--- 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: 2025-01 api_name: admin type: mutation api_type: graphql source_url: html: https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/appusagerecordcreate md: https://shopify.dev/docs/api/admin-graphql/2025-01/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 [String!](https://shopify.dev/docs/api/admin-graphql/2025-01/scalars/String) required The description of the app usage record. * idempotency​Key [String](https://shopify.dev/docs/api/admin-graphql/2025-01/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/2025-01/input-objects/MoneyInput) required The price of the app usage record. * subscription​Line​Item​Id [ID!](https://shopify.dev/docs/api/admin-graphql/2025-01/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/2025-01/objects/AppUsageRecord) The newly created app usage record. * user​Errors [\[User​Error!\]!](https://shopify.dev/docs/api/admin-graphql/2025-01/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-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/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": 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-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/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!, $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) ##### GQL ```graphql mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!) { appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId) { userErrors { field message } appUsageRecord { id } } } ``` ##### cURL ```bash 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, "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; } ``` ##### 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" }, }, }); ``` ##### 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) ``` ## 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" } } } ```