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.

Choose a version:

UsageCharge

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?

Endpoints

post
/admin/api/latest/recurring_application_charges/{recurring_application_charge_id}/usage_charges.json
Creates a usage charge
appUsageRecordCreate
get
/admin/api/latest/recurring_application_charges/{recurring_application_charge_id}/usage_charges.json
Retrieves a list of usage charges
nodes
get
/admin/api/latest/recurring_application_charges/{recurring_application_charge_id}/usage_charges/{usage_charge_id}.json
Retrieves a single charge
node

Anchor to

The UsageCharge resource

Anchor to

Properties

created_at

createdAt

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

description

The description of the usage charge.

The ID of the usage charge.

price

string

price

The price of the usage charge.

recurring_application_charge_id

subscriptionLineItem

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

price

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"

}

Anchor to POST request, Creates a usage charge
post
Creates a usage charge

appUsageRecordCreate

Creates a usage charge

Anchor to Parameters of Creates a usage chargeParameters

api_version

string

required

recurring_application_charge_id

string

required

Was this section helpful?

Anchor to post-recurring-application-charges-recurring-application-charge-id-usage-charges-examplesExamples

Create a new usage charge

Path parameters

recurring_application_charge_id=455696195

string

required

Request body

usage_charge

Usage_charge resource

Show usage_charge properties

usage_charge.description:"Super Mega Plan 1000 emails"

The description of the usage charge.

usage_charge.price:"1.00"

string

The price of the usage charge.

Trying to create a charge which exceeds the remaining balance will return an error

Path parameters

recurring_application_charge_id=455696195

string

required

Request body

usage_charge

Usage_charge resource

Show usage_charge properties

usage_charge.description:"Super Mega Plan 1000 emails"

The description of the usage charge.

usage_charge.price:9999

string

The price of the usage charge.

Trying to create a charge without a price or a description will return an error

Path parameters

recurring_application_charge_id=455696195

string

required

Request body

usage_charge

Usage_charge resource

Show usage_charge properties

usage_charge.description:""

The description of the usage charge.

Was this section helpful?

post

/admin/api/2026-07/recurring_application_charges/455696195/usage_charges.json

curl -d '{"usage_charge":{"description":"Super Mega Plan 1000 emails","price":"1.00"}}' \

-X POST "https://your-development-store.myshopify.com/admin/api/2026-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": 1034618207,

"description": "Super Mega Plan 1000 emails",

"price": "1.00",

"created_at": "2026-07-06T10:59:35-04:00",

"currency": "USD",

"balance_used": "1.0",

"balance_remaining": "99.00",

"risk_level": 0

}

examples

Create a new usage charge

curl -d '{"usage_charge":{"description":"Super Mega Plan 1000 emails","price":"1.00"}}' \
-X POST "https://your-development-store.myshopify.com/admin/api/2026-07/recurring_application_charges/455696195/usage_charges.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"

use Shopify\Rest\Admin2026_07\UsageCharge;
use Shopify\Utils;

$this->test_session = Utils::loadCurrentSession(
    $requestHeaders,
    $requestCookies,
    $isOnline
);

$usage_charge = new UsageCharge($this->test_session);
$usage_charge->description = "Super Mega Plan 1000 emails";
$usage_charge->price = "1.00";
$usage_charge->post(
    455696195,
);

use Shopify\Rest\Admin2026_07\UsageCharge;
use Shopify\Utils;

$this->test_session = Utils::loadCurrentSession(
    $requestHeaders,
    $requestCookies,
    $isOnline
);

$usage_charge = new UsageCharge($this->test_session);
$usage_charge->description = "Super Mega Plan 1000 emails";
$usage_charge->price = "1.00";
$usage_charge->post(
    test_session,
    455696195,
);

use Shopify\Rest\Admin2026_07\UsageCharge;
use Shopify\Utils;

$this->test_session = Utils::loadCurrentSession(
    $requestHeaders,
    $requestCookies,
    $isOnline
);

$usage_charge = new UsageCharge($this->test_session);
$usage_charge->description = "Super Mega Plan 1000 emails";
$usage_charge->price = "1.00";
$usage_charge->post(
    455696195,
);

response

HTTP/1.1 201 Created{"usage_charge":{"id":1034618207,"description":"Super Mega Plan 1000 emails","price":"1.00","created_at":"2026-07-06T10:59:35-04:00","currency":"USD","balance_used":"1.0","balance_remaining":"99.00","risk_level":0}}

Trying to create a charge which exceeds the remaining balance will return an error

curl -d '{"usage_charge":{"description":"Super Mega Plan 1000 emails","price":9999}}' \
-X POST "https://your-development-store.myshopify.com/admin/api/2026-07/recurring_application_charges/455696195/usage_charges.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"

use Shopify\Rest\Admin2026_07\UsageCharge;
use Shopify\Utils;

$this->test_session = Utils::loadCurrentSession(
    $requestHeaders,
    $requestCookies,
    $isOnline
);

$usage_charge = new UsageCharge($this->test_session);
$usage_charge->description = "Super Mega Plan 1000 emails";
$usage_charge->price = 9999;
$usage_charge->post(
    455696195,
);

use Shopify\Rest\Admin2026_07\UsageCharge;
use Shopify\Utils;

$this->test_session = Utils::loadCurrentSession(
    $requestHeaders,
    $requestCookies,
    $isOnline
);

$usage_charge = new UsageCharge($this->test_session);
$usage_charge->description = "Super Mega Plan 1000 emails";
$usage_charge->price = 9999;
$usage_charge->post(
    test_session,
    455696195,
);

use Shopify\Rest\Admin2026_07\UsageCharge;
use Shopify\Utils;

$this->test_session = Utils::loadCurrentSession(
    $requestHeaders,
    $requestCookies,
    $isOnline
);

$usage_charge = new UsageCharge($this->test_session);
$usage_charge->description = "Super Mega Plan 1000 emails";
$usage_charge->price = 9999;
$usage_charge->post(
    455696195,
);

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

curl -d '{"usage_charge":{"description":""}}' \
-X POST "https://your-development-store.myshopify.com/admin/api/2026-07/recurring_application_charges/455696195/usage_charges.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"

use Shopify\Rest\Admin2026_07\UsageCharge;
use Shopify\Utils;

$this->test_session = Utils::loadCurrentSession(
    $requestHeaders,
    $requestCookies,
    $isOnline
);

$usage_charge = new UsageCharge($this->test_session);
$usage_charge->description = "";
$usage_charge->post(
    455696195,
);

use Shopify\Rest\Admin2026_07\UsageCharge;
use Shopify\Utils;

$this->test_session = Utils::loadCurrentSession(
    $requestHeaders,
    $requestCookies,
    $isOnline
);

$usage_charge = new UsageCharge($this->test_session);
$usage_charge->description = "";
$usage_charge->post(
    test_session,
    455696195,
);

use Shopify\Rest\Admin2026_07\UsageCharge;
use Shopify\Utils;

$this->test_session = Utils::loadCurrentSession(
    $requestHeaders,
    $requestCookies,
    $isOnline
);

$usage_charge = new UsageCharge($this->test_session);
$usage_charge->description = "";
$usage_charge->post(
    455696195,
);

response

HTTP/1.1 422 Unprocessable Entity{"errors":{"description":["can't be blank"],"price":["must be greater than zero"]}}

Anchor to GET request, Retrieves a list of usage charges
get
Retrieves a list of usage charges

nodes

Retrieves a list of usage charges

Anchor to Parameters of Retrieves a list of usage chargesParameters

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?

Anchor to get-recurring-application-charges-recurring-application-charge-id-usage-charges-examplesExamples

Retrieve all usage charges

Path parameters

recurring_application_charge_id=455696195

string

required

Was this section helpful?

get

/admin/api/2026-07/recurring_application_charges/455696195/usage_charges.json

curl -X GET "https://your-development-store.myshopify.com/admin/api/2026-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": 1034618206,

"description": "Super Mega Plan Add-ons",

"price": "10.00",

"created_at": "2026-07-06T10:59:33-04:00",

"currency": "USD",

"balance_used": "10.0",

"balance_remaining": "90.00",

"risk_level": 0

}

]

}

examples

Retrieve all usage charges

curl -X GET "https://your-development-store.myshopify.com/admin/api/2026-07/recurring_application_charges/455696195/usage_charges.json" \
-H "X-Shopify-Access-Token: {access_token}"

use Shopify\Rest\Admin2026_07\UsageCharge;
use Shopify\Utils;

$this->test_session = Utils::loadCurrentSession(
    $requestHeaders,
    $requestCookies,
    $isOnline
);

$response = admin.rest.resources.UsageCharge::all(
    455696195,
);

use Shopify\Rest\Admin2026_07\UsageCharge;
use Shopify\Utils;

$this->test_session = Utils::loadCurrentSession(
    $requestHeaders,
    $requestCookies,
    $isOnline
);

$response = UsageCharge::all(
    455696195,
);

use Shopify\Rest\Admin2026_07\UsageCharge;
use Shopify\Utils;

$this->test_session = Utils::loadCurrentSession(
    $requestHeaders,
    $requestCookies,
    $isOnline
);

$response = UsageCharge::all(
    455696195,
);

response

HTTP/1.1 200 OK{"usage_charges":[{"id":1034618206,"description":"Super Mega Plan Add-ons","price":"10.00","created_at":"2026-07-06T10:59:33-04:00","currency":"USD","balance_used":"10.0","balance_remaining":"90.00","risk_level":0}]}

Anchor to GET request, Retrieves a single charge
get
Retrieves a single charge

node

Retrieves a single charge

Anchor to Parameters of Retrieves a single chargeParameters

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?

Anchor to get-recurring-application-charges-recurring-application-charge-id-usage-charges-usage-charge-id-examplesExamples

Retrieve a single charge

Was this section helpful?

get

/admin/api/2026-07/recurring_application_charges/455696195/usage_charges/1034618208.json

curl -X GET "https://your-development-store.myshopify.com/admin/api/2026-07/recurring_application_charges/455696195/usage_charges/1034618208.json" \

-H "X-Shopify-Access-Token: {access_token}"

{}

Response

JSON

HTTP/1.1 200 OK

{

"usage_charge": {

"id": 1034618208,

"description": "Super Mega Plan Add-ons",

"price": "10.00",

"created_at": "2026-07-06T10:59:35-04:00",

"currency": "USD",

"balance_used": "10.0",

"balance_remaining": "90.00",

"risk_level": 0

}

examples

Retrieve a single charge

curl -X GET "https://your-development-store.myshopify.com/admin/api/2026-07/recurring_application_charges/455696195/usage_charges/1034618208.json" \
-H "X-Shopify-Access-Token: {access_token}"

use Shopify\Rest\Admin2026_07\UsageCharge;
use Shopify\Utils;

$this->test_session = Utils::loadCurrentSession(
    $requestHeaders,
    $requestCookies,
    $isOnline
);

$result = admin.rest.resources.UsageCharge::find(
    455696195,
    1034618208,
);

use Shopify\Rest\Admin2026_07\UsageCharge;
use Shopify\Utils;

$this->test_session = Utils::loadCurrentSession(
    $requestHeaders,
    $requestCookies,
    $isOnline
);

$result = UsageCharge::find(
    455696195,
    1034618208,
);

use Shopify\Rest\Admin2026_07\UsageCharge;
use Shopify\Utils;

$this->test_session = Utils::loadCurrentSession(
    $requestHeaders,
    $requestCookies,
    $isOnline
);

$result = UsageCharge::find(
    455696195,
    1034618208,
);

response

HTTP/1.1 200 OK{"usage_charge":{"id":1034618208,"description":"Super Mega Plan Add-ons","price":"10.00","created_at":"2026-07-06T10:59:35-04:00","currency":"USD","balance_used":"10.0","balance_remaining":"90.00","risk_level":0}}

UsageCharge

Creating usage charges

Charging for usage only

Setting capped amounts

Endpoints

The UsageCharge resource

Properties

The UsageCharge resource

Anchor to POST request, Creates a usage chargepostCreates a usage charge

Anchor to Parameters of Creates a usage chargeParameters

Anchor to post-recurring-application-charges-recurring-application-charge-id-usage-charges-examplesExamples

Response

examples

Create a new usage charge

response

Trying to create a charge which exceeds the remaining balance will return an error

response

Trying to create a charge without a price or a description will return an error

response

Anchor to GET request, Retrieves a list of usage chargesgetRetrieves a list of usage charges

Anchor to Parameters of Retrieves a list of usage chargesParameters

Anchor to get-recurring-application-charges-recurring-application-charge-id-usage-charges-examplesExamples

Response

examples

Retrieve all usage charges

response

Anchor to GET request, Retrieves a single chargegetRetrieves a single charge

Anchor to Parameters of Retrieves a single chargeParameters

Anchor to get-recurring-application-charges-recurring-application-charge-id-usage-charges-usage-charge-id-examplesExamples

Response

examples

Retrieve a single charge

response

Anchor to POST request, Creates a usage charge
post
Creates a usage charge

Anchor to GET request, Retrieves a list of usage charges
get
Retrieves a list of usage charges

Anchor to GET request, Retrieves a single charge
get
Retrieves a single charge