---
title: UsageCharge
description: Charge varying amounts based on the monthly usage of your app.
api_version: 2026-07
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'
api_name: admin-rest
api_type: rest
---

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.md#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.md#post-recurring-application-charges-recurring-application-charge-id-usage-charges)

  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.md#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.md#get-recurring-application-charges-recurring-application-charge-id-usage-charges)

  Retrieves a list of usage charges

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

* [get](https://shopify.dev/docs/api/admin-rest/latest/resources/usagecharge.md#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.md#get-recurring-application-charges-recurring-application-charge-id-usage-charges-usage-charge-id)

  Retrieves a single charge

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

***

## The UsageCharge resource

### Properties

***

created\_at

->[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

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

The description of the usage charge.

***

id

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

The ID of the usage charge.

***

price

**string**

->[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

->[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

->[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

[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**

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**

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**

usage\_​charge.description:​""

The description of the usage charge.

post

## /admin/api/2026-07/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/2026-07/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": 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
  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}}
  ```

* #### 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/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 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/2026-07/recurring_application_charges/455696195/usage_charges.json" \
  -H "X-Shopify-Access-Token: {access_token}" \
  -H "Content-Type: application/json"
  ```

***

## getRetrieves a list of usage charges

[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/2026-07/recurring\_​application\_​charges/455696195/usage\_​charges.​json

```bash
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

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

***

## getRetrieves a single charge

[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/2026-07/recurring\_​application\_​charges/455696195/usage\_​charges/1034618208.​json

```bash
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

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