Executive summary
- What: API version 2027-01 adds allowStoreCredit to selling plans and subscription contracts, so a customer's store credit can pay down each renewal before the saved card is charged.
- Why: Store credit from refunds, loyalty, or goodwill gestures previously sat unusable against recurring orders. Now it applies automatically at renewal, with the remainder billed as normal.
- Who: Merchants running subscriptions on Shopify, especially those issuing store credit as a refund or retention mechanism and fielding support tickets about why it cannot be spent.
What changed
When a customer opts in to store credit for an eligible subscription at checkout, Shopify applies their available credit to each renewal first and charges the remaining balance to the saved payment method. The behaviour is exposed through both the GraphQL Admin API and the Customer Account API, and no action is mandatory.
On the Admin side, SellingPlanRecurringBillingPolicy.paymentConfiguration.allowStoreCredit controls whether subscriptions on a selling plan can use credit, set through the billing policy input in sellingPlanGroupCreate and sellingPlanGroupUpdate. Contracts carry the same flag, and paymentConfiguration is a new optional input on contract calculation and SubscriptionDraftInput. In the Customer Account API the field is read-only, so a portal can display the setting but not change it.
Validation is stricter than it first appears. The API rejects allowStoreCredit: true on a contract with no lines, and when any line's selling plan has store credit off, where a fixed selling plan counts as off. It accepts true on lines with no selling plan, and always accepts false. A failed calculation returns an INVALID error on calculatedContract.paymentConfiguration.allowStoreCredit, and subscriptionDraftCommit returns an INVALID user error. Existing plans and contracts default to false.
Why it matters
This closes a gap that generates real support volume. A subscriber given store credit for a damaged shipment has had no way to spend it on the thing they actually buy from you every month. The workarounds were a manual discount, a refund to card, or an agent explaining the limitation, all of which cost money and goodwill.
There is a retention argument too. Store credit is a cheaper remedy than a cash refund because it stays inside your business, but only if the customer can spend it without friction. Applying it automatically at renewal turns credit into a genuine retention tool rather than a balance that quietly expires. For brands investing in subscription growth, it also removes an awkward caveat from the service recovery script.
Role-specific impact
- Marketers: Store credit becomes viable as a win-back and service recovery offer for subscribers. It also changes renewal revenue reporting, since part of a renewal may now settle against credit rather than new card revenue.
- Developers: Move to 2027-01, then set allowStoreCredit on selling plans through the billing policy input and on contracts via SubscriptionDraftInput or calculations. After each calculation, read back calculatedContract.paymentConfiguration.allowStoreCredit and do not commit if it differs from what you sent.
- Store admins: Expect renewal charges that are smaller than the contract total when credit is applied. Brief the support team before enabling, so agents can explain a partial charge rather than escalating it as a billing error.
Use-case example
Real-world scenario
A supplements brand bills 8,400 subscriptions a month at an average of 54 dollars and issues roughly 190 store credits a month averaging 22 dollars for damaged or delayed shipments. Most of that credit went unredeemed, because subscribers rarely place one-off orders. Enabling allowStoreCredit on the two recurring selling plans lets each credit apply to the next renewal automatically. Redemption should reach most issued credit within one billing cycle, cutting follow-up refund requests and making credit a defensible alternative to a card refund.
Implementation checklist
- Upgrade the integration to API version 2027-01 in a development environment first.
- Decide which selling plans should permit store credit, remembering that fixed selling plans count as off.
- Set paymentConfiguration.allowStoreCredit on those plans through sellingPlanGroupCreate or sellingPlanGroupUpdate.
- Set the flag on contracts through SubscriptionDraftInput or contract calculation inputs.
- After every calculation, compare the returned allowStoreCredit against the value you sent and abort the commit on a mismatch.
- Handle INVALID errors on calculation and on subscriptionDraftCommit rather than treating them as transient.
- Surface the read-only flag in the customer portal so subscribers can see credit will apply.
- Update support macros and renewal reporting to account for partial card charges.
FAQ
Q: Will this change billing on our existing subscriptions?
A: No. Existing selling plans and contracts default to allowStoreCredit: false and continue to bill exactly as before. Nothing applies credit to a renewal until you opt a plan in and the customer opts in at checkout.
Q: Can a customer turn store credit on for an existing subscription themselves?
A: Not through the Customer Account API, where the field is read-only. A portal can display the setting, so a customer can see whether credit applies, but changing it requires an Admin API call on your side.
Resources
Shopify's implementation guide with end-to-end examples and request shapes: Use store credit with subscriptions.
Need guidance? Talk to Makro.