Choose a version:

appUsageRecordCreate

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

Anchor to Arguments

Arguments

Anchor to descriptiondescription •String! required: The description of the app usage record.
Anchor to idempotencyKeyidempotencyKey •String: A unique key generated by the client to avoid duplicate charges. Maximum length of 255 characters.
Anchor to priceprice •MoneyInput! required: The price of the app usage record.
Anchor to subscriptionLineItemIdsubscriptionLineItemId •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.

Was this section helpful?

Anchor to AppUsageRecordCreatePayload returnsAppUsageRecordCreatePayload returns

Anchor to appUsageRecordappUsageRecord •AppUsageRecord: The newly created app usage record.
Anchor to userErrorsuserErrors •[UserError!]! non-null: The list of errors that occurred from executing the mutation.

Was this section helpful?

Examples

Creates a usage charge

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

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-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

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

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

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

{
  "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

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

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-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

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

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

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

{
  "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

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": "****************************************************************************************************************************************************************************************************************************************************************"
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-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

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

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

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

{
  "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

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

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-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

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

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

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

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

appUsageRecordCreate reference

Examples

Open in GraphiQL

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 {

}

}`,

{

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;

}

GQL

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

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-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

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

Node.js

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"
    },
  },
});

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)

Input variables

JSON

{

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

}