# UsageCharge <p>You can use the UsageCharge resource to add variable usage fees to an existing <a href="/docs/admin-api/rest/reference/billing/recurringapplicationcharge">recurring application charge</a>. You can use these resources to support billing plans that vary from month to month, with or without a monthly recurring fee. <h2>Creating usage charges</h2> <p>To use the UsageCharge resource, first create a <a href="/docs/admin-api/rest/reference/billing/recurringapplicationcharge">recurring application charge</a>. This returns the ID that you'll need to create an associated usage charge.</p> <p>To create the usage charge, send a POST request, where <code>{id}</code> represents the ID of the previously created recurring application charge.<p> <div id="callback-url" class="api-endpoint"> <div class="api-endpoint-request"> <pre class="api-endpoint-request-type api-endpoint-request-type-get">POST</pre> /admin/recurring_application_charges/{id}/usage_charges.json </div> </div> <h3>Charging for usage only</h3> <p>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 <a href="/docs/admin-api/rest/reference/billing/recurringapplicationcharge/">recurring application charge</a> with a price of $0.00 and then apply the usage charge.</p> <p>You need to include the <code>capped_amount</code> and <code>terms</code> properties in the body of your request when you create a recurring application charge with a price of $0.00.</p> <h2>Setting capped amounts</h2> <p>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.</p> <p> <div class="note"> <h4>Note</h4> <p>The capped amount setting is applicable on a per billing cycle basis (30 days), and remains in effect unless updated.</p> </div> <p>For step-by-step guidance that walks through this flow using examples, see our <a href="/apps/billing/models">implementation guide</a>.</p> ## Resource Properties ### UsageCharge * created_at: The date and time (<a href="https://en.wikipedia.org/wiki/ISO_8601" target="_blank">ISO 8601</a> 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 (<a href="https://en.wikipedia.org/wiki/ISO_8601" target="_blank">ISO 8601</a> 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}} ```