Skip to main content

Subscriptions now support store credit with allowStoreCredit

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:

In the Customer Account API, SubscriptionContract.paymentConfiguration.allowStoreCredit 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 allowStoreCredit: true when the contract has no lines.
  • The API rejects allowStoreCredit: true when any line's selling plan has store credit off. A fixed selling plan counts as store credit off.
  • The API accepts allowStoreCredit: true on lines that have no selling plan.
  • The API always accepts allowStoreCredit: false.

If a calculation fails validation, then the API returns an INVALID error on calculatedContract.paymentConfiguration.allowStoreCredit. On a subscriptionDraftCommit, 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 paymentConfiguration.allowStoreCredit fields are available in API version 2027-01 and later. Existing selling plans and contracts are unchanged, and their allowStoreCredit 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:

  1. Set allowStoreCredit on your selling plans through SellingPlanRecurringBillingPolicyInput.paymentConfiguration.
  2. Set allowStoreCredit on your contracts, either directly through SubscriptionDraftInput or through contract calculations.
  3. After each calculation, read calculatedContract.paymentConfiguration.allowStoreCredit, 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.

Related docs

Was this page helpful?