2021-01 release notes

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.

Anchor to Breaking changesBreaking 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.

Anchor to Status field in REST FulfillmentOrder resourceStatus 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.

Anchor to Auto-activate billing charges using the REST Admin APIAuto-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.

Anchor to Cursor-based paginationCursor-based pagination

The /admin/api/{version}/users.json endpoint now supports cursor-based pagination.

Anchor to GraphQL Admin API changesGraphQL Admin API changes

Below are all the changes currently introduced in the 2021-01 version of the GraphQL Admin API.

Anchor to Subscription APIs,[object Object]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

Anchor to Managing prepaid subscription orders,[object Object]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

Anchor to Subscription-related webhooks,[object Object]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

Anchor to Extended authorizations ,[object Object]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

Anchor to Transaction fees,[object Object]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

Anchor to APIs for payments provider apps ,[object Object]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

Anchor to Fulfillments picked up by customers ,[object Object]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

Anchor to Tips on orders ,[object Object]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

Anchor to Image dimensions ,[object Object]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

Anchor to Localization extensions,[object Object]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

Anchor to Translated Country and Province names,[object Object]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

Anchor to GraphQL Storefront API changesGraphQL Storefront API changes

Below are all the changes currently introduced in the 2021-01 version of the GraphQL Storefront API.

Anchor to Managing prepaid subscription orders ,[object Object]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

Anchor to Image dimensions ,[object Object]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

Anchor to Sort order for product media ,[object Object]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

Anchor to REST Admin API changesREST Admin API changes

Below are all the changes currently introduced in the 2021-01 version of the REST Admin API.

Anchor to Cursor-based paginationCursor-based pagination

Anchor to BreakingBreaking

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

Anchor to Managing prepaid subscription ordersManaging prepaid subscription orders

Anchor to BreakingBreaking

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

Anchor to Auto-activate billing chargesAuto-activate billing charges

Anchor to BreakingBreaking

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

Anchor to Extended authorization ,[object Object]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

Anchor to Script tag caching ,[object Object]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

Anchor to New endpoint for tracking deprecated API calls ,[object Object]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.

Anchor to Subscription-related webhooks,[object Object]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