| Release date | Date version is no longer supported |
|---|---|
| January 1, 2021 | January 1, 2022 |
We've added the new subscription APIs to enable you to build support for subscriptions into the cart and product pages on the storefront.
You can use subscription APIs to sell goods and services in multiple ways. For example, you can sell a product as a one-time purchase or as a recurring subscription.
Subscription APIs
Selling plan APIs: An alternative way to sell a product or variant, other than "buy now".
Subscription contract APIs: The subscription agreements between a customer and merchant.
Customer payment method APIs: Stored payment methods that can be used to pay for future orders without requiring the customer to manually go through checkout.
For more information about subscription APIs, refer to Shopify subscriptions overview.
New mutations
CustomerPaymentMethodCreditCardCreate was addedCustomerPaymentMethodSendUpdateEmail was addedCustomerPaymentMethodCreditCardUpdate was addedCustomerPaymentMethodRemoteCreditCardCreate was addedCustomerPaymentMethodRevoke was addedProductJoinSellingPlanGroups was addedProductLeaveSellingPlanGroups was addedProductVariantJoinSellingPlanGroups was addedProductVariantLeaveSellingPlanGroups was addedSellingPlanGroupAddProductVariants was addedSellingPlanGroupAddProducts was addedSellingPlanGroupCreate was addedSellingPlanGroupDelete was addedSellingPlanGroupRemoveProductVariants was addedSellingPlanGroupRemoveProducts was addedSellingPlanGroupUpdate was addedSubscriptionBillingAttemptCreate was addedSubscriptionContractCreate was addedSubscriptionContractSetNextBillingDate was addedSubscriptionContractUpdate was addedSubscriptionDraftCommit was addedSubscriptionDraftDiscountAdd was addedSubscriptionDraftDiscountCodeApply was addedSubscriptionDraftDiscountRemove was addedSubscriptionDraftDiscountUpdate was addedSubscriptionDraftFreeShippingDiscountAdd was addedSubscriptionDraftFreeShippingDiscountUpdate was addedSubscriptionDraftLineAdd was addedSubscriptionDraftLineRemove was addedSubscriptionDraftLineUpdate was addedSubscriptionDraftUpdate was addedNew types
CustomerCreditCard object was addedCustomerPaymentMethod object was addedCustomerPaymentInstrument union type was addedDiscountTargetType enum was addedDiscountType enum was addedFailure object was addedLastPaymentStatus enum was addedLineItemSellingPlan object was addedSellingPlan object was addedSellingPlanAnchorInput input object was addedSellingPlanAnchor object was addedSellingPlanBillingPolicyInput input object was addedSellingPlanBillingPolicy object was addedSellingPlanDeliveryPolicyInput input object was addedSellingPlanDeliveryPolicy object was addedSellingPlanFixedPricingPolicyInput input object was addedSellingPlanFixedPricingPolicy object was addedSellingPlanGroupInput input object was addedSellingPlanGroupResourceInput input object was addedSellingPlanGroup object was addedSellingPlanInput input object was addedSellingPlanOption object was addedSellingPlanPricingPolicyAdjustmentType enum was addedSellingPlanPricingPolicyAdjustmentValue union type was addedSellingPlanPricingPolicyBase interface type was addedSellingPlanPricingPolicyInput input object was addedSellingPlanPricingPolicyPercentageValue object was addedSellingPlanPricingPolicyValueInput input object was addedSellingPlanPricingPolicy union type was addedSellingPlanRecurringBillingPolicyInput input object was addedSellingPlanRecurringBillingPolicy object was addedSellingPlanRecurringDeliveryPolicyInput input object was addedSellingPlanRecurringDeliveryPolicy object was addedSellingPlanRecurringPricingPolicyInput input object was addedSellingPlanRecurringPricingPolicy object was addedSubscriptionAppliedCodeDiscount object was addedSubscriptionBillingAttemptInput input object was addedSubscriptionBillingAttempt object was addedSubscriptionBillingPolicyInput input object was addedSubscriptionBillingPolicy object was addedSubscriptionContractCreateInput input object was addedSubscriptionContract object was addedSubscriptionStatus enum was addedSubscriptionCyclePriceAdjustment object was addedSubscriptionDeliveryMethodInput input object was addedSubscriptionDeliveryMethodShippingInput input object was addedSubscriptionDeliveryMethodShippingOptionInput input object was addedSubscriptionDeliveryMethodShippingOption object was addedSubscriptionDeliveryMethodShipping object was addedSubscriptionDeliveryPolicyInput input object was addedSubscriptionDeliveryPolicy object was addedSubscriptionDiscountAllocation object was addedSubscriptionDiscountEntitledLines object was addedSubscriptionDiscountFixedAmountValue object was addedSubscriptionDiscountPercentageValue object was addedSubscriptionDiscountRejectionReason enum was addedSubscriptionDiscountValue union type was addedSubscriptionDiscount union type was addedSubscriptionDraftInput input object was addedSubscriptionDraft object was addedSubscriptionFreeShippingDiscountInput input object was addedSubscriptionLineInput input object was addedSubscriptionLineUpdateInput input object was addedSubscriptionLine object was addedSubscriptionMailingAddress object was addedSubscriptionManualDiscountEntitledLinesInput input object was addedSubscriptionManualDiscountFixedAmountInput input object was addedSubscriptionManualDiscountInput input object was addedSubscriptionManualDiscountLinesInput input object was addedSubscriptionManualDiscountValueInput input object was addedSubscriptionManualDiscount object was addedSubscriptionPricingPolicy object was addedSubscriptionShippingOption object was addedSubscriptionShippingOptionResult union type was addedNew fields
appliesOnOneTimePurchase was added to object DiscountCodeFreeShippingappliesOnOneTimePurchase was added to input object DiscountCodeFreeShippingInputappliesOnOneTimePurchase was added to input object DiscountCustomerGetsInputappliesOnOneTimePurchase was added to object DiscountCustomerGetsappliesOnSubscription was added to input object DiscountCodeFreeShippingInputappliesOnSubscription was added to object DiscountCodeFreeShippingappliesOnSubscription was added to input object DiscountCustomerGetsInputappliesOnSubscription was added to object DiscountCustomerGetscontract was added to object LineItemcustomerPaymentMethod was added to object QueryRootcustomerPaymentMethod was added to object OrderPaymentCollectionDetailseligibleForSubscriptionMigration was added to object ShopFeatureseligibleForSubscriptions was added to object ShopFeatureslegacySubscriptionGatewayEnabled was added to object ShopFeaturesmessage was added to union type SubscriptionShippingOptionResultpaymentMethods was added to object CustomerproductSubscriberStatus was added to object CustomerrecurringCycleLimit was added to input object DiscountCodeBasicInputrecurringCycleLimit was added to object DiscountCodeBasicrecurringCycleLimit was added to input object DiscountCodeFreeShippingInputrecurringCycleLimit was added to object DiscountCodeFreeShippingrequiresSellingPlan was added to input object ProductInputrequiresSellingPlan was added to object ProductsellingPlan was added to object LineItemsellingPlanGroupsToAssociate was added to input object ProfileInputsellingPlanGroupsToDissociate was added to input object ProfileInputsellingPlanGroupCount was added to object ProductVariantsellingPlanGroup was added to object QueryRootshippingOptions was added to object SubscriptionDraftsubscriptionContract was added to object QueryRootsubscriptionDraft was added to object QueryRootNew connection
sellingPlanGroups was added to object ProfilesellingPlanGroups was added to object QueryRootsubscriptionContracts was added to object CustomerPaymentMethodsubscriptionContracts was added to object CustomersubscriptionContracts was added to object QueryRootNew error codes
BillingAttemptUserError was addedCustomerPaymentMethodUserError was addedAPPLIES_ON_NOTHING was added to PriceRuleErrorCodeMULTIPLE_RECURRING_CYCLE_LIMIT_FOR_NON_SUBSCRIPTION_ITEMS was added to PriceRuleErrorCodeSellingPlanGroupUserError was addedSellingPlanUserError was addedSubscriptionContractUserError was addedSubscriptionDraftUserError was addedAs of API version 2021-01, we've added support for managing prepaid subscription orders. You can now create an order with multiple billing or payment schedules along with multiple fulfillment orders.
New mutations
FulfillmentOrderOpen was addedFulfillmentOrderReschedule was addedNew and updated types
mark_as_open value was added to enum FulfillmentOrderActionscheduled value was added to enum FulfillmentStatusscheduled value was added to enum FulfillmentOrderStatusscheduled value was added to enum OrderDisplayFulfillmentStatusNew field
fulfillAt was added to object FulfillmentOrderYou can now subscribe to subscription contracts, billing attempts, and customer payment methods event webhooks.
For detailed information about required scopes and payloads, refer to Subscription-related webhooks.
New topics
SUBSCRIPTION_CONTRACTS/CREATE value was added to enum WebhookSubscriptionTopicSUBSCRIPTION_CONTRACTS/UPDATE value was added to enum WebhookSubscriptionTopicSUBSCRIPTION_BILLING_ATTEMPTS/SUCCESS value was added to enum WebhookSubscriptionTopicSUBSCRIPTION_BILLING_ATTEMPTS/FAILURE value was added to enum WebhookSubscriptionTopicCUSTOMER_PAYMENT_METHODS/CREATE value was added to enum WebhookSubscriptionTopicCUSTOMER_PAYMENT_METHODS/UPDATE value was added to enum WebhookSubscriptionTopicCUSTOMER_PAYMENT_METHODS/REVOKE value was added to enum WebhookSubscriptionTopicAs of API version 2021-01, you can query the GraphQL Admin API to access information about extended authorization periods.
New types
ShopifyPaymentsExtendedAuthorization object was addedShopifyPaymentsTransactionSet object was addedNew fields
authorizationExpiresAt field was added to object OrderTransactionshopifyPaymentsSet field was added to object OrderTransactionstandardAuthorizationExpiresAt field was added to object ShopifyPaymentsExtendedAuthorizationextendedAuthorizationExpiresAt field was added to object ShopifyPaymentsExtendedAuthorizationextendedAuthorizationSet field was added to object ShopifyPaymentsTransactionSetNew value
EXPIRED value was added to enum OrderDisplayFinancialStatusAs of API version 2021-01, you can query the GraphQL Admin API to access the details of transaction fees charged on Shopify Payments transactions.
For example, you can now reconcile transaction fee amounts with external accounting systems. You can also better understand the following:
New type
TransactionFee object was addedNew fields
fees field was added to object OrderTransactionsettlementCurrency field was added to object OrderTransactionsettlementCurrencyRate field was added to object OrderTransactionAs of the 2021-01 API version, you can query the GraphQL Admin API for details about a payment processing session and the configuration of a payments provider app.
New types
PaymentSession object was addedPaymentsAppConfiguration object was addedNew mutations
paymentSessionReject was addedpaymentSessionResolve was addedpaymentsAppConfigure was addedAs of API version 2021-01, you can query the GraphQL Admin API to determine which fulfillments have been picked up by customers.
New types
PICKED_UP value was added to enum FulfillmentDisplayStatusAs of API version 2021-01, you can query the GraphQL Admin API to determine the total tip received for an order in shop and presentment currencies.
New field
totalTipReceivedSet field was added to object OrderAs of API version 2021-01, you can query the GraphQL Admin API to determine the width and height (in pixels) of images hosted by Shopify.
New fields
width field was added to object Imageheight field was added to object ImageAs of API version 2021-01, you can add localization extensions when you create a new order.
New fields
localizationExtensions field was added to object DraftOrderInputlocalizationExtensions field was added to object OrderInputkey field was added to object LocalizationExtensionNew connection
localizationExtensions connection was added to object DraftOrderNew types
HasLocalizationExtensionsForDraftOrders was addedLocalizationExtensionInput input object was addedLocalizationExtensionKey enum was addedAs of API version 2021-01, you can query the translated names of DeliveryCountry and DeliveryProvince. The translated name is based on the user locale.
New fields
translatedName field was added to object DeliveryCountrytranslatedName field was added to object DeliveryProvinceAs of API version 2021-01, we've added support for managing prepaid subscription orders. You can now create an order with multiple billing or payment schedules along with multiple fulfillment orders.
Updated type
scheduled value was added to enum OrderFulfillmentStatusAs of API version 2021-01, you can query the Storefront API to determine the width and height (in pixels) of images hosted by Shopify.
New fields
width field was added to object Imageheight field was added to object ImageAs of API version 2021-01, you can sort product media by a given key. The default sort order is by POSITION. In previous API versions, product media was sorted by the CREATED_AT value by default.
New argument
sortKey was added to connection media in object ProductAs of API version 2021-01, the /admin/api/{version}/users.json endpoint supports cursor-based pagination.
Use the /admin/api/{version}/users.json endpoint to request paginated user data from the REST Admin API and access each page of results.
Updated endpoint
admin/api/{version}/users.json was updated to support cursor-based paginationAs of API version 2021-01, we've added support for managing prepaid subscription orders. You can now create an order with multiple billing or payment schedules along with multiple fulfillment orders.
New endpoints
/admin/api/2021-01/fulfillment_orders/{fulfillment_order_id}/open.json: Marks a fulfillment order as open./admin/api/2021-01/fulfillment_orders/{fulfillment_order_id}/reschedule.json: Reschedules the fulfill_at time of a scheduled fulfillment order.New and updated fields
fulfill_at field was added to resource FulfillmentOrderstatus field in resource FulfillmentOrder
status: open, in_progress, scheduled, cancelled, incomplete, closedTo simplify and streamline billing for your apps, we've removed the accepted value for the status field and the activate endpoint on the ApplicationCharge and RecurringApplicationCharge resources.
As of API version 2021-01, when a merchant accepts a charge, the charge immediately transitions from pending to active. This means that you no longer need to activate the charge to finalize it.
To learn more about creating and issuing charges, refer to Charging for your app with the REST Admin API.
Removed values
accepted value was removed from status field in resource ApplicationChargeaccepted value was removed from status field in resource RecurringApplicationChargeRemoved endpoints
POST /admin/api/2021-01/application_charges/{application_charge_id}/activate.json endpoint was removed from resource ApplicationChargePOST /admin/api/2021-01/recurring_application_charges/{recurring_application_charge_id}/activate.json endpoint was removed from resource RecurringApplicationChargeAs of API version 2021-01, you can query the Transaction resource to access information about extended authorization periods.
New fields
authorization_expires_at field was added to resource Transactionextended_authorization_attributes field was added to resource TransactionAs of API version 2021-01, you can query the ScriptTag resource to determine whether the Shopify CDN (content delivery network) can cache and serve a script tag.
New field
cache field was added to resource ScriptTagAs of API version 2021-01, you can use the Deprecated API calls endpoint to get a list of all the deprecated calls your private apps have made in the past 30 days, information on migration steps, and the deadline to update these calls in your apps.
New endpoint
/admin/api/2021-01/deprecated_api_calls.json: Retrieves a list of deprecated API calls.You can now subscribe to subscription contracts, billing attempts, and customer payment methods event webhooks.
For detailed information about required scopes and payloads, refer to Subscription-related webhooks.
New topics
subscription_contracts/create topic was added to webhook resourcesubscription_contracts/update topic was added to webhook resourcesubscription_billing_attempts/failure topic was added to webhook resourcesubscription_billing_attempts/success topic was added to webhook resourcecustomer_payment_methods/create topic was added to webhook resourcecustomer_payment_methods/revoke topic was added to webhook resourcecustomer_payment_methods/update topic was added to webhook resource