Anchor to section titled 'undefined'

appUsageRecordCreate
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.


Anchor to description
description
required

The description of the app usage record.

A unique key generated by the client to avoid duplicate charges. Maximum length of 255 characters.

The price of the app usage record.

Anchor to subscriptionLineItemId
subscriptionLineItemId
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.


Was this section helpful?

The newly created app usage record.

The list of errors that occurred from executing the mutation.


Was this section helpful?

Examples

Hide code
Copy
mutation appUsageRecordCreate($description: String!, $price: MoneyInput!, $subscriptionLineItemId: ID!) {
  appUsageRecordCreate(description: $description, price: $price, subscriptionLineItemId: $subscriptionLineItemId) {
    userErrors {
      field
      message
    }
    appUsageRecord {
      id
    }
  }
}
curl -X POST \
https://your-development-store.myshopify.com/admin/api/2024-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.0,
      "currencyCode": "USD"
    },
    "description": "Super Mega Plan 1000 emails"
  }
}'
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.0,
        "currencyCode": "USD"
      },
      "description": "Super Mega Plan 1000 emails"
    },
  },
);

const data = await response.json();
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.0,
    "currencyCode": "USD"
  },
  "description": "Super Mega Plan 1000 emails"
}

response = client.query(query: query, variables: variables)
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.0,
        "currencyCode": "USD"
      },
      "description": "Super Mega Plan 1000 emails"
    },
  },
});
use Shopify\Clients\Graphql;

$client = new Graphql("your-development-store.myshopify.com", $accessToken);
$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.0,
    "currencyCode" => "USD",
  ],
  "description" => "Super Mega Plan 1000 emails",
];

$response = $client->query(["query" => $query, "variables" => $variables]);
Hide code
Input variables
Copy
{
  "subscriptionLineItemId": "gid://shopify/AppSubscriptionLineItem/1029266946?v=1&index=1",
  "price": {
    "amount": 1,
    "currencyCode": "USD"
  },
  "description": "Super Mega Plan 1000 emails"
}
Hide code
Response
JSON
{
  "appUsageRecordCreate": {
    "userErrors": [],
    "appUsageRecord": {
      "id": "gid://shopify/AppUsageRecord/1034618206"
    }
  }
}