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.
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
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.
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.
## Resource Properties ### UsageCharge * created_at: The date and time (ISO 8601 format) when the usage charge was created. * Type: x-string * Example: "2013-06-27T08:48:27-04:00" * description: The description of the usage charge. * Type: x-string * Example: "Super Mega Plan 1000 emails" * id: The ID of the usage charge. * Type: x-string * Example: 675931192 * price: The price of the usage charge. * Type: string * Example: "1" * recurring_application_charge_id: The ID of the recurring application charge that the usage charge belongs to. * Type: x-string * Example: 527669426 * updated_at: The date and time (ISO 8601 format) when the usage charge was last updated. * Type: x-string * Example: "2013-06-27T08:48:27-04:00" * currency: The currency of the price of the usage charge. * Type: x-string * Example: "USD" ## Creates a usage charge Creates a usage charge ### Endpoint /admin/api/#{api_version}/recurring_application_charges/{recurring_application_charge_id}/usage_charges.json (POST) ### Parameters * api_version (required): * recurring_application_charge_id (required): ### Responses #### 201 Creates a usage charge Examples: ##### Create a new usage charge Request: ``` POST /admin/api/unstable/recurring_application_charges/455696195/usage_charges.json {"usage_charge":{"description":"Super Mega Plan 1000 emails","price":"1.00"}} ``` Response: ``` HTTP/1.1 201 Created {"usage_charge":{"id":1034618212,"description":"Super Mega Plan 1000 emails","price":"1.00","created_at":"2025-01-02T11:20:36-05:00","currency":"USD","balance_used":"11.0","balance_remaining":"89.00","risk_level":0}} ``` #### 422 Creates a usage charge Examples: ##### Trying to create a charge which exceeds the remaining balance will return an error Request: ``` POST /admin/api/unstable/recurring_application_charges/455696195/usage_charges.json {"usage_charge":{"description":"Super Mega Plan 1000 emails","price":9999}} ``` Response: ``` HTTP/1.1 422 Unprocessable Entity {"errors":{"base":["Total price exceeds balance remaining"]}} ``` ##### Trying to create a charge without a price or a description will return an error Request: ``` POST /admin/api/unstable/recurring_application_charges/455696195/usage_charges.json {"usage_charge":{"description":""}} ``` Response: ``` HTTP/1.1 422 Unprocessable Entity {"errors":{"description":["can't be blank"],"price":["must be greater than zero"]}} ``` ## Retrieves a list of usage charges Retrieves a list of usage charges ### Endpoint /admin/api/#{api_version}/recurring_application_charges/{recurring_application_charge_id}/usage_charges.json (GET) ### Parameters * api_version (required): * recurring_application_charge_id (required): * fields: A comma-separated list of fields to include in the response. ### Responses #### 200 Retrieves a list of usage charges Examples: ##### Retrieve all usage charges Request: ``` GET /admin/api/unstable/recurring_application_charges/455696195/usage_charges.json ``` Response: ``` HTTP/1.1 200 OK {"usage_charges":[{"id":1034618207,"description":"Super Mega Plan Add-ons","price":"10.00","created_at":"2025-01-02T11:20:34-05:00","currency":"USD","balance_used":"10.0","balance_remaining":"90.00","risk_level":0}]} ``` ## Retrieves a single charge Retrieves a single charge ### Endpoint /admin/api/#{api_version}/recurring_application_charges/{recurring_application_charge_id}/usage_charges/{usage_charge_id}.json (GET) ### Parameters * api_version (required): * recurring_application_charge_id (required): * usage_charge_id (required): * fields: A comma-separated list of fields to include in the response. ### Responses #### 200 Retrieves a single charge Examples: ##### Retrieve a single charge Request: ``` GET /admin/api/unstable/recurring_application_charges/455696195/usage_charges/1034618209.json ``` Response: ``` HTTP/1.1 200 OK {"usage_charge":{"id":1034618209,"description":"Super Mega Plan Add-ons","price":"10.00","created_at":"2025-01-02T11:20:35-05:00","currency":"USD","balance_used":"10.0","balance_remaining":"90.00","risk_level":0}} ```