The REST Admin API is a legacy API as of October 1, 2024. Starting April 1, 2025, all new public apps must be built exclusively with the GraphQL Admin API. For details and migration steps, visit our migration guide.
Usage
You can use the UsageCharge resource to add variable usage fees to an existing recurring application charge. You can use these resources to support billing plans that vary from month to month, with or without a monthly recurring fee.
Creating usage charges
To use the UsageCharge resource, first create a recurring application charge. This returns the ID that you'll need to create an associated usage charge.
To create the usage charge, send a POST request, where {id} represents the ID of the previously created recurring application charge.
POST/admin/recurring_application_charges/{id}/usage_charges.json
Charging for usage only
A common billing scenario is to charge only usage-based fees, without a flat recurring monthly fee. To charge only usage-based fees without a recurring monthly fee, first create a recurring application charge with a price of $0.00 and then apply the usage charge.
You need to include the capped_amount and terms properties in the body of your request
when you create a recurring application charge with a price of $0.00.
Setting capped amounts
You can use the RecurringApplicationCharge resource to specify a capped amount that applies to usage-based billing. This prevents the customer from being charged for any usage over and above the capped amount. To implement capped amount billing, create a recurring application charge with the capped dollar amount, and then create the associated usage charge.
The capped amount setting is applicable on a per billing cycle basis (30 days), and remains in effect unless updated.
For step-by-step guidance that walks through this flow using examples, see our implementation guide.
Endpoints
- post/admin/api/latest/recurring_
application_ charges/{recurring_ application_ charge_ id}/usage_ charges. json Creates a usage charge - get/admin/api/latest/recurring_
application_ charges/{recurring_ application_ charge_ id}/usage_ charges. json Retrieves a list of usage charges - get/admin/api/latest/recurring_
application_ charges/{recurring_ application_ charge_ id}/usage_ charges/{usage_ charge_ id}. json Retrieves a single charge
The UsageCharge resource
Properties
The description of the usage charge.
The ID of the usage charge.
The price of the usage charge.
The ID of the recurring application charge that the usage charge belongs to.
The date and time (ISO 8601 format) when the usage charge was last updated.
The currency of the price of the usage charge.
The UsageCharge resource
Anchor to POST request, Creates a usage chargepostCreates a usage charge
Creates a usage charge
Create a new usage charge
Create a new usage charge
Show usage_charge properties
The description of the usage charge.
The price of the usage charge.
Trying to create a charge which exceeds the remaining balance will return an error
Trying to create a charge which exceeds the remaining balance will return an error
Show usage_charge properties
The description of the usage charge.
The price of the usage charge.
Trying to create a charge without a price or a description will return an error
Trying to create a charge without a price or a description will return an error
Show usage_charge properties
The description of the usage charge.
/admin/api/2025-07/recurring_
Response
Anchor to GET request, Retrieves a list of usage chargesgetRetrieves a list of usage charges
Retrieves a list of usage charges
A comma-separated list of fields to include in the response.
Retrieve all usage charges
Retrieve all usage charges
/admin/api/2025-07/recurring_
Response
Anchor to GET request, Retrieves a single chargegetRetrieves a single charge
Retrieves a single charge
A comma-separated list of fields to include in the response.
Retrieve a single charge
Retrieve a single charge