2021-01 release notes
| Release date | Date version is no longer supported |
|---|---|
| January 1, 2021 | January 1, 2022 |
The 2021-01 release contains native support for subscriptions through our new Subscription APIs.
This release also includes support for scheduled fulfillments to facilitate prepaid subscriptions, automatic activation of app charges, and more granular financial information on orders and transactions, such as fees and tip totals.
What’s new in 2021-01
The following features were added in version 2021-01 of Shopify's APIs:
- We've included several new endpoints and resources to help you manage subscriptions on behalf of merchants. You can use selling plans to set delivery, billing, and pricing policies for groups of products. When a customer places an order that includes a product with a selling plan, you can manage subscription contracts to support recurring payments on the customer payment methods that are available.
- We've released a product subscription app extension that allows you to manage subscriptions directly inside the Shopify admin.
- Fulfillment orders now support the
SCHEDULEDstatus, which displays for any orders that include a prepaid subscription. To learn more about how fulfillments and subscriptions work together, refer to the Create and manage fulfillments for prepaid subscriptions. - Accepted application charges now automatically transition into an
activestate. To learn more about creating and issuing charges, refer to Charging for your app with the REST Admin API. - The new
TransactionFeeobject includes more detailed information about fees collected as a part of Shopify Payments payouts, including the flat rate charges, percentage charges, and a breakdown of the tax charged on these fees. - The GraphQL Admin API now includes tips received as a part of an order in both shop and presentment currencies using the
totalTipReceivedSetfield on theOrderobject. This increased granularity helps accounting apps report accurately on fees and tips for order transactions.
Breaking changes
Anchor link to section titled "Breaking changes"These changes require special attention. If your app uses these API resources, and you don’t adjust your usage of the resources according to the following instructions, then your app might break when you update to this API version.
Status field in REST FulfillmentOrder resource
Anchor link to section titled "Status field in REST FulfillmentOrder resource"As of the 2021-01 API version, we've added a new scheduled value to the status field in the FulfillmentOrder resource.
For more information, refer to Managing prepaid subscription orders.
Auto-activate billing charges using the REST Admin API
Anchor link to section titled "Auto-activate billing charges using the REST Admin API"We've removed the accepted value for the status field and the activate endpoint on the ApplicationCharge and RecurringApplicationCharge resources.
As of the 2021-01 API version, 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.
Cursor-based pagination
Anchor link to section titled "Cursor-based pagination"The /admin/api/{version}/users.json endpoint now supports cursor-based pagination.
GraphQL Admin API changes
Anchor link to section titled "GraphQL Admin API changes"Below are all the changes currently introduced in the 2021-01 version of the GraphQL Admin API.
Subscription APIs
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
CustomerPaymentMethodCreditCardCreatewas addedCustomerPaymentMethodSendUpdateEmailwas addedCustomerPaymentMethodCreditCardUpdatewas addedCustomerPaymentMethodRemoteCreditCardCreatewas addedCustomerPaymentMethodRevokewas addedProductJoinSellingPlanGroupswas addedProductLeaveSellingPlanGroupswas addedProductVariantJoinSellingPlanGroupswas addedProductVariantLeaveSellingPlanGroupswas addedSellingPlanGroupAddProductVariantswas addedSellingPlanGroupAddProductswas addedSellingPlanGroupCreatewas addedSellingPlanGroupDeletewas addedSellingPlanGroupRemoveProductVariantswas addedSellingPlanGroupRemoveProductswas addedSellingPlanGroupUpdatewas addedSubscriptionBillingAttemptCreatewas addedSubscriptionContractCreatewas addedSubscriptionContractSetNextBillingDatewas addedSubscriptionContractUpdatewas addedSubscriptionDraftCommitwas addedSubscriptionDraftDiscountAddwas addedSubscriptionDraftDiscountCodeApplywas addedSubscriptionDraftDiscountRemovewas addedSubscriptionDraftDiscountUpdatewas addedSubscriptionDraftFreeShippingDiscountAddwas addedSubscriptionDraftFreeShippingDiscountUpdatewas addedSubscriptionDraftLineAddwas addedSubscriptionDraftLineRemovewas addedSubscriptionDraftLineUpdatewas addedSubscriptionDraftUpdatewas added
New types
CustomerCreditCardobject was addedCustomerPaymentMethodobject was addedCustomerPaymentInstrumentunion type was addedDiscountTargetTypeenum was addedDiscountTypeenum was addedFailureobject was addedLastPaymentStatusenum was addedLineItemSellingPlanobject was addedSellingPlanobject was addedSellingPlanAnchorInputinput object was addedSellingPlanAnchorobject was addedSellingPlanBillingPolicyInputinput object was addedSellingPlanBillingPolicyobject was addedSellingPlanDeliveryPolicyInputinput object was addedSellingPlanDeliveryPolicyobject was addedSellingPlanFixedPricingPolicyInputinput object was addedSellingPlanFixedPricingPolicyobject was addedSellingPlanGroupInputinput object was addedSellingPlanGroupResourceInputinput object was addedSellingPlanGroupobject was addedSellingPlanInputinput object was addedSellingPlanOptionobject was addedSellingPlanPricingPolicyAdjustmentTypeenum was addedSellingPlanPricingPolicyAdjustmentValueunion type was addedSellingPlanPricingPolicyBaseinterface type was addedSellingPlanPricingPolicyInputinput object was addedSellingPlanPricingPolicyPercentageValueobject was addedSellingPlanPricingPolicyValueInputinput object was addedSellingPlanPricingPolicyunion type was addedSellingPlanRecurringBillingPolicyInputinput object was addedSellingPlanRecurringBillingPolicyobject was addedSellingPlanRecurringDeliveryPolicyInputinput object was addedSellingPlanRecurringDeliveryPolicyobject was addedSellingPlanRecurringPricingPolicyInputinput object was addedSellingPlanRecurringPricingPolicyobject was addedSubscriptionAppliedCodeDiscountobject was addedSubscriptionBillingAttemptInputinput object was addedSubscriptionBillingAttemptobject was addedSubscriptionBillingPolicyInputinput object was addedSubscriptionBillingPolicyobject was addedSubscriptionContractCreateInputinput object was addedSubscriptionContractobject was addedSubscriptionStatusenum was addedSubscriptionCyclePriceAdjustmentobject was addedSubscriptionDeliveryMethodInputinput object was addedSubscriptionDeliveryMethodShippingInputinput object was addedSubscriptionDeliveryMethodShippingOptionInputinput object was addedSubscriptionDeliveryMethodShippingOptionobject was addedSubscriptionDeliveryMethodShippingobject was addedSubscriptionDeliveryPolicyInputinput object was addedSubscriptionDeliveryPolicyobject was addedSubscriptionDiscountAllocationobject was addedSubscriptionDiscountEntitledLinesobject was addedSubscriptionDiscountFixedAmountValueobject was addedSubscriptionDiscountPercentageValueobject was addedSubscriptionDiscountRejectionReasonenum was addedSubscriptionDiscountValueunion type was addedSubscriptionDiscountunion type was addedSubscriptionDraftInputinput object was addedSubscriptionDraftobject was addedSubscriptionFreeShippingDiscountInputinput object was addedSubscriptionLineInputinput object was addedSubscriptionLineUpdateInputinput object was addedSubscriptionLineobject was addedSubscriptionMailingAddressobject was addedSubscriptionManualDiscountEntitledLinesInputinput object was addedSubscriptionManualDiscountFixedAmountInputinput object was addedSubscriptionManualDiscountInputinput object was addedSubscriptionManualDiscountLinesInputinput object was addedSubscriptionManualDiscountValueInputinput object was addedSubscriptionManualDiscountobject was addedSubscriptionPricingPolicyobject was addedSubscriptionShippingOptionobject was addedSubscriptionShippingOptionResultunion type was added
New fields
appliesOnOneTimePurchasewas added to objectDiscountCodeFreeShippingappliesOnOneTimePurchasewas added to input objectDiscountCodeFreeShippingInputappliesOnOneTimePurchasewas added to input objectDiscountCustomerGetsInputappliesOnOneTimePurchasewas added to objectDiscountCustomerGetsappliesOnSubscriptionwas added to input objectDiscountCodeFreeShippingInputappliesOnSubscriptionwas added to objectDiscountCodeFreeShippingappliesOnSubscriptionwas added to input objectDiscountCustomerGetsInputappliesOnSubscriptionwas added to objectDiscountCustomerGetscontractwas added to objectLineItemcustomerPaymentMethodwas added to objectQueryRootcustomerPaymentMethodwas added to objectOrderPaymentCollectionDetailseligibleForSubscriptionMigrationwas added to objectShopFeatureseligibleForSubscriptionswas added to objectShopFeatureslegacySubscriptionGatewayEnabledwas added to objectShopFeaturesmessagewas added to union typeSubscriptionShippingOptionResultpaymentMethodswas added to objectCustomerproductSubscriberStatuswas added to objectCustomerrecurringCycleLimitwas added to input objectDiscountCodeBasicInputrecurringCycleLimitwas added to objectDiscountCodeBasicrecurringCycleLimitwas added to input objectDiscountCodeFreeShippingInputrecurringCycleLimitwas added to objectDiscountCodeFreeShippingrequiresSellingPlanwas added to input objectProductInputrequiresSellingPlanwas added to objectProductsellingPlanwas added to objectLineItemsellingPlanGroupsToAssociatewas added to input objectProfileInputsellingPlanGroupsToDissociatewas added to input objectProfileInputsellingPlanGroupCountwas added to objectProductVariantsellingPlanGroupwas added to objectQueryRootshippingOptionswas added to objectSubscriptionDraftsubscriptionContractwas added to objectQueryRootsubscriptionDraftwas added to objectQueryRoot
New connection
sellingPlanGroupswas added to objectProfilesellingPlanGroupswas added to objectQueryRootsubscriptionContractswas added to objectCustomerPaymentMethodsubscriptionContractswas added to objectCustomersubscriptionContractswas added to objectQueryRoot
New error codes
BillingAttemptUserErrorwas addedCustomerPaymentMethodUserErrorwas addedAPPLIES_ON_NOTHINGwas added toPriceRuleErrorCodeMULTIPLE_RECURRING_CYCLE_LIMIT_FOR_NON_SUBSCRIPTION_ITEMSwas added toPriceRuleErrorCodeSellingPlanGroupUserErrorwas addedSellingPlanUserErrorwas addedSubscriptionContractUserErrorwas addedSubscriptionDraftUserErrorwas added
Managing prepaid subscription orders
As 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.
- To learn how to manage orders for prepaid subscriptions, refer to Manage orders for prepaid subscriptions.
- For information on managing fulfillments for prepaid subscriptions, refer to Create and manage fulfillments for prepaid subscriptions.
- If you need to manage advanced fulfillment scenarios for subscriptions, then refer to Handling advanced scenarios for subscription-based fulfillment orders.
New mutations
FulfillmentOrderOpenwas addedFulfillmentOrderReschedulewas added
New and updated types
mark_as_openvalue was added to enumFulfillmentOrderActionscheduledvalue was added to enumFulfillmentStatusscheduledvalue was added to enumFulfillmentOrderStatusscheduledvalue was added to enumOrderDisplayFulfillmentStatus
New field
fulfillAtwas added to objectFulfillmentOrder
Subscription-related webhooks
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/CREATEvalue was added to enumWebhookSubscriptionTopicSUBSCRIPTION_CONTRACTS/UPDATEvalue was added to enumWebhookSubscriptionTopicSUBSCRIPTION_BILLING_ATTEMPTS/SUCCESSvalue was added to enumWebhookSubscriptionTopicSUBSCRIPTION_BILLING_ATTEMPTS/FAILUREvalue was added to enumWebhookSubscriptionTopicCUSTOMER_PAYMENT_METHODS/CREATEvalue was added to enumWebhookSubscriptionTopicCUSTOMER_PAYMENT_METHODS/UPDATEvalue was added to enumWebhookSubscriptionTopicCUSTOMER_PAYMENT_METHODS/REVOKEvalue was added to enumWebhookSubscriptionTopic
Extended authorizations
As of API version 2021-01, you can query the GraphQL Admin API to access information about extended authorization periods.
New types
ShopifyPaymentsExtendedAuthorizationobject was addedShopifyPaymentsTransactionSetobject was added
New fields
authorizationExpiresAtfield was added to objectOrderTransactionshopifyPaymentsSetfield was added to objectOrderTransactionstandardAuthorizationExpiresAtfield was added to objectShopifyPaymentsExtendedAuthorizationextendedAuthorizationExpiresAtfield was added to objectShopifyPaymentsExtendedAuthorizationextendedAuthorizationSetfield was added to objectShopifyPaymentsTransactionSet
New value
EXPIREDvalue was added to enumOrderDisplayFinancialStatus
Transaction fees
As 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:
- How fees are calculated and subtracted from payouts
- How a particular transaction fee rate is used
- How transaction fees were charged in a historical context
New type
TransactionFeeobject was added
New fields
feesfield was added to objectOrderTransactionsettlementCurrencyfield was added to objectOrderTransactionsettlementCurrencyRatefield was added to objectOrderTransaction
APIs for payments provider apps
As 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
PaymentSessionobject was addedPaymentsAppConfigurationobject was added
New mutations
paymentSessionRejectwas addedpaymentSessionResolvewas addedpaymentsAppConfigurewas added
Fulfillments picked up by customers
As 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_UPvalue was added to enumFulfillmentDisplayStatus
Tips on orders
As 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
totalTipReceivedSetfield was added to objectOrder
Image dimensions
As 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
widthfield was added to objectImageheightfield was added to objectImage
Localization extensions
As of API version 2021-01, you can add localization extensions when you create a new order.
New fields
localizationExtensionsfield was added to objectDraftOrderInputlocalizationExtensionsfield was added to objectOrderInputkeyfield was added to objectLocalizationExtension
New connection
localizationExtensionsconnection was added to objectDraftOrder
New types
HasLocalizationExtensionsForDraftOrderswas addedLocalizationExtensionInputinput object was addedLocalizationExtensionKeyenum was added
Translated Country and Province names
As 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
translatedNamefield was added to objectDeliveryCountrytranslatedNamefield was added to objectDeliveryProvince
GraphQL Storefront API changes
Anchor link to section titled "GraphQL Storefront API changes"Below are all the changes currently introduced in the 2021-01 version of the GraphQL Storefront API.
Managing prepaid subscription orders
As 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
scheduledvalue was added to enumOrderFulfillmentStatus
Image dimensions
As 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
widthfield was added to objectImageheightfield was added to objectImage
Sort order for product media
As 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
sortKeywas added to connectionmediain objectProduct
REST Admin API changes
Anchor link to section titled "REST Admin API changes"Below are all the changes currently introduced in the 2021-01 version of the REST Admin API.
Cursor-based pagination
As 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.jsonwas updated to support cursor-based pagination
Managing prepaid subscription orders
As 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_atfield was added to resourceFulfillmentOrder- scheduled value was added to
statusfield in resourceFulfillmentOrder- Valid values for
status: open, in_progress, scheduled, cancelled, incomplete, closed
- Valid values for
Auto-activate billing charges
To 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
acceptedvalue was removed fromstatusfield in resourceApplicationChargeacceptedvalue was removed fromstatusfield in resourceRecurringApplicationCharge
Removed endpoints
POST /admin/api/2021-01/application_charges/{application_charge_id}/activate.jsonendpoint was removed from resourceApplicationChargePOST /admin/api/2021-01/recurring_application_charges/{recurring_application_charge_id}/activate.jsonendpoint was removed from resourceRecurringApplicationCharge
Extended authorization
As of API version 2021-01, you can query the Transaction resource to access information about extended authorization periods.
New fields
authorization_expires_atfield was added to resourceTransactionextended_authorization_attributesfield was added to resourceTransaction
Script tag caching
As 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
cachefield was added to resourceScriptTag
New endpoint for tracking deprecated API calls
As 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.
Subscription-related webhooks
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/createtopic was added to webhook resourcesubscription_contracts/updatetopic was added to webhook resourcesubscription_billing_attempts/failuretopic was added to webhook resourcesubscription_billing_attempts/successtopic was added to webhook resourcecustomer_payment_methods/createtopic was added to webhook resourcecustomer_payment_methods/revoketopic was added to webhook resourcecustomer_payment_methods/updatetopic was added to webhook resource