appUsageRecordCreate - admin-graphql - MUTATION

Version: 2024-10

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: String! - The description of the app usage record.
• idempotencyKey: String - A unique key generated by the client to avoid duplicate charges. Maximum length of 255 characters.
• price: MoneyInput! - The price of the app usage record.
• subscriptionLineItemId: 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: AppUsageRecord The newly created app usage record.
• userErrors: UserError! The list of errors that occurred from executing the mutation.

Examples

• Create a new usage record

          Curl example: "curl -X POST \\\nhttps://your-development-store.myshopify.com/admin/api/2024-10/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"
          PHP example: "use Shopify\\Clients\\Graphql;\n\n$client = new Graphql(\"your-development-store.myshopify.com\", $accessToken);\n$query = << \"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$response = $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}"
        

  input: {
    "subscriptionLineItemId": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",
    "price": {
      "amount": 1.0,
      "currencyCode": "USD"
    },
    "description": "Super Mega Plan 1000 emails"
  }

  response: {
    "data": {
      "appUsageRecordCreate": {
        "userErrors": [],
        "appUsageRecord": {
          "id": "gid://shopify/AppUsageRecord/1034618206"
        }
      }
    }
  }

  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-10/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"
          PHP example: "use Shopify\\Clients\\Graphql;\n\n$client = new Graphql(\"your-development-store.myshopify.com\", $accessToken);\n$query = << \"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$response = $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}"
        

  input: {
    "subscriptionLineItemId": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",
    "price": {
      "amount": 100.0,
      "currencyCode": "USD"
    },
    "description": "Super Mega Plan 1000 emails"
  }

  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-10/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"
          PHP example: "use Shopify\\Clients\\Graphql;\n\n$client = new Graphql(\"your-development-store.myshopify.com\", $accessToken);\n$query = << \"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$response = $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}"
        

  input: {
    "subscriptionLineItemId": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",
    "price": {
      "amount": 1.0,
      "currencyCode": "USD"
    },
    "description": "Super Mega Plan 1000 emails",
    "idempotencyKey": "****************************************************************************************************************************************************************************************************************************************************************"
  }

  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-10/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"
          PHP example: "use Shopify\\Clients\\Graphql;\n\n$client = new Graphql(\"your-development-store.myshopify.com\", $accessToken);\n$query = << \"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$response = $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}"
        

  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"
  }

  response: {
    "data": {
      "appUsageRecordCreate": {
        "userErrors": [
          {
            "field": [
              "idempotencyKey"
            ],
            "message": "Another request for the same idempotency key is being processed. Please try again."
          }
        ],
        "appUsageRecord": null
      }
    }
  }