appUsageRecordCreate

mutation

Enables an app to charge a store for features or services on a per-use basis. The usage charge value is counted towards the cappedAmount limit that was specified in the appUsagePricingDetails field when the app subscription was created. If you create an app usage charge that causes the total usage charges in a billing interval to exceed the capped amount, then a Total price exceeds balance remaining error is returned.

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?

Creates a usage charge
Creating a usage record above the capped amount returns an error
Creating usage record with idempotency key exceeding 255 characters results in an error.
Creating usage record with idempotency key returns an error when another request for the same shop, app, idempotency key is in progress.
appUsageRecordCreate reference

Examples

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

"currencyCode": "USD"

"description": "Super Mega Plan 1000 emails"

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

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-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.0,
      "currencyCode": "USD"
    },
    "description": "Super Mega Plan 1000 emails"
  }
}'

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.0,
        "currencyCode": "USD"
      },
      "description": "Super Mega Plan 1000 emails"
    },
  },
);

const data = await response.json();

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.0,
        "currencyCode": "USD"
      },
      "description": "Super Mega Plan 1000 emails"
    },
  },
});

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.0,
    "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"

}