Update a subscription contract
Subscription contracts often require updates, such as when a customer needs to update their payment method or requests a change to their subscription.
This guide shows you how to manage and update your existing subscription contracts by creating and applying a discount code to a contract.
RequirementsAnchor link to section titled "Requirements"
- Your app can make authenticated requests to the GraphQL Admin API.
- Your app has the
write_own_subscription_contractsaccess scopes. For more information on requesting access scopes when your app is installed, refer to Getting started with OAuth.
You've created products and product variants in your development store.
You've created a subscription contract.
Step 1: Query the available contracts on the storeAnchor link to section titled "Step 1: Query the available contracts on the store"
To view the available contracts on a store, you can query
subscriptionContracts. In the following example, the response body returns the first ten available contracts, including the status of the contract and information about the customer, billing policy, and delivery policy.
For a list of possible statuses, refer to SubscriptionContractSubscriptionStatus.
Step 2: Create a draft of an existing contractAnchor link to section titled "Step 2: Create a draft of an existing contract"
When a customer updates their payment method or makes a change to their subscription, you need to update the appropriate subscription contract.
To update a subscription contract, use the
subscriptionContractUpdate mutation and supply the subscription contract ID. The call returns a draft with the existing state of the contract.
Step 3: Update the subscription draftAnchor link to section titled "Step 3: Update the subscription draft"
After retrieving the draft ID, you can begin making edits to the contract draft. Edits to the contract draft can be made incrementally. Changes to the contract draft aren't made live until the draft is committed.
Create a subscription discount codeAnchor link to section titled "Create a subscription discount code"
discountCodeBasicCreate mutation to create a basic discount code. To specify that the discount can be applied on subscriptions, set the
appliesOnSubscription field to
Apply the discount codeAnchor link to section titled "Apply the discount code"
subscriptionDraftDiscountCodeApply mutation to apply the discount code to the subscription draft:
Step 4: Commit the subscription draftAnchor link to section titled "Step 4: Commit the subscription draft"
When you commit the subscription draft, the changes that you've made become active on the subscription contract for which the draft was created. You can call the
subscriptionDraft query to review the information on the subscription draft before committing it.
After you're satisfied with your updates, you can call the
subscriptionDraftCommit mutation to commit your changes to the contract:
- Learn how to manage and edit billing cycles, including updating the schedule and contract information for a billing cycle, skipping a billing cycle or changing the contract information for one period.