--- title: appUsageRecordCreate - GraphQL Admin description: |- 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. api_version: 2025-10 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 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 * 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/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 ```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/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 ```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/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 ```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/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 ```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 [Open in GraphiQL](http://localhost:3457/graphiql?query=mutation%20appUsageRecordCreate\(%24description%3A%20String!%2C%20%24price%3A%20MoneyInput!%2C%20%24subscriptionLineItemId%3A%20ID!\)%20%7B%0A%20%20appUsageRecordCreate\(description%3A%20%24description%2C%20price%3A%20%24price%2C%20subscriptionLineItemId%3A%20%24subscriptionLineItemId\)%20%7B%0A%20%20%20%20userErrors%20%7B%0A%20%20%20%20%20%20field%0A%20%20%20%20%20%20message%0A%20%20%20%20%7D%0A%20%20%20%20appUsageRecord%20%7B%0A%20%20%20%20%20%20id%0A%20%20%20%20%7D%0A%20%20%7D%0A%7D\&variables=%7B%0A%20%20%22subscriptionLineItemId%22%3A%20%22gid%3A%2F%2Fshopify%2FAppSubscriptionLineItem%2F1029266946%3Fv%3D1%26index%3D1%22%2C%0A%20%20%22price%22%3A%20%7B%0A%20%20%20%20%22amount%22%3A%201%2C%0A%20%20%20%20%22currencyCode%22%3A%20%22USD%22%0A%20%20%7D%2C%0A%20%20%22description%22%3A%20%22Super%20Mega%20Plan%201000%20emails%22%0A%7D) ```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; } ``` ##### 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 ```json { "subscriptionLineItemId": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1", "price": { "amount": 1, "currencyCode": "USD" }, "description": "Super Mega Plan 1000 emails" } ``` ## Response JSON ```json { "appUsageRecordCreate": { "userErrors": [], "appUsageRecord": { "id": "gid://shopify/AppUsageRecord/1034618209" } } } ```