Skip to main content

Update the maximum charge for a subscription

Preferred approach

For public apps, use Shopify App Pricing. The Billing API is still supported for existing apps and outlier pricing models Shopify App Pricing doesn't cover.

Update the maximum amount that merchants can be charged for their subscription. You should do this if you change your pricing model.

Note

If a new usage record would make the total usage charges in the current billing interval exceed the plan's cappedAmount, then the request to create it fails. You need to increase the cappedAmount, and then obtain merchant approval before you can create more usage records.

Anchor to RequirementsRequirements

Anchor to Step 1: Retrieve charge dataStep 1: Retrieve charge data

Make a request to the AppSubscription object's lineItems for the following data from the usage line item:

  • id

    The AppSubscriptionLineItem ID. You pass this ID to the mutation in the next step.

  • cappedAmount, from the line item's plan.pricingDetails (AppUsagePricing)

    The cappedAmount is the maximum that a merchant is billed for during the 30-day billing cycle. The currencyCode must be one of the supported currencies.

  • balanceUsed, from the line item's plan.pricingDetails

The following query is an example:

POST https://{shop}.myshopify.com/admin/api/{api_version}/graphql.json

GraphQL query

query {
node(id: "gid://shopify/AppSubscription/4019585080") {
... on AppSubscription {
lineItems {
id
plan {
pricingDetails {
... on AppUsagePricing {
terms
cappedAmount {
amount
currencyCode
}
balanceUsed {
amount
currencyCode
}
}
}
}
}
}
}
}

JSON response

{
"data": {
"node": {
"lineItems": [
{
"id": "gid://shopify/AppSubscriptionLineItem/4019585080?v=1&index=0",
"plan": {
"pricingDetails": {
"terms": "$1 for 100 emails",
"cappedAmount": {
"amount": "20.0",
"currencyCode": "USD"
},
"balanceUsed": {
"amount": "0.0",
"currencyCode": "USD"
}
}
}
}
]
}
},
...
}

Anchor to Step 2: Update the capped amountStep 2: Update the capped amount

Update the capped amount by passing the usage line item's AppSubscriptionLineItem ID as the id argument, along with the new cappedAmount, to the appSubscriptionLineItemUpdate mutation.

The following mutation is an example:

POST https://{shop}.myshopify.com/admin/api/{api_version}/graphql.json

GraphQL mutation

mutation {
appSubscriptionLineItemUpdate(
id: "gid://shopify/AppSubscriptionLineItem/4019585080?v=1&index=0",
cappedAmount: {
amount: 100.00,
currencyCode: USD
}
) {
userErrors {
field
message
}
confirmationUrl
appSubscription {
id
}
}
}

JSON response

{
"data": {
"appSubscriptionLineItemUpdate": {
"userErrors": [],
"confirmationUrl": "https://domain.myshopify.com/admin/charges/4019585080/confirm_update_capped_amount?signature=BAh7BzoHaWRsKwc4AJbvOhJhdXRvX2FjdGl2YXRlRg%3D%3D--a93b35054feb213f04f1ee35ef5b569617ce6823",
"appSubscription": {
"id": "gid://shopify/AppSubscription/4019585080"
}
}
},
...
}

The new capped amount doesn't take effect until the merchant approves it. Redirect the merchant to the confirmationUrl that the mutation returns, where they can approve or decline the new capped amount.

Anchor to Next stepsNext steps

Discounts

Learn about offering subscription discounts.

Was this page helpful?