On this page

Installed Add-ons Usage Subresource

(warning)

Migrate from Preview to v1

Marketplace v1 API is now available, and the Preview API for this Resource will be discontinued in December 2024. See the API Preview to v1 Migration Guide for more information.

(information)

Info

If you already have a published Add-on and would like access to this API resource, reach out to Twilio.

Base URL

https://preview.twilio.com/marketplace

Authentication

The Module resource uses the same HTTP Basic Authentication as other Twilio APIs. Use your Twilio account SID as your username and your Auth Token as your password.

Prerequisite

This APi endpoint requires Twilio to enable manual usage reporting for an add-on that you own. To verify that it's been enabled, navigate to Marketplace > Catalog > Add-on (select your add-on) in the Twilio Console. Check that "Manual Usage Reporting" is added as a category.

Installed Add-ons Usage subresource

The Installed Add-ons Usage subresource allows Twilio Marketplace Partners to manually report customer usage on add-ons that they own.

Properties

Parameter	Description
Quantity	Required. A number greater than or less than zero that represents usage of a specific add-on installation. When set to a value greater than zero, the update is reported as usage on the customer account, and the customer will be charged. See Charging a customer for Add-on Usage as an example.When set to a value less than zero, the update is reported as a credit on the customer account. This should only be used to correct a reporting error with a previous API call.

Parameter

Description

Quantity

Required. A number greater than or less than zero that represents usage of a specific add-on installation. When set to a value greater than zero, the update is reported as usage on the customer account, and the customer will be charged. See Charging a customer for Add-on Usage as an example.When set to a value less than zero, the update is reported as a credit on the customer account. This should only be used to correct a reporting error with a previous API call.

Example requests

Charging a customer for add-on usage

1curl -X POST "https://preview.twilio.com/marketplace/InstalledAddOns/XExxxxxxxxxxxxxxxxxxxxxxx/Usage" \
2--data-urlencode "Quantity=10" \
3-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Response

1202 Accepted
2

Crediting a customer for add-on usage previously posted

1curl -X POST "https://preview.twilio.com/marketplace/InstalledAddOns/XExxxxxxxxxxxxxxxxxxxxxxx/Usage" \
2--data-urlencode "Quantity=-10" \
3-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Response

1202 Accepted
2

Response Codes

Here is a list of common scenarios along with associated HTTP response codes, Twilio Debugger notifications, and messages that the API may return.

HTTP response code	Debugger notification	Description
404	Warning	The Add-on is not installed on the customer account or no Module is found with the Installation SID.
403	Warning	The Account Sid in the API request does not match with the Partner Account Sid attached to the Add-on.
403	Warning	The Add-on is not set up to accept Manual Usage Reporting .
403	Warning	The Add-on is not in one of the Marketing Preview, Private Beta, or Active state.
400	Warning	Quantity is either null, empty, or 0.
500	Error	Error received while generating a billing event.
202	N/A	The request is successful, and a billing event is generated.