# 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}}
```