The REST Admin API is a legacy API as of October 1, 2024. All apps and integrations should be built with the GraphQL Admin API. For details and migration steps, visit our migration guide.

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.

Note

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.

Was this section helpful?

Properties

created_at
The date and time (ISO 8601 format) when the usage charge was created.

description
The description of the usage charge.

id
->id
The ID of the usage charge.

price
string
The price of the usage charge.

recurring_application_charge_id
The ID of the recurring application charge that the usage charge belongs to.

updated_at
The date and time (ISO 8601 format) when the usage charge was last updated.

currency
The currency of the price of the usage charge.

Was this section helpful?
{}The UsageCharge resource
{
  "created_at": "2013-06-27T08:48:27-04:00",
  "description": "Super Mega Plan 1000 emails",
  "id": 675931192,
  "price": "1",
  "recurring_application_charge_id": 527669426,
  "updated_at": "2013-06-27T08:48:27-04:00",
  "currency": "USD"
}

Creates a usage charge

api_version
string
required

recurring_application_charge_id
string
required

Was this section helpful?
Path parameters
recurringapplicationchargeid=455696195
string
required
Request body
usagecharge
Usage_charge resource
Was this section helpful?
post
/admin/api/2024-07/recurring_application_charges/455696195/usage_charges.json
Copy
curl -d '{"usage_charge":{"description":"Super Mega Plan 1000 emails","price":"1.00"}}' \
-X POST "https://your-development-store.myshopify.com/admin/api/2024-07/recurring_application_charges/455696195/usage_charges.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"
{}Response
JSON
HTTP/1.1 201 Created
{
  "usage_charge": {
    "id": 1034618212,
    "description": "Super Mega Plan 1000 emails",
    "price": "1.00",
    "created_at": "2024-09-19T10:12:16-04:00",
    "currency": "USD",
    "balance_used": "11.0",
    "balance_remaining": "89.00",
    "risk_level": 0
  }
}

Retrieves a list of usage charges

api_version
string
required

recurring_application_charge_id
string
required

fields
A comma-separated list of fields to include in the response.

Was this section helpful?
Path parameters
recurringapplicationchargeid=455696195
string
required
Was this section helpful?
get
/admin/api/2024-07/recurring_application_charges/455696195/usage_charges.json
Copy
curl -X GET "https://your-development-store.myshopify.com/admin/api/2024-07/recurring_application_charges/455696195/usage_charges.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
HTTP/1.1 200 OK
{
  "usage_charges": [
    {
      "id": 1034618210,
      "description": "Super Mega Plan Add-ons",
      "price": "10.00",
      "created_at": "2024-09-19T10:12:15-04:00",
      "currency": "USD",
      "balance_used": "10.0",
      "balance_remaining": "90.00",
      "risk_level": 0
    }
  ]
}

Retrieves a single charge

api_version
string
required

recurring_application_charge_id
string
required

usage_charge_id
string
required

fields
A comma-separated list of fields to include in the response.

Was this section helpful?
Was this section helpful?
get
/admin/api/2024-07/recurring_application_charges/455696195/usage_charges/1034618207.json
Copy
curl -X GET "https://your-development-store.myshopify.com/admin/api/2024-07/recurring_application_charges/455696195/usage_charges/1034618207.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
HTTP/1.1 200 OK
{
  "usage_charge": {
    "id": 1034618207,
    "description": "Super Mega Plan Add-ons",
    "price": "10.00",
    "created_at": "2024-09-19T10:12:13-04:00",
    "currency": "USD",
    "balance_used": "10.0",
    "balance_remaining": "90.00",
    "risk_level": 0
  }
}