Store Credit Now Powers Shopify Subscriptions with allowStoreCredit

Shopify’s 2027-01 API adds store‑credit support to subscriptions via the allowStoreCredit flag. Learn what changed, who’s impacted, and how developers can enable this new feature in minutes.

Store Credit Now Powers Shopify Subscriptions with allowStoreCredit
5 sections

Shopify merchants and developers have long wanted a seamless way to let customers apply their store credit toward recurring purchases. Starting with API version 2027-01, Shopify finally makes that possible. The new allowStoreCredit field unlocks store‑credit handling for subscription selling plans, contracts, and drafts, giving you granular control over how credit is applied at each renewal. This post breaks down the update, explains who needs to pay attention, and provides a quick implementation guide so you can start offering this flexibility to your shoppers right away.

What Changed: Store Credit Support in Subscriptions

The GraphQL Admin API now exposes a paymentConfiguration.allowStoreCredit boolean on several subscription‑related objects:

• SellingPlanRecurringBillingPolicy.paymentConfiguration.allowStoreCredit – toggles store‑credit eligibility for a selling plan.

• SubscriptionContract.paymentConfiguration.allowStoreCredit – reflects the contract’s store‑credit setting.

• SubscriptionBillingCycleEditedContract.paymentConfiguration.allowStoreCredit – same flag on edited cycles.

• SubscriptionContractCalculationContractCreateInput / UpdateInput – optional input to calculate a contract with the desired flag.

• SubscriptionDraftInput.paymentConfiguration – used when creating or updating a draft subscription.

In the Customer Account API, SubscriptionContract.paymentConfiguration.allowStoreCredit is read‑only, allowing storefronts to display the setting to customers.

Validation rules in the Customer Account API ensure consistency:

– allowStoreCredit:true is rejected if the contract has no lines.

– allowStoreCredit:true is rejected if any line’s selling plan disables store credit (fixed plans count as disabled).

– allowStoreCredit:true is allowed on lines without a selling plan.

– allowStoreCredit:false is always accepted.

When a calculation fails, the API returns an INVALID error on calculatedContract.paymentConfiguration.allowStoreCredit, and a subscriptionDraftCommit will surface a user‑facing INVALID error.

Who Is Affected: Developers vs. Merchants

Developers building subscription‑based apps or custom checkout flows are the primary audience—this is where you’ll set or read the new flag. Existing apps that create or manage selling plans, subscription contracts, or drafts will see the new fields appear in the schema, but nothing will break because the default value remains false. In other words, your current subscriptions continue to operate as before until you opt‑in to store‑credit support.

Merchants who run storefronts benefit indirectly. Once a developer enables the feature, customers can choose to apply any available store credit at checkout, and Shopify will automatically deduct the credit before charging the saved payment method. No manual configuration is required on the merchant side.

How to Implement Store Credit in Your Apps

Even though no mandatory migration is required, adding store‑credit support is straightforward. Follow these three steps:

1️⃣ Enable the flag on selling plans when you create or update them.

2️⃣ Pass the flag when you create or calculate a subscription contract.

3️⃣ After each calculation, verify that the returned allowStoreCredit value matches what you sent—if it differs, abort the commit and adjust your input.

Below is a minimal GraphQL mutation that creates a selling plan group with store‑credit enabled:

graphql

mutation CreateSellingPlanGroup {

sellingPlanGroupCreate(

input: {

name: "Monthly – Store Credit Enabled"

sellingPlansToCreate: [

{

name: "Monthly Plan"

billingPolicy: {

recurring: {

interval: MONTHLY

paymentConfiguration: {

allowStoreCredit: true

}

}

}

priceAdjustments: [{adjustmentType: PERCENTAGE, adjustmentValue: 0}]

}

]

}

) {

sellingPlanGroup {

id

name

sellingPlans {

id

billingPolicy {

... on SellingPlanRecurringBillingPolicy {

paymentConfiguration {

allowStoreCredit

}

}

}

}

}

userErrors { field message }

}

}

When you later create a subscription contract (or draft), include the same flag:

graphql

mutation CreateSubscriptionContract {

subscriptionContractCreate(

input: {

customerId: "gid://shopify/Customer/123456789"

lineItems: [{ sellingPlanId: "gid://shopify/SellingPlan/987654321", quantity: 1 }]

paymentConfiguration: { allowStoreCredit: true }

}

) {

subscriptionContract {

id

paymentConfiguration {

allowStoreCredit

}

}

userErrors { field message }

}

}

If you’re using the calculation API to preview a renewal, remember to read the returned calculatedContract.paymentConfiguration.allowStoreCredit and compare it to your request. A mismatch signals that a line’s selling plan does not permit credit, and you should either adjust the plan or fallback to a non‑credit flow.

Testing & Validation Tips

• Create a test store credit balance via the admin UI or the Store Credit API, then run a checkout using a subscription product that has allowStoreCredit:true. Verify that the credit is applied before the card is charged (you can inspect the order’s payment gateway response).

• Attempt to set allowStoreCredit:true on a contract that references a fixed selling plan – you should receive an INVALID error. This confirms the validation logic is active.

• Use GraphQL Playground’s “Headers” tab to force API version 2027-01 or newer, ensuring the new fields appear in the schema.

Next Steps & Takeaways

Store credit is now a first‑class citizen for Shopify subscriptions. While existing setups keep working out of the box, enabling the new allowStoreCredit flag can boost conversion by letting loyal customers apply earned credit to recurring orders. For developers, the change is limited to adding a boolean in the appropriate input objects and handling the optional validation error. For merchants, the benefit is immediate once an integrated app toggles the feature on.

Ready to add store‑credit support? Review the “Use store credit with subscriptions” guide, update your selling‑plan creation logic, and test in a sandbox store. If you have questions or need a code review, drop a comment below or reach out to our Shopify developer community.

Tags
Sources

Related Articles

Why Network Access Declarations Are Now Mandatory for Online Store Apps

Why Network Access Declarations Are Now Mandatory for Online Store Apps

Shopify now requires apps that run on the online store to declare their network access in shopify.app.toml. Learn what changed, who’s affected, and how to update your app before the December 2026 deadline.

November 19, 20264 min
Understanding the New applyResult Field in RolloutChange: What Developers Need to Know

Understanding the New applyResult Field in RolloutChange: What Developers Need to Know

Shopify’s GraphQL Admin API now returns an applyResult field on RolloutChange, letting apps track rollout outcomes in real time. Learn what changed, who it affects, and how to update your code to handle success, failure, and in‑progress states.

November 19, 20264 min

November 19, 20261 min
Why `abandonedCheckoutUrl` Now Needs Level 2 Protected Customer Data Access (and What to Do)

Why `abandonedCheckoutUrl` Now Needs Level 2 Protected Customer Data Access (and What to Do)

Starting Dec 1 2026 for public apps, Shopify requires level 2 protected customer data access to read abandonedCheckoutUrl. Learn who is affected, why the change matters, and how to update your app before the deadline.

November 19, 20264 min