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.
