# appUsageRecordCreate - admin - MUTATION
Version: 2025-01

## 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/2025-01/scalars/String): String! - The description of the app usage record.
* [idempotencyKey](/docs/api/admin/2025-01/scalars/String): String - A unique key generated by the client to avoid duplicate charges. Maximum length of 255 characters.
* [price](/docs/api/admin/2025-01/input-objects/MoneyInput): MoneyInput! - The price of the app usage record.
* [subscriptionLineItemId](/docs/api/admin/2025-01/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/2025-01/objects/AppUsageRecord): AppUsageRecord The newly created app usage record.
* [userErrors](/docs/api/admin/2025-01/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/2025-01/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/2025-01/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/2025-01/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/2025-01/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
    }
  }
}