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 you try to create a usage record for a usage pricing plan with an amount that's less than the new usage record, then the request 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/api/{api_version}/graphql.json

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/api/{api_version}/graphql.json

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

Anchor to Next stepsNext steps

Discounts

Learn about offering subscription discounts.

Was this page helpful?