# appUsageRecordCreate - admin - MUTATION Version: 2024-04 ## 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. ### Access Scopes ## Arguments * [description](/docs/api/admin/2024-04/scalars/String): String! - The description of the app usage record. * [idempotencyKey](/docs/api/admin/2024-04/scalars/String): String - A unique key generated by the client to avoid duplicate charges. Maximum length of 255 characters. * [price](/docs/api/admin/2024-04/input-objects/MoneyInput): MoneyInput! - The price of the app usage record. * [subscriptionLineItemId](/docs/api/admin/2024-04/scalars/ID): ID! - 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. ## Returns * [appUsageRecord](/docs/api/admin/2024-04/objects/AppUsageRecord): AppUsageRecord The newly created app usage record. * [userErrors](/docs/api/admin/2024-04/objects/UserError): UserError! The list of errors that occurred from executing the mutation. ## Examples ### Creates a usage charge Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2024-04/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"query\": \"mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!) { appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId) { userErrors { field message } appUsageRecord { id } } }\",\n \"variables\": {\n \"subscriptionLineItemId\": \"gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1\",\n \"price\": {\n \"amount\": 1.0,\n \"currencyCode\": \"USD\"\n },\n \"description\": \"Super Mega Plan 1000 emails\"\n }\n}'\n" Node example: "const client = new shopify.clients.Graphql({session});\nconst data = await client.query({\n data: {\n \"query\": `mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!) {\n appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId) {\n userErrors {\n field\n message\n }\n appUsageRecord {\n id\n }\n }\n }`,\n \"variables\": {\n \"subscriptionLineItemId\": \"gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1\",\n \"price\": {\n \"amount\": 1.0,\n \"currencyCode\": \"USD\"\n },\n \"description\": \"Super Mega Plan 1000 emails\"\n },\n },\n});\n" Ruby example: "session = ShopifyAPI::Auth::Session.new(\n shop: \"your-development-store.myshopify.com\",\n access_token: access_token\n)\nclient = ShopifyAPI::Clients::Graphql::Admin.new(\n session: session\n)\n\nquery = <<~QUERY\n mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!) {\n appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId) {\n userErrors {\n field\n message\n }\n appUsageRecord {\n id\n }\n }\n }\nQUERY\n\nvariables = {\n \"subscriptionLineItemId\": \"gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1\",\n \"price\": {\n \"amount\": 1.0,\n \"currencyCode\": \"USD\"\n },\n \"description\": \"Super Mega Plan 1000 emails\"\n}\n\nresponse = client.query(query: query, variables: variables)\n" Remix example: "const { admin } = await authenticate.admin(request);\n\nconst response = await admin.graphql(\n `#graphql\n mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!) {\n appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId) {\n userErrors {\n field\n message\n }\n appUsageRecord {\n id\n }\n }\n }`,\n {\n variables: {\n \"subscriptionLineItemId\": \"gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1\",\n \"price\": {\n \"amount\": 1.0,\n \"currencyCode\": \"USD\"\n },\n \"description\": \"Super Mega Plan 1000 emails\"\n },\n },\n);\n\nconst data = await response.json();\n" Graphql query: "mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!) {\n appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId) {\n userErrors {\n field\n message\n }\n appUsageRecord {\n id\n }\n }\n}" #### Graphql Input { "subscriptionLineItemId": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1", "price": { "amount": 1.0, "currencyCode": "USD" }, "description": "Super Mega Plan 1000 emails" } #### Graphql Response { "data": { "appUsageRecordCreate": { "userErrors": [], "appUsageRecord": { "id": "gid://shopify/AppUsageRecord/1034618209" } } } } ### Creating a usage record above the capped amount returns an error Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2024-04/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"query\": \"mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!) { appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId) { userErrors { field message } appUsageRecord { id } } }\",\n \"variables\": {\n \"subscriptionLineItemId\": \"gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1\",\n \"price\": {\n \"amount\": 100.0,\n \"currencyCode\": \"USD\"\n },\n \"description\": \"Super Mega Plan 1000 emails\"\n }\n}'\n" Node example: "const client = new shopify.clients.Graphql({session});\nconst data = await client.query({\n data: {\n \"query\": `mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!) {\n appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId) {\n userErrors {\n field\n message\n }\n appUsageRecord {\n id\n }\n }\n }`,\n \"variables\": {\n \"subscriptionLineItemId\": \"gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1\",\n \"price\": {\n \"amount\": 100.0,\n \"currencyCode\": \"USD\"\n },\n \"description\": \"Super Mega Plan 1000 emails\"\n },\n },\n});\n" Ruby example: "session = ShopifyAPI::Auth::Session.new(\n shop: \"your-development-store.myshopify.com\",\n access_token: access_token\n)\nclient = ShopifyAPI::Clients::Graphql::Admin.new(\n session: session\n)\n\nquery = <<~QUERY\n mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!) {\n appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId) {\n userErrors {\n field\n message\n }\n appUsageRecord {\n id\n }\n }\n }\nQUERY\n\nvariables = {\n \"subscriptionLineItemId\": \"gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1\",\n \"price\": {\n \"amount\": 100.0,\n \"currencyCode\": \"USD\"\n },\n \"description\": \"Super Mega Plan 1000 emails\"\n}\n\nresponse = client.query(query: query, variables: variables)\n" Remix example: "const { admin } = await authenticate.admin(request);\n\nconst response = await admin.graphql(\n `#graphql\n mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!) {\n appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId) {\n userErrors {\n field\n message\n }\n appUsageRecord {\n id\n }\n }\n }`,\n {\n variables: {\n \"subscriptionLineItemId\": \"gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1\",\n \"price\": {\n \"amount\": 100.0,\n \"currencyCode\": \"USD\"\n },\n \"description\": \"Super Mega Plan 1000 emails\"\n },\n },\n);\n\nconst data = await response.json();\n" Graphql query: "mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!) {\n appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId) {\n userErrors {\n field\n message\n }\n appUsageRecord {\n id\n }\n }\n}" #### Graphql Input { "subscriptionLineItemId": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1", "price": { "amount": 100.0, "currencyCode": "USD" }, "description": "Super Mega Plan 1000 emails" } #### Graphql Response { "data": { "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. Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2024-04/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"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 } } }\",\n \"variables\": {\n \"subscriptionLineItemId\": \"gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1\",\n \"price\": {\n \"amount\": 1.0,\n \"currencyCode\": \"USD\"\n },\n \"description\": \"Super Mega Plan 1000 emails\",\n \"idempotencyKey\": \"****************************************************************************************************************************************************************************************************************************************************************\"\n }\n}'\n" Node example: "const client = new shopify.clients.Graphql({session});\nconst data = await client.query({\n data: {\n \"query\": `mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!, $idempotencyKey: String) {\n appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId, idempotencyKey: $idempotencyKey) {\n userErrors {\n field\n message\n }\n appUsageRecord {\n id\n }\n }\n }`,\n \"variables\": {\n \"subscriptionLineItemId\": \"gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1\",\n \"price\": {\n \"amount\": 1.0,\n \"currencyCode\": \"USD\"\n },\n \"description\": \"Super Mega Plan 1000 emails\",\n \"idempotencyKey\": \"****************************************************************************************************************************************************************************************************************************************************************\"\n },\n },\n});\n" Ruby example: "session = ShopifyAPI::Auth::Session.new(\n shop: \"your-development-store.myshopify.com\",\n access_token: access_token\n)\nclient = ShopifyAPI::Clients::Graphql::Admin.new(\n session: session\n)\n\nquery = <<~QUERY\n mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!, $idempotencyKey: String) {\n appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId, idempotencyKey: $idempotencyKey) {\n userErrors {\n field\n message\n }\n appUsageRecord {\n id\n }\n }\n }\nQUERY\n\nvariables = {\n \"subscriptionLineItemId\": \"gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1\",\n \"price\": {\n \"amount\": 1.0,\n \"currencyCode\": \"USD\"\n },\n \"description\": \"Super Mega Plan 1000 emails\",\n \"idempotencyKey\": \"****************************************************************************************************************************************************************************************************************************************************************\"\n}\n\nresponse = client.query(query: query, variables: variables)\n" Remix example: "const { admin } = await authenticate.admin(request);\n\nconst response = await admin.graphql(\n `#graphql\n mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!, $idempotencyKey: String) {\n appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId, idempotencyKey: $idempotencyKey) {\n userErrors {\n field\n message\n }\n appUsageRecord {\n id\n }\n }\n }`,\n {\n variables: {\n \"subscriptionLineItemId\": \"gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1\",\n \"price\": {\n \"amount\": 1.0,\n \"currencyCode\": \"USD\"\n },\n \"description\": \"Super Mega Plan 1000 emails\",\n \"idempotencyKey\": \"****************************************************************************************************************************************************************************************************************************************************************\"\n },\n },\n);\n\nconst data = await response.json();\n" Graphql query: "mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!, $idempotencyKey: String) {\n appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId, idempotencyKey: $idempotencyKey) {\n userErrors {\n field\n message\n }\n appUsageRecord {\n id\n }\n }\n}" #### Graphql Input { "subscriptionLineItemId": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1", "price": { "amount": 1.0, "currencyCode": "USD" }, "description": "Super Mega Plan 1000 emails", "idempotencyKey": "****************************************************************************************************************************************************************************************************************************************************************" } #### Graphql Response { "data": { "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. Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2024-04/graphql.json \\\n-H 'Content-Type: application/json' \\\n-H 'X-Shopify-Access-Token: {access_token}' \\\n-d '{\n\"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 } } }\",\n \"variables\": {\n \"subscriptionLineItemId\": \"gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1\",\n \"price\": {\n \"amount\": 1.0,\n \"currencyCode\": \"USD\"\n },\n \"description\": \"Super Mega Plan 1000 emails\",\n \"idempotencyKey\": \"Some idempotency key\"\n }\n}'\n" Node example: "const client = new shopify.clients.Graphql({session});\nconst data = await client.query({\n data: {\n \"query\": `mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!, $idempotencyKey: String) {\n appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId, idempotencyKey: $idempotencyKey) {\n userErrors {\n field\n message\n }\n appUsageRecord {\n id\n }\n }\n }`,\n \"variables\": {\n \"subscriptionLineItemId\": \"gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1\",\n \"price\": {\n \"amount\": 1.0,\n \"currencyCode\": \"USD\"\n },\n \"description\": \"Super Mega Plan 1000 emails\",\n \"idempotencyKey\": \"Some idempotency key\"\n },\n },\n});\n" Ruby example: "session = ShopifyAPI::Auth::Session.new(\n shop: \"your-development-store.myshopify.com\",\n access_token: access_token\n)\nclient = ShopifyAPI::Clients::Graphql::Admin.new(\n session: session\n)\n\nquery = <<~QUERY\n mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!, $idempotencyKey: String) {\n appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId, idempotencyKey: $idempotencyKey) {\n userErrors {\n field\n message\n }\n appUsageRecord {\n id\n }\n }\n }\nQUERY\n\nvariables = {\n \"subscriptionLineItemId\": \"gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1\",\n \"price\": {\n \"amount\": 1.0,\n \"currencyCode\": \"USD\"\n },\n \"description\": \"Super Mega Plan 1000 emails\",\n \"idempotencyKey\": \"Some idempotency key\"\n}\n\nresponse = client.query(query: query, variables: variables)\n" Remix example: "const { admin } = await authenticate.admin(request);\n\nconst response = await admin.graphql(\n `#graphql\n mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!, $idempotencyKey: String) {\n appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId, idempotencyKey: $idempotencyKey) {\n userErrors {\n field\n message\n }\n appUsageRecord {\n id\n }\n }\n }`,\n {\n variables: {\n \"subscriptionLineItemId\": \"gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1\",\n \"price\": {\n \"amount\": 1.0,\n \"currencyCode\": \"USD\"\n },\n \"description\": \"Super Mega Plan 1000 emails\",\n \"idempotencyKey\": \"Some idempotency key\"\n },\n },\n);\n\nconst data = await response.json();\n" Graphql query: "mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!, $idempotencyKey: String) {\n appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId, idempotencyKey: $idempotencyKey) {\n userErrors {\n field\n message\n }\n appUsageRecord {\n id\n }\n }\n}" #### Graphql Input { "subscriptionLineItemId": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1", "price": { "amount": 1.0, "currencyCode": "USD" }, "description": "Super Mega Plan 1000 emails", "idempotencyKey": "Some idempotency key" } #### Graphql Response { "data": { "appUsageRecordCreate": { "userErrors": [ { "field": [ "idempotencyKey" ], "message": "Another request for the same idempotency key is being processed. Please try again." } ], "appUsageRecord": null } } }