As of API version 2027-01, apps can read and manage store credit on subscriptions. When a customer opts in to store credit for an eligible subscription at checkout, Shopify applies the customer's store credit to each renewal first and charges the remaining balance to the saved payment method. The change is available in the GraphQL Admin API and the Customer Account API, and doesn't require any mandatory action.
What changed
The GraphQL Admin API adds the following fields and inputs:
- Selling plans:
shows whether subscriptions on a selling plan can use store credit. You set it throughon, inandonand. - Contracts:
andshow the contract's store credit setting. - Contract calculation:
is a new optional input onand.shows the value that the commit applies. - SubscriptionDraft:
is available on,, and.
In the Customer Account API, returns the store credit setting. Customer portals can display it, and the field is read-only.
The Customer Account API applies the following validation rules:
- The API rejects
when the contract has no lines. - The API rejects
when any line's selling plan has store credit off. A fixed selling plan counts as store credit off. - The API accepts
on lines that have no selling plan. - The API always accepts
.
If a calculation fails validation, then the API returns an INVALID error on . On a , it returns an INVALID user error.
Who's affected
This change affects:
- Apps that create or manage subscription selling plans or subscription contracts using the GraphQL Admin API.
- Customer portals that read and display subscription contracts using the Customer Account API.
The new fields are available in API version 2027-01 and later. Existing selling plans and contracts are unchanged, and their default value is false.
What to do
No action is required. Existing selling plans and subscriptions continue to work as before, and you only need to update your app if you want to add support for store credit.
To add store credit support in your app:
- Set
on your selling plans through. - Set
on your contracts, either directly throughor through contract calculations. - After each calculation, read
, and don't commit the calculation if the value differs from the value that you sent.
For implementation details, end-to-end examples, and request shapes, see Use store credit with subscriptions.