appUsageRecordCreate
Enables an app to charge a store for features or services on a per-use basis.
The usage charge value is counted towards the limit that was specified in the
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.
Arguments
- Anchor to descriptiondescription•String!required
The description of the app usage record.
- Anchor to idempotencyKeyidempotency•
Key A unique key generated by the client to avoid duplicate charges. Maximum length of 255 characters.
- Anchor to priceprice•Money
Input! required The price of the app usage record.
- Anchor to subscriptionLineItemIdsubscription•
Line Item Id 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.
Anchor to AppUsageRecordCreatePayload returnsAppUsageRecordCreatePayload returns
- Anchor to appUsageRecordapp•
Usage Record The newly created app usage record.
- Anchor to userErrorsuser•
Errors [UserError!]! non-null The list of errors that occurred from executing the mutation.
- Creates a usage charge
- Creating a usage record above the capped amount returns an error
- Creating usage record with idempotency key exceeding 255 characters results in an error.
- Creating usage record with idempotency key returns an error when another request for the same shop, app, idempotency key is in progress.
- appUsageRecordCreate reference
Examples
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-04/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();
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"
},
},
});
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)