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 SCHEDULED status, 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 active state. To learn more about creating and issuing charges, refer to Charging for your app with the REST Admin API.
The new TransactionFee object 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 totalTipReceivedSet field on the Order object. 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

CustomerPaymentMethodCreditCardCreate was added
CustomerPaymentMethodSendUpdateEmail was added
CustomerPaymentMethodCreditCardUpdate was added
CustomerPaymentMethodRemoteCreditCardCreate was added
CustomerPaymentMethodRevoke was added
ProductJoinSellingPlanGroups was added
ProductLeaveSellingPlanGroups was added
ProductVariantJoinSellingPlanGroups was added
ProductVariantLeaveSellingPlanGroups was added
SellingPlanGroupAddProductVariants was added
SellingPlanGroupAddProducts was added
SellingPlanGroupCreate was added
SellingPlanGroupDelete was added
SellingPlanGroupRemoveProductVariants was added
SellingPlanGroupRemoveProducts was added
SellingPlanGroupUpdate was added
SubscriptionBillingAttemptCreate was added
SubscriptionContractCreate was added
SubscriptionContractSetNextBillingDate was added
SubscriptionContractUpdate was added
SubscriptionDraftCommit was added
SubscriptionDraftDiscountAdd was added
SubscriptionDraftDiscountCodeApply was added
SubscriptionDraftDiscountRemove was added
SubscriptionDraftDiscountUpdate was added
SubscriptionDraftFreeShippingDiscountAdd was added
SubscriptionDraftFreeShippingDiscountUpdate was added
SubscriptionDraftLineAdd was added
SubscriptionDraftLineRemove was added
SubscriptionDraftLineUpdate was added
SubscriptionDraftUpdate was added

New types

CustomerCreditCard object was added
CustomerPaymentMethod object was added
CustomerPaymentInstrument union type was added
DiscountTargetType enum was added
DiscountType enum was added
Failure object was added
LastPaymentStatus enum was added
LineItemSellingPlan object was added
SellingPlan object was added
SellingPlanAnchorInput input object was added
SellingPlanAnchor object was added
SellingPlanBillingPolicyInput input object was added
SellingPlanBillingPolicy object was added
SellingPlanDeliveryPolicyInput input object was added
SellingPlanDeliveryPolicy object was added
SellingPlanFixedPricingPolicyInput input object was added
SellingPlanFixedPricingPolicy object was added
SellingPlanGroupInput input object was added
SellingPlanGroupResourceInput input object was added
SellingPlanGroup object was added
SellingPlanInput input object was added
SellingPlanOption object was added
SellingPlanPricingPolicyAdjustmentType enum was added
SellingPlanPricingPolicyAdjustmentValue union type was added
SellingPlanPricingPolicyBase interface type was added
SellingPlanPricingPolicyInput input object was added
SellingPlanPricingPolicyPercentageValue object was added
SellingPlanPricingPolicyValueInput input object was added
SellingPlanPricingPolicy union type was added
SellingPlanRecurringBillingPolicyInput input object was added
SellingPlanRecurringBillingPolicy object was added
SellingPlanRecurringDeliveryPolicyInput input object was added
SellingPlanRecurringDeliveryPolicy object was added
SellingPlanRecurringPricingPolicyInput input object was added
SellingPlanRecurringPricingPolicy object was added
SubscriptionAppliedCodeDiscount object was added
SubscriptionBillingAttemptInput input object was added
SubscriptionBillingAttempt object was added
SubscriptionBillingPolicyInput input object was added
SubscriptionBillingPolicy object was added
SubscriptionContractCreateInput input object was added
SubscriptionContract object was added
SubscriptionStatus enum was added
SubscriptionCyclePriceAdjustment object was added
SubscriptionDeliveryMethodInput input object was added
SubscriptionDeliveryMethodShippingInput input object was added
SubscriptionDeliveryMethodShippingOptionInput input object was added
SubscriptionDeliveryMethodShippingOption object was added
SubscriptionDeliveryMethodShipping object was added
SubscriptionDeliveryPolicyInput input object was added
SubscriptionDeliveryPolicy object was added
SubscriptionDiscountAllocation object was added
SubscriptionDiscountEntitledLines object was added
SubscriptionDiscountFixedAmountValue object was added
SubscriptionDiscountPercentageValue object was added
SubscriptionDiscountRejectionReason enum was added
SubscriptionDiscountValue union type was added
SubscriptionDiscount union type was added
SubscriptionDraftInput input object was added
SubscriptionDraft object was added
SubscriptionFreeShippingDiscountInput input object was added
SubscriptionLineInput input object was added
SubscriptionLineUpdateInput input object was added
SubscriptionLine object was added
SubscriptionMailingAddress object was added
SubscriptionManualDiscountEntitledLinesInput input object was added
SubscriptionManualDiscountFixedAmountInput input object was added
SubscriptionManualDiscountInput input object was added
SubscriptionManualDiscountLinesInput input object was added
SubscriptionManualDiscountValueInput input object was added
SubscriptionManualDiscount object was added
SubscriptionPricingPolicy object was added
SubscriptionShippingOption object was added
SubscriptionShippingOptionResult union type was added

New fields

appliesOnOneTimePurchase was added to object DiscountCodeFreeShipping
appliesOnOneTimePurchase was added to input object DiscountCodeFreeShippingInput
appliesOnOneTimePurchase was added to input object DiscountCustomerGetsInput
appliesOnOneTimePurchase was added to object DiscountCustomerGets
appliesOnSubscription was added to input object DiscountCodeFreeShippingInput
appliesOnSubscription was added to object DiscountCodeFreeShipping
appliesOnSubscription was added to input object DiscountCustomerGetsInput
appliesOnSubscription was added to object DiscountCustomerGets
contract was added to object LineItem
customerPaymentMethod was added to object QueryRoot
customerPaymentMethod was added to object OrderPaymentCollectionDetails
eligibleForSubscriptionMigration was added to object ShopFeatures
eligibleForSubscriptions was added to object ShopFeatures
legacySubscriptionGatewayEnabled was added to object ShopFeatures
message was added to union type SubscriptionShippingOptionResult
paymentMethods was added to object Customer
productSubscriberStatus was added to object Customer
recurringCycleLimit was added to input object DiscountCodeBasicInput
recurringCycleLimit was added to object DiscountCodeBasic
recurringCycleLimit was added to input object DiscountCodeFreeShippingInput
recurringCycleLimit was added to object DiscountCodeFreeShipping
requiresSellingPlan was added to input object ProductInput
requiresSellingPlan was added to object Product
sellingPlan was added to object LineItem
sellingPlanGroupsToAssociate was added to input object ProfileInput
sellingPlanGroupsToDissociate was added to input object ProfileInput
sellingPlanGroupCount was added to object ProductVariant
sellingPlanGroup was added to object QueryRoot
shippingOptions was added to object SubscriptionDraft
subscriptionContract was added to object QueryRoot
subscriptionDraft was added to object QueryRoot

New connection

sellingPlanGroups was added to object Profile
sellingPlanGroups was added to object QueryRoot
subscriptionContracts was added to object CustomerPaymentMethod
subscriptionContracts was added to object Customer
subscriptionContracts was added to object QueryRoot

New error codes

BillingAttemptUserError was added
CustomerPaymentMethodUserError was added
APPLIES_ON_NOTHING was added to PriceRuleErrorCode
MULTIPLE_RECURRING_CYCLE_LIMIT_FOR_NON_SUBSCRIPTION_ITEMS was added to PriceRuleErrorCode
SellingPlanGroupUserError was added
SellingPlanUserError was added
SubscriptionContractUserError was added
SubscriptionDraftUserError was 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

FulfillmentOrderOpen was added
FulfillmentOrderReschedule was added

New and updated types

mark_as_open value was added to enum FulfillmentOrderAction
scheduled value was added to enum FulfillmentStatus
scheduled value was added to enum FulfillmentOrderStatus
scheduled value was added to enum OrderDisplayFulfillmentStatus

New field

fulfillAt was added to object FulfillmentOrder

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/CREATE value was added to enum WebhookSubscriptionTopic
SUBSCRIPTION_CONTRACTS/UPDATE value was added to enum WebhookSubscriptionTopic
SUBSCRIPTION_BILLING_ATTEMPTS/SUCCESS value was added to enum WebhookSubscriptionTopic
SUBSCRIPTION_BILLING_ATTEMPTS/FAILURE value was added to enum WebhookSubscriptionTopic
CUSTOMER_PAYMENT_METHODS/CREATE value was added to enum WebhookSubscriptionTopic
CUSTOMER_PAYMENT_METHODS/UPDATE value was added to enum WebhookSubscriptionTopic
CUSTOMER_PAYMENT_METHODS/REVOKE value was added to enum WebhookSubscriptionTopic

Extended authorizations

As of API version 2021-01, you can query the GraphQL Admin API to access information about extended authorization periods.

New types

ShopifyPaymentsExtendedAuthorization object was added
ShopifyPaymentsTransactionSet object was added

New fields

authorizationExpiresAt field was added to object OrderTransaction
shopifyPaymentsSet field was added to object OrderTransaction
standardAuthorizationExpiresAt field was added to object ShopifyPaymentsExtendedAuthorization
extendedAuthorizationExpiresAt field was added to object ShopifyPaymentsExtendedAuthorization
extendedAuthorizationSet field was added to object ShopifyPaymentsTransactionSet

New value

EXPIRED value was added to enum OrderDisplayFinancialStatus

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

TransactionFee object was added

New fields

fees field was added to object OrderTransaction
settlementCurrency field was added to object OrderTransaction
settlementCurrencyRate field was added to object OrderTransaction

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

PaymentSession object was added
PaymentsAppConfiguration object was added

New mutations

paymentSessionReject was added
paymentSessionResolve was added
paymentsAppConfigure was 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_UP value was added to enum FulfillmentDisplayStatus

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

totalTipReceivedSet field was added to object Order

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

width field was added to object Image
height field was added to object Image

Localization extensions

As of API version 2021-01, you can add localization extensions when you create a new order.

New fields

localizationExtensions field was added to object DraftOrderInput
localizationExtensions field was added to object OrderInput
key field was added to object LocalizationExtension

New connection

localizationExtensions connection was added to object DraftOrder

New types

HasLocalizationExtensionsForDraftOrders was added
LocalizationExtensionInput input object was added
LocalizationExtensionKey enum 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

translatedName field was added to object DeliveryCountry
translatedName field was added to object DeliveryProvince

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

scheduled value was added to enum OrderFulfillmentStatus

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

width field was added to object Image
height field was added to object Image

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

sortKey was added to connection media in object Product

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.json was 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_at field was added to resource FulfillmentOrder
scheduled value was added to status field in resource FulfillmentOrder
- Valid values for status: open, in_progress, scheduled, cancelled, incomplete, closed

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

accepted value was removed from status field in resource ApplicationCharge
accepted value was removed from status field in resource RecurringApplicationCharge

Removed endpoints

POST /admin/api/2021-01/application_charges/{application_charge_id}/activate.json endpoint was removed from resource ApplicationCharge
POST /admin/api/2021-01/recurring_application_charges/{recurring_application_charge_id}/activate.json endpoint was removed from resource RecurringApplicationCharge

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_at field was added to resource Transaction
extended_authorization_attributes field was added to resource Transaction

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

cache field was added to resource ScriptTag

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/create topic was added to webhook resource
subscription_contracts/update topic was added to webhook resource
subscription_billing_attempts/failure topic was added to webhook resource
subscription_billing_attempts/success topic was added to webhook resource
customer_payment_methods/create topic was added to webhook resource
customer_payment_methods/revoke topic was added to webhook resource
customer_payment_methods/update topic was added to webhook resource

2021-01 release notes

Breaking changes

Status field in REST FulfillmentOrder resource

Auto-activate billing charges using the REST Admin API

Cursor-based pagination

GraphQL Admin API changes

Subscription APIs

Managing prepaid subscription orders

Subscription-related webhooks

Extended authorizations

Transaction fees

APIs for payments provider apps

Fulfillments picked up by customers

Tips on orders

Image dimensions

Localization extensions

Translated Country and Province names

GraphQL Storefront API changes

Managing prepaid subscription orders

Image dimensions

Sort order for product media

REST Admin API changes

Cursor-based pagination

Managing prepaid subscription orders

Auto-activate billing charges

Extended authorization

Script tag caching

New endpoint for tracking deprecated API calls

Subscription-related webhooks

On this page