---
title: UsageCharge
description: Charge varying amounts based on the monthly usage of your app.
api_version: 2025-10
api_name: admin-rest
api_type: rest
source_url:
  html: https://shopify.dev/docs/api/admin-rest/latest/resources/usagecharge
  md: https://shopify.dev/docs/api/admin-rest/latest/resources/usagecharge.md
---

![](https://shopify.dev/images/logos/GraphQL.svg)![](https://shopify.dev/images/logos/GraphQL-dark.svg)

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](https://shopify.dev/docs/api/admin-graphql). For details and migration steps, visit our [migration guide](https://shopify.dev/docs/apps/build/graphql/migrate).

# Usage​Charge

You can use the UsageCharge resource to add variable usage fees to an existing [recurring application charge](https://shopify.dev/docs/admin-api/rest/reference/billing/recurringapplicationcharge). 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](https://shopify.dev/docs/admin-api/rest/reference/billing/recurringapplicationcharge). 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](https://shopify.dev/docs/admin-api/rest/reference/billing/recurringapplicationcharge/) 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](https://shopify.dev/apps/billing/models).

\#

## Endpoints

* [post](https://shopify.dev/docs/api/admin-rest/latest/resources/usagecharge#post-recurring-application-charges-recurring-application-charge-id-usage-charges)

  [/admin/api/latest/recurring\_​application\_​charges/{recurring\_​application\_​charge\_​id}/usage\_​charges.​json](https://shopify.dev/docs/api/admin-rest/latest/resources/usagecharge#post-recurring-application-charges-recurring-application-charge-id-usage-charges)

  Creates a usage charge

  [![](https://shopify.dev/images/logos/GraphQL.svg)![](https://shopify.dev/images/logos/GraphQL-dark.svg)](https://shopify.dev/docs/api/admin-graphql/latest/mutations/appUsageRecordCreate?example=creates-a-usage-charge)

  [appUsageRecordCreate](https://shopify.dev/docs/api/admin-graphql/latest/mutations/appUsageRecordCreate?example=creates-a-usage-charge)

* [get](https://shopify.dev/docs/api/admin-rest/latest/resources/usagecharge#get-recurring-application-charges-recurring-application-charge-id-usage-charges)

  [/admin/api/latest/recurring\_​application\_​charges/{recurring\_​application\_​charge\_​id}/usage\_​charges.​json](https://shopify.dev/docs/api/admin-rest/latest/resources/usagecharge#get-recurring-application-charges-recurring-application-charge-id-usage-charges)

  Retrieves a list of usage charges

  [![](https://shopify.dev/images/logos/GraphQL.svg)![](https://shopify.dev/images/logos/GraphQL-dark.svg)](https://shopify.dev/docs/api/admin-graphql/latest/queries/nodes)

  [nodes](https://shopify.dev/docs/api/admin-graphql/latest/queries/nodes)

* [get](https://shopify.dev/docs/api/admin-rest/latest/resources/usagecharge#get-recurring-application-charges-recurring-application-charge-id-usage-charges-usage-charge-id)

  [/admin/api/latest/recurring\_​application\_​charges/{recurring\_​application\_​charge\_​id}/usage\_​charges/{usage\_​charge\_​id}.​json](https://shopify.dev/docs/api/admin-rest/latest/resources/usagecharge#get-recurring-application-charges-recurring-application-charge-id-usage-charges-usage-charge-id)

  Retrieves a single charge

  [![](https://shopify.dev/images/logos/GraphQL.svg)![](https://shopify.dev/images/logos/GraphQL-dark.svg)](https://shopify.dev/docs/api/admin-graphql/latest/queries/node)

  [node](https://shopify.dev/docs/api/admin-graphql/latest/queries/node)

***

## The UsageCharge resource

### Properties

***

created\_at

->

[![](https://shopify.dev/images/logos/GraphQL.svg)![](https://shopify.dev/images/logos/GraphQL-dark.svg)](https://shopify.dev/docs/api/admin-graphql/latest/objects/AppUsageRecord#field-AppUsageRecord.fields.createdAt)

[createdAt](https://shopify.dev/docs/api/admin-graphql/latest/objects/AppUsageRecord#field-AppUsageRecord.fields.createdAt)

The date and time ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format) when the usage charge was created.

***

description

->

[![](https://shopify.dev/images/logos/GraphQL.svg)![](https://shopify.dev/images/logos/GraphQL-dark.svg)](https://shopify.dev/docs/api/admin-graphql/latest/objects/AppUsageRecord#field-AppUsageRecord.fields.description)

[description](https://shopify.dev/docs/api/admin-graphql/latest/objects/AppUsageRecord#field-AppUsageRecord.fields.description)

The description of the usage charge.

***

id

->

[![](https://shopify.dev/images/logos/GraphQL.svg)![](https://shopify.dev/images/logos/GraphQL-dark.svg)](https://shopify.dev/docs/api/admin-graphql/latest/objects/AppUsageRecord#field-AppUsageRecord.fields.id)

[id](https://shopify.dev/docs/api/admin-graphql/latest/objects/AppUsageRecord#field-AppUsageRecord.fields.id)

The ID of the usage charge.

***

price

string

->

[![](https://shopify.dev/images/logos/GraphQL.svg)![](https://shopify.dev/images/logos/GraphQL-dark.svg)](https://shopify.dev/docs/api/admin-graphql/latest/objects/AppUsageRecord#field-AppUsageRecord.fields.price)

[price](https://shopify.dev/docs/api/admin-graphql/latest/objects/AppUsageRecord#field-AppUsageRecord.fields.price)

The price of the usage charge.

***

recurring\_application\_charge\_id

->

[![](https://shopify.dev/images/logos/GraphQL.svg)![](https://shopify.dev/images/logos/GraphQL-dark.svg)](https://shopify.dev/docs/api/admin-graphql/latest/objects/AppUsageRecord#field-AppUsageRecord.fields.subscriptionLineItem)

[subscriptionLineItem](https://shopify.dev/docs/api/admin-graphql/latest/objects/AppUsageRecord#field-AppUsageRecord.fields.subscriptionLineItem)

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

***

updated\_at

The date and time ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format) when the usage charge was last updated.

***

currency

->

[![](https://shopify.dev/images/logos/GraphQL.svg)![](https://shopify.dev/images/logos/GraphQL-dark.svg)](https://shopify.dev/docs/api/admin-graphql/latest/objects/AppUsageRecord#field-AppUsageRecord.fields.price)

[price](https://shopify.dev/docs/api/admin-graphql/latest/objects/AppUsageRecord#field-AppUsageRecord.fields.price)

The currency of the price of the usage charge.

***

{}

## The UsageCharge resource

```json
{
  "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"
}
```

***

## postCreates a usage charge

[![](https://shopify.dev/images/logos/GraphQL.svg)![](https://shopify.dev/images/logos/GraphQL-dark.svg)](https://shopify.dev/docs/api/admin-graphql/latest/mutations/appUsageRecordCreate?example=creates-a-usage-charge)

[appUsageRecordCreate](https://shopify.dev/docs/api/admin-graphql/latest/mutations/appUsageRecordCreate?example=creates-a-usage-charge)

Creates a usage charge

### Parameters

***

api\_version

string

required

***

recurring\_application\_charge\_id

string

required

***

### Examples

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.

post

## /admin/api/2025-10/recurring\_​application\_​charges/455696195/usage\_​charges.​json

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

{}

## Response

JSON

```json
HTTP/1.1 201 Created
{
  "usage_charge": {
    "id": 1034618209,
    "description": "Super Mega Plan 1000 emails",
    "price": "1.00",
    "created_at": "2025-10-01T14:32:00-04:00",
    "currency": "USD",
    "balance_used": "11.0",
    "balance_remaining": "89.00",
    "risk_level": 0
  }
}
```

### examples

* #### Create a new usage charge

  #####

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

  #####

  ```remix
  const { admin, session } = await authenticate.admin(request);

  const usage_charge = new admin.rest.resources.UsageCharge({session: session});

  usage_charge.recurring_application_charge_id = 455696195;
  usage_charge.description = "Super Mega Plan 1000 emails";
  usage_charge.price = "1.00";
  await usage_charge.save({
    update: true,
  });
  ```

  #####

  ```ruby
  # Session is activated via Authentication
  test_session = ShopifyAPI::Context.active_session

  usage_charge = ShopifyAPI::UsageCharge.new(session: test_session)
  usage_charge.recurring_application_charge_id = 455696195
  usage_charge.description = "Super Mega Plan 1000 emails"
  usage_charge.price = "1.00"
  usage_charge.save!
  ```

  #####

  ```node
  // Session is built by the OAuth process

  const usage_charge = new shopify.rest.UsageCharge({session: session});
  usage_charge.recurring_application_charge_id = 455696195;
  usage_charge.description = "Super Mega Plan 1000 emails";
  usage_charge.price = "1.00";
  await usage_charge.save({
    update: true,
  });
  ```

  #### response

  ```json
  HTTP/1.1 201 Created{"usage_charge":{"id":1034618209,"description":"Super Mega Plan 1000 emails","price":"1.00","created_at":"2025-10-01T14:32:00-04:00","currency":"USD","balance_used":"11.0","balance_remaining":"89.00","risk_level":0}}
  ```

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

  #####

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

  #####

  ```remix
  const { admin, session } = await authenticate.admin(request);

  const usage_charge = new admin.rest.resources.UsageCharge({session: session});

  usage_charge.recurring_application_charge_id = 455696195;
  usage_charge.description = "Super Mega Plan 1000 emails";
  usage_charge.price = 9999;
  await usage_charge.save({
    update: true,
  });
  ```

  #####

  ```ruby
  # Session is activated via Authentication
  test_session = ShopifyAPI::Context.active_session

  usage_charge = ShopifyAPI::UsageCharge.new(session: test_session)
  usage_charge.recurring_application_charge_id = 455696195
  usage_charge.description = "Super Mega Plan 1000 emails"
  usage_charge.price = 9999
  usage_charge.save!
  ```

  #####

  ```node
  // Session is built by the OAuth process

  const usage_charge = new shopify.rest.UsageCharge({session: session});
  usage_charge.recurring_application_charge_id = 455696195;
  usage_charge.description = "Super Mega Plan 1000 emails";
  usage_charge.price = 9999;
  await usage_charge.save({
    update: true,
  });
  ```

  #### response

  ```json
  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
  curl -d '{"usage_charge":{"description":""}}' \
  -X POST "https://your-development-store.myshopify.com/admin/api/2025-10/recurring_application_charges/455696195/usage_charges.json" \
  -H "X-Shopify-Access-Token: {access_token}" \
  -H "Content-Type: application/json"
  ```

  #####

  ```remix
  const { admin, session } = await authenticate.admin(request);

  const usage_charge = new admin.rest.resources.UsageCharge({session: session});

  usage_charge.recurring_application_charge_id = 455696195;
  usage_charge.description = "";
  await usage_charge.save({
    update: true,
  });
  ```

  #####

  ```ruby
  # Session is activated via Authentication
  test_session = ShopifyAPI::Context.active_session

  usage_charge = ShopifyAPI::UsageCharge.new(session: test_session)
  usage_charge.recurring_application_charge_id = 455696195
  usage_charge.description = ""
  usage_charge.save!
  ```

  #####

  ```node
  // Session is built by the OAuth process

  const usage_charge = new shopify.rest.UsageCharge({session: session});
  usage_charge.recurring_application_charge_id = 455696195;
  usage_charge.description = "";
  await usage_charge.save({
    update: true,
  });
  ```

  #### response

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

***

## getRetrieves a list of usage charges

[![](https://shopify.dev/images/logos/GraphQL.svg)![](https://shopify.dev/images/logos/GraphQL-dark.svg)](https://shopify.dev/docs/api/admin-graphql/latest/queries/nodes)

[nodes](https://shopify.dev/docs/api/admin-graphql/latest/queries/nodes)

Retrieves a list of usage charges

### Parameters

***

api\_version

string

required

***

recurring\_application\_charge\_id

string

required

***

fields

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

***

### Examples

Retrieve all usage charges

Path parameters

recurring\_​application\_​charge\_​id=​455696195

string

required

get

## /admin/api/2025-10/recurring\_​application\_​charges/455696195/usage\_​charges.​json

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

{}

## Response

JSON

```json
HTTP/1.1 200 OK
{
  "usage_charges": [
    {
      "id": 1034618206,
      "description": "Super Mega Plan Add-ons",
      "price": "10.00",
      "created_at": "2025-10-01T14:31:58-04:00",
      "currency": "USD",
      "balance_used": "10.0",
      "balance_remaining": "90.00",
      "risk_level": 0
    }
  ]
}
```

### examples

* #### Retrieve all usage charges

  #####

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

  #####

  ```remix
  await admin.rest.resources.UsageCharge.all({
    session: session,
    recurring_application_charge_id: 455696195,
  });
  ```

  #####

  ```ruby
  # Session is activated via Authentication
  test_session = ShopifyAPI::Context.active_session

  ShopifyAPI::UsageCharge.all(
    session: test_session,
    recurring_application_charge_id: 455696195,
  )
  ```

  #####

  ```node
  // Session is built by the OAuth process

  await shopify.rest.UsageCharge.all({
    session: session,
    recurring_application_charge_id: 455696195,
  });
  ```

  #### response

  ```json
  HTTP/1.1 200 OK{"usage_charges":[{"id":1034618206,"description":"Super Mega Plan Add-ons","price":"10.00","created_at":"2025-10-01T14:31:58-04:00","currency":"USD","balance_used":"10.0","balance_remaining":"90.00","risk_level":0}]}
  ```

***

## getRetrieves a single charge

[![](https://shopify.dev/images/logos/GraphQL.svg)![](https://shopify.dev/images/logos/GraphQL-dark.svg)](https://shopify.dev/docs/api/admin-graphql/latest/queries/node)

[node](https://shopify.dev/docs/api/admin-graphql/latest/queries/node)

Retrieves a single charge

### Parameters

***

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.

***

### Examples

Retrieve a single charge

get

## /admin/api/2025-10/recurring\_​application\_​charges/455696195/usage\_​charges/1034618207.​json

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

{}

## Response

JSON

```json
HTTP/1.1 200 OK
{
  "usage_charge": {
    "id": 1034618207,
    "description": "Super Mega Plan Add-ons",
    "price": "10.00",
    "created_at": "2025-10-01T14:31:59-04:00",
    "currency": "USD",
    "balance_used": "10.0",
    "balance_remaining": "90.00",
    "risk_level": 0
  }
}
```

### examples

* #### Retrieve a single charge

  #####

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

  #####

  ```remix
  await admin.rest.resources.UsageCharge.find({
    session: session,
    recurring_application_charge_id: 455696195,
    id: 1034618207,
  });
  ```

  #####

  ```ruby
  # Session is activated via Authentication
  test_session = ShopifyAPI::Context.active_session

  ShopifyAPI::UsageCharge.find(
    session: test_session,
    recurring_application_charge_id: 455696195,
    id: 1034618207,
  )
  ```

  #####

  ```node
  // Session is built by the OAuth process

  await shopify.rest.UsageCharge.find({
    session: session,
    recurring_application_charge_id: 455696195,
    id: 1034618207,
  });
  ```

  #### response

  ```json
  HTTP/1.1 200 OK{"usage_charge":{"id":1034618207,"description":"Super Mega Plan Add-ons","price":"10.00","created_at":"2025-10-01T14:31:59-04:00","currency":"USD","balance_used":"10.0","balance_remaining":"90.00","risk_level":0}}
  ```