---
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-10
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
api_name: admin
api_type: graphql
type: mutation
---

# 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

  [String!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String)

  required

  The description of the app usage record.

* idempotency​Key

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

  A unique key generated by the client to avoid duplicate charges. Maximum length of 255 characters.

* price

  [Money​Input!](https://shopify.dev/docs/api/admin-graphql/latest/input-objects/MoneyInput)

  required

  The price of the app usage record.

* subscription​Line​Item​Id

  [ID!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/ID)

  required

  The ID of the app subscription line item to create the usage record under. This app subscription line item must have a usage pricing plan.

***

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

* app​Usage​Record

  [App​Usage​Record](https://shopify.dev/docs/api/admin-graphql/latest/objects/AppUsageRecord)

  The newly created app usage record.

* user​Errors

  [\[User​Error!\]!](https://shopify.dev/docs/api/admin-graphql/latest/objects/UserError)

  non-null

  The list of errors that occurred from executing the mutation.

***

## 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-10/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"
      },
    },
  });
  ```

  #### Shopify CLI

  ```bash
  shopify app execute \
  --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"
  }'
  ```

  #### Direct API Access

  ```javascript
  const response = await fetch('shopify:admin/api/2026-10/graphql.json', {
    method: 'POST',
    body: JSON.stringify({
      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"
      },
    }),
  });

  const { data } = await response.json();
  console.log(data);
  ```

  #### 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-10/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"
      },
    },
  });
  ```

  #### Shopify CLI

  ```bash
  shopify app execute \
  --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"
  }'
  ```

  #### Direct API Access

  ```javascript
  const response = await fetch('shopify:admin/api/2026-10/graphql.json', {
    method: 'POST',
    body: JSON.stringify({
      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"
      },
    }),
  });

  const { data } = await response.json();
  console.log(data);
  ```

  #### 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-10/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": "****************************************************************************************************************************************************************************************************************************************************************"
      },
    },
  });
  ```

  #### Shopify CLI

  ```bash
  shopify app execute \
  --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": "****************************************************************************************************************************************************************************************************************************************************************"
  }'
  ```

  #### Direct API Access

  ```javascript
  const response = await fetch('shopify:admin/api/2026-10/graphql.json', {
    method: 'POST',
    body: JSON.stringify({
      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": "****************************************************************************************************************************************************************************************************************************************************************"
      },
    }),
  });

  const { data } = await response.json();
  console.log(data);
  ```

  #### 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-10/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"
      },
    },
  });
  ```

  #### Shopify CLI

  ```bash
  shopify app execute \
  --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"
  }'
  ```

  #### Direct API Access

  ```javascript
  const response = await fetch('shopify:admin/api/2026-10/graphql.json', {
    method: 'POST',
    body: JSON.stringify({
      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"
      },
    }),
  });

  const { data } = await response.json();
  console.log(data);
  ```

  #### Response

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

* ### appUsageRecordCreate reference