---
title: appUsageRecordCreate - GraphQL Admin
description: >-
  Creates a usage charge for an app subscription with usage-based pricing. The
  charge counts toward the capped amount limit set when creating the
  subscription.


  Usage records track consumption of app features or services on a per-use
  basis. You provide the charge amount, a description of what you consumed, and
  the subscription line item ID. The optional
  [`idempotencyKey`](https://shopify.dev/docs/api/admin-graphql/latest/objects/AppUsageRecord#field-idempotencyKey)
  parameter prevents duplicate charges if you send the same request multiple
  times.


  If the new charge would cause total usage charges in the current billing
  interval to exceed the capped amount, then the mutation returns an error.


  Learn more about [creating usage-based
  subscriptions](https://shopify.dev/docs/apps/launch/billing/subscription-billing/create-usage-based-subscriptions).
api_version: 2026-01
api_name: admin
type: mutation
api_type: graphql
source_url:
  html: >-
    https://shopify.dev/docs/api/admin-graphql/latest/mutations/appUsageRecordCreate
  md: >-
    https://shopify.dev/docs/api/admin-graphql/latest/mutations/appUsageRecordCreate.md
---

# app​Usage​Record​Create

mutation

Creates a usage charge for an app subscription with usage-based pricing. The charge counts toward the capped amount limit set when creating the subscription.

Usage records track consumption of app features or services on a per-use basis. You provide the charge amount, a description of what you consumed, and the subscription line item ID. The optional [`idempotencyKey`](https://shopify.dev/docs/api/admin-graphql/latest/objects/AppUsageRecord#field-idempotencyKey) parameter prevents duplicate charges if you send the same request multiple times.

If the new charge would cause total usage charges in the current billing interval to exceed the capped amount, then the mutation returns an error.

Learn more about [creating usage-based subscriptions](https://shopify.dev/docs/apps/launch/billing/subscription-billing/create-usage-based-subscriptions).

## Arguments

* description
* idempotencyKey
* price
* subscriptionLineItemId

***

## App​Usage​Record​Create​Payload returns

* appUsageRecord
* userErrors

***

## Examples

* ### Creates a usage charge

  #### Query

  ```graphql
  mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!) {
    appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId) {
      userErrors {
        field
        message
      }
      appUsageRecord {
        id
      }
    }
  }
  ```

  #### Variables

  ```json
  {
    "subscriptionLineItemId": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",
    "price": {
      "amount": 1,
      "currencyCode": "USD"
    },
    "description": "Super Mega Plan 1000 emails"
  }
  ```

  #### cURL

  ```bash
  curl -X POST \
  https://your-development-store.myshopify.com/admin/api/2026-01/graphql.json \
  -H 'Content-Type: application/json' \
  -H 'X-Shopify-Access-Token: {access_token}' \
  -d '{
  "query": "mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!) { appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId) { userErrors { field message } appUsageRecord { id } } }",
   "variables": {
      "subscriptionLineItemId": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",
      "price": {
        "amount": 1,
        "currencyCode": "USD"
      },
      "description": "Super Mega Plan 1000 emails"
    }
  }'
  ```

  #### React Router

  ```javascript
  import { authenticate } from "../shopify.server";

  export const loader = async ({request}) => {
    const { admin } = await authenticate.admin(request);
    const response = await admin.graphql(
      `#graphql
    mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!) {
      appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId) {
        userErrors {
          field
          message
        }
        appUsageRecord {
          id
        }
      }
    }`,
    {
      variables: {
          "subscriptionLineItemId": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",
          "price": {
              "amount": 1,
              "currencyCode": "USD"
          },
          "description": "Super Mega Plan 1000 emails"
      },
    },
    );
    const json = await response.json();
    return json.data;
  }
  ```

  #### Ruby

  ```ruby
  session = ShopifyAPI::Auth::Session.new(
    shop: "your-development-store.myshopify.com",
    access_token: access_token
  )
  client = ShopifyAPI::Clients::Graphql::Admin.new(
    session: session
  )

  query = <<~QUERY
    mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!) {
      appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId) {
        userErrors {
          field
          message
        }
        appUsageRecord {
          id
        }
      }
    }
  QUERY

  variables = {
    "subscriptionLineItemId": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",
    "price": {
      "amount": 1,
      "currencyCode": "USD"
    },
    "description": "Super Mega Plan 1000 emails"
  }

  response = client.query(query: query, variables: variables)
  ```

  #### Node.js

  ```javascript
  const client = new shopify.clients.Graphql({session});
  const data = await client.query({
    data: {
      "query": `mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!) {
        appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId) {
          userErrors {
            field
            message
          }
          appUsageRecord {
            id
          }
        }
      }`,
      "variables": {
          "subscriptionLineItemId": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",
          "price": {
              "amount": 1,
              "currencyCode": "USD"
          },
          "description": "Super Mega Plan 1000 emails"
      },
    },
  });
  ```

  #### Response

  ```json
  {
    "appUsageRecordCreate": {
      "userErrors": [],
      "appUsageRecord": {
        "id": "gid://shopify/AppUsageRecord/1034618209"
      }
    }
  }
  ```

* ### Creating a usage record above the capped amount returns an error

  #### Description

  If the usage record would cause the capped amount specified on the usage pricing plan to be exceeded an error is returned.

  #### Query

  ```graphql
  mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!) {
    appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId) {
      userErrors {
        field
        message
      }
      appUsageRecord {
        id
      }
    }
  }
  ```

  #### Variables

  ```json
  {
    "subscriptionLineItemId": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",
    "price": {
      "amount": 100,
      "currencyCode": "USD"
    },
    "description": "Super Mega Plan 1000 emails"
  }
  ```

  #### cURL

  ```bash
  curl -X POST \
  https://your-development-store.myshopify.com/admin/api/2026-01/graphql.json \
  -H 'Content-Type: application/json' \
  -H 'X-Shopify-Access-Token: {access_token}' \
  -d '{
  "query": "mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!) { appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId) { userErrors { field message } appUsageRecord { id } } }",
   "variables": {
      "subscriptionLineItemId": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",
      "price": {
        "amount": 100,
        "currencyCode": "USD"
      },
      "description": "Super Mega Plan 1000 emails"
    }
  }'
  ```

  #### React Router

  ```javascript
  import { authenticate } from "../shopify.server";

  export const loader = async ({request}) => {
    const { admin } = await authenticate.admin(request);
    const response = await admin.graphql(
      `#graphql
    mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!) {
      appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId) {
        userErrors {
          field
          message
        }
        appUsageRecord {
          id
        }
      }
    }`,
    {
      variables: {
          "subscriptionLineItemId": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",
          "price": {
              "amount": 100,
              "currencyCode": "USD"
          },
          "description": "Super Mega Plan 1000 emails"
      },
    },
    );
    const json = await response.json();
    return json.data;
  }
  ```

  #### Ruby

  ```ruby
  session = ShopifyAPI::Auth::Session.new(
    shop: "your-development-store.myshopify.com",
    access_token: access_token
  )
  client = ShopifyAPI::Clients::Graphql::Admin.new(
    session: session
  )

  query = <<~QUERY
    mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!) {
      appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId) {
        userErrors {
          field
          message
        }
        appUsageRecord {
          id
        }
      }
    }
  QUERY

  variables = {
    "subscriptionLineItemId": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",
    "price": {
      "amount": 100,
      "currencyCode": "USD"
    },
    "description": "Super Mega Plan 1000 emails"
  }

  response = client.query(query: query, variables: variables)
  ```

  #### Node.js

  ```javascript
  const client = new shopify.clients.Graphql({session});
  const data = await client.query({
    data: {
      "query": `mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!) {
        appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId) {
          userErrors {
            field
            message
          }
          appUsageRecord {
            id
          }
        }
      }`,
      "variables": {
          "subscriptionLineItemId": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",
          "price": {
              "amount": 100,
              "currencyCode": "USD"
          },
          "description": "Super Mega Plan 1000 emails"
      },
    },
  });
  ```

  #### Response

  ```json
  {
    "appUsageRecordCreate": {
      "userErrors": [
        {
          "field": null,
          "message": "Failed to create usage charge"
        }
      ],
      "appUsageRecord": null
    }
  }
  ```

* ### Creating usage record with idempotency key exceeding 255 characters results in an error.

  #### Query

  ```graphql
  mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!, $idempotencyKey: String) {
    appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId, idempotencyKey: $idempotencyKey) {
      userErrors {
        field
        message
      }
      appUsageRecord {
        id
      }
    }
  }
  ```

  #### Variables

  ```json
  {
    "subscriptionLineItemId": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",
    "price": {
      "amount": 1,
      "currencyCode": "USD"
    },
    "description": "Super Mega Plan 1000 emails",
    "idempotencyKey": "****************************************************************************************************************************************************************************************************************************************************************"
  }
  ```

  #### cURL

  ```bash
  curl -X POST \
  https://your-development-store.myshopify.com/admin/api/2026-01/graphql.json \
  -H 'Content-Type: application/json' \
  -H 'X-Shopify-Access-Token: {access_token}' \
  -d '{
  "query": "mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!, $idempotencyKey: String) { appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId, idempotencyKey: $idempotencyKey) { userErrors { field message } appUsageRecord { id } } }",
   "variables": {
      "subscriptionLineItemId": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",
      "price": {
        "amount": 1,
        "currencyCode": "USD"
      },
      "description": "Super Mega Plan 1000 emails",
      "idempotencyKey": "****************************************************************************************************************************************************************************************************************************************************************"
    }
  }'
  ```

  #### React Router

  ```javascript
  import { authenticate } from "../shopify.server";

  export const loader = async ({request}) => {
    const { admin } = await authenticate.admin(request);
    const response = await admin.graphql(
      `#graphql
    mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!, $idempotencyKey: String) {
      appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId, idempotencyKey: $idempotencyKey) {
        userErrors {
          field
          message
        }
        appUsageRecord {
          id
        }
      }
    }`,
    {
      variables: {
          "subscriptionLineItemId": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",
          "price": {
              "amount": 1,
              "currencyCode": "USD"
          },
          "description": "Super Mega Plan 1000 emails",
          "idempotencyKey": "****************************************************************************************************************************************************************************************************************************************************************"
      },
    },
    );
    const json = await response.json();
    return json.data;
  }
  ```

  #### Ruby

  ```ruby
  session = ShopifyAPI::Auth::Session.new(
    shop: "your-development-store.myshopify.com",
    access_token: access_token
  )
  client = ShopifyAPI::Clients::Graphql::Admin.new(
    session: session
  )

  query = <<~QUERY
    mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!, $idempotencyKey: String) {
      appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId, idempotencyKey: $idempotencyKey) {
        userErrors {
          field
          message
        }
        appUsageRecord {
          id
        }
      }
    }
  QUERY

  variables = {
    "subscriptionLineItemId": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",
    "price": {
      "amount": 1,
      "currencyCode": "USD"
    },
    "description": "Super Mega Plan 1000 emails",
    "idempotencyKey": "****************************************************************************************************************************************************************************************************************************************************************"
  }

  response = client.query(query: query, variables: variables)
  ```

  #### Node.js

  ```javascript
  const client = new shopify.clients.Graphql({session});
  const data = await client.query({
    data: {
      "query": `mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!, $idempotencyKey: String) {
        appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId, idempotencyKey: $idempotencyKey) {
          userErrors {
            field
            message
          }
          appUsageRecord {
            id
          }
        }
      }`,
      "variables": {
          "subscriptionLineItemId": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",
          "price": {
              "amount": 1,
              "currencyCode": "USD"
          },
          "description": "Super Mega Plan 1000 emails",
          "idempotencyKey": "****************************************************************************************************************************************************************************************************************************************************************"
      },
    },
  });
  ```

  #### Response

  ```json
  {
    "appUsageRecordCreate": {
      "userErrors": [
        {
          "field": [
            "idempotencyKey"
          ],
          "message": "Idempotency key exceeds the maximum length."
        }
      ],
      "appUsageRecord": null
    }
  }
  ```

* ### Creating usage record with idempotency key returns an error when another request for the same shop, app, idempotency key is in progress.

  #### Query

  ```graphql
  mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!, $idempotencyKey: String) {
    appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId, idempotencyKey: $idempotencyKey) {
      userErrors {
        field
        message
      }
      appUsageRecord {
        id
      }
    }
  }
  ```

  #### Variables

  ```json
  {
    "subscriptionLineItemId": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",
    "price": {
      "amount": 1,
      "currencyCode": "USD"
    },
    "description": "Super Mega Plan 1000 emails",
    "idempotencyKey": "Some idempotency key"
  }
  ```

  #### cURL

  ```bash
  curl -X POST \
  https://your-development-store.myshopify.com/admin/api/2026-01/graphql.json \
  -H 'Content-Type: application/json' \
  -H 'X-Shopify-Access-Token: {access_token}' \
  -d '{
  "query": "mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!, $idempotencyKey: String) { appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId, idempotencyKey: $idempotencyKey) { userErrors { field message } appUsageRecord { id } } }",
   "variables": {
      "subscriptionLineItemId": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",
      "price": {
        "amount": 1,
        "currencyCode": "USD"
      },
      "description": "Super Mega Plan 1000 emails",
      "idempotencyKey": "Some idempotency key"
    }
  }'
  ```

  #### React Router

  ```javascript
  import { authenticate } from "../shopify.server";

  export const loader = async ({request}) => {
    const { admin } = await authenticate.admin(request);
    const response = await admin.graphql(
      `#graphql
    mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!, $idempotencyKey: String) {
      appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId, idempotencyKey: $idempotencyKey) {
        userErrors {
          field
          message
        }
        appUsageRecord {
          id
        }
      }
    }`,
    {
      variables: {
          "subscriptionLineItemId": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",
          "price": {
              "amount": 1,
              "currencyCode": "USD"
          },
          "description": "Super Mega Plan 1000 emails",
          "idempotencyKey": "Some idempotency key"
      },
    },
    );
    const json = await response.json();
    return json.data;
  }
  ```

  #### Ruby

  ```ruby
  session = ShopifyAPI::Auth::Session.new(
    shop: "your-development-store.myshopify.com",
    access_token: access_token
  )
  client = ShopifyAPI::Clients::Graphql::Admin.new(
    session: session
  )

  query = <<~QUERY
    mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!, $idempotencyKey: String) {
      appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId, idempotencyKey: $idempotencyKey) {
        userErrors {
          field
          message
        }
        appUsageRecord {
          id
        }
      }
    }
  QUERY

  variables = {
    "subscriptionLineItemId": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",
    "price": {
      "amount": 1,
      "currencyCode": "USD"
    },
    "description": "Super Mega Plan 1000 emails",
    "idempotencyKey": "Some idempotency key"
  }

  response = client.query(query: query, variables: variables)
  ```

  #### Node.js

  ```javascript
  const client = new shopify.clients.Graphql({session});
  const data = await client.query({
    data: {
      "query": `mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!, $idempotencyKey: String) {
        appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId, idempotencyKey: $idempotencyKey) {
          userErrors {
            field
            message
          }
          appUsageRecord {
            id
          }
        }
      }`,
      "variables": {
          "subscriptionLineItemId": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",
          "price": {
              "amount": 1,
              "currencyCode": "USD"
          },
          "description": "Super Mega Plan 1000 emails",
          "idempotencyKey": "Some idempotency key"
      },
    },
  });
  ```

  #### Response

  ```json
  {
    "appUsageRecordCreate": {
      "userErrors": [
        {
          "field": [
            "idempotencyKey"
          ],
          "message": "Another request for the same idempotency key is being processed. Please try again."
        }
      ],
      "appUsageRecord": null
    }
  }
  ```

* ### appUsageRecordCreate reference