Skip to contentSkip to navigationSkip to topbar
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

base-url page anchor
https://preview.twilio.com/marketplace

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.


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

installed-add-ons-usage-subresource page anchor

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


ParameterDescription
QuantityRequired. 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.

Charging a customer for add-on usage

charging-a-customer-for-add-on-usage page anchor
1
curl -X POST "https://preview.twilio.com/marketplace/InstalledAddOns/XExxxxxxxxxxxxxxxxxxxxxxx/Usage" \
2
--data-urlencode "Quantity=10" \
3
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Response

1
202 Accepted
2

Crediting a customer for add-on usage previously posted

crediting-a-customer-for-add-on-usage-previously-posted page anchor
1
curl -X POST "https://preview.twilio.com/marketplace/InstalledAddOns/XExxxxxxxxxxxxxxxxxxxxxxx/Usage" \
2
--data-urlencode "Quantity=-10" \
3
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Response

1
202 Accepted
2

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 codeDebugger notificationDescription
404WarningThe Add-on is not installed on the customer account or no Module is found with the Installation SID.
403WarningThe Account Sid in the API request does not match with the Partner Account Sid attached to the Add-on.
403WarningThe Add-on is not set up to accept Manual Usage Reporting .
403WarningThe Add-on is not in one of the Marketing Preview, Private Beta, or Active state.
400WarningQuantity is either null, empty, or 0.
500ErrorError received while generating a billing event.
202N/AThe request is successful, and a billing event is generated.

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.