2020-10 release notes

Release date Date version is no longer supported
October 1, 2020 October 1, 2021

The 2020-10 release contains many changes to improve the experience of the Shopify API. This release includes the addition of checksums to the assets API, improvements to order editing, support for bulk operations when managing discounts, the addition of shipping lines and delivery methods to orders and fulfillment orders, and improvements to product management and filtering.

This release also includes an entirely new API that allows apps to read and manage shop Legal Policies.

What’s new in 2020-10

The following features were added in version 2020-10 of Shopify's APIs:

  • The Asset resource now includes a checksum property. This property dramatically improves the performance of Theme Kit.
  • Apps can now edit orders that they created. To determine if your app can edit an order on Shopify, you can query the merchantEditable field on the Order object.
  • Apps can now add discounts to line items while editing orders.
  • The Discounts API has received several upgrades in this version. It's now possible to retrieve usage counts for automatic discounts and perform bulk mutations to enable, disable, or delete large numbers of discounts codes with a single request.
  • The Order object now includes shippingLines, a list of line items that contains the shipping costs.
  • Fulfillment Orders now include a DeliveryMethodType, which specifies how an order was delivered. Possible values include LOCAL, NONE, PICK_UP, RETAIL, or SHIPPING.
  • Delivery Profiles now have support for profiles/create, profiles/update, and profiles/delete webhook topics.
  • The Product resource now supports a variety of statuses to manage and filter products: draft, active, and archived.
  • Apps can now read and write policies that merchants have configured for their store, such as their refund or privacy policies.

Breaking changes

These changes require special attention. If your app uses these API resources and you don’t upgrade to a more recent API version, then your app will break.

Tax field data

As of version 2020-10, you can no longer create or update any tax field data using the Country or Province resources.

Include risk analysis header

We've deprecated the include-risk-analysis header that includes order risks and risk analysis objects in the Order payload.

The existence of this deprecated header was not previously documented. The REST Admin API and GraphQL Admin API are not affected by this change.

If you request the header using an API version earlier than 2020-10, then the header will still be returned.

Type filter parameter

We've deprecated the type filter parameter on CodeDiscountQuery. Use discount_type instead. For more information about deprecated fields, refer to QueryRoot.

Deprecated fields in Refund and RefundLineItem objects

We've deprecated the following fields in the GraphQL Admin API:

  • restocked field in the Refund object. Use RefundLineItem.restockType instead.
  • refundType field in the RefundLineItem object. Use RefundLineItem.restockType instead.

GraphQL Admin API changes

Below are all the changes currently introduced in the 2020-10 version of the GraphQL Admin API.

We've deprecated the type filter parameter on CodeDiscountQuery. Use discount_type instead. For more information about deprecated fields, refer to QueryRoot.

We've deprecated the following fields in the GraphQL Admin API:

  • restocked field in the Refund object. Use RefundLineItem.restockType instead.
  • refundType field in the RefundLineItem object. Use RefundLineItem.restockType instead.

We've added new fields, mutations, arguments, and types to extend and enhance what you can do with discounts. You can now use the GraphQL Admin API to do the following:

  • Retrieve usage counts for automatic discounts
  • Perform new ways of searching through discounts
  • Speed up the management of discounts with bulk mutations

To learn how to manage discounts using the GraphQL Admin API, refer to the Create and manage discounts with the Admin API tutorial.

New fields

  • discountRedeemCodeSavedSearches field was added to type QueryRoot
  • asyncUsageCount field was added to type DiscountAutomaticBasic
  • asyncUsageCount field was added to type DiscountAutomaticBxgy
  • hasTimelineComment field was added to type DiscountCodeBasic
  • shareableUrls field was added to type DiscountCodeBasic
  • totalSales field was added to type DiscountCodeBasic
  • asyncUsageCount field was added to type DiscountRedeemCode
  • id field was added to type DiscountRedeemCode
  • targetItemImage field was added to type DiscountShareableUrl
  • targetType field was added to type DiscountShareableUrl
  • title field was added to type DiscountShareableUrl
  • url field was added to type DiscountShareableUrl
  • hasTimelineComment field was added to type DiscountCodeBxgy
  • shareableUrls field was added to type DiscountCodeBxgy
  • totalSales field was added to type DiscountCodeBxgy
  • hasTimelineComment field was added to type DiscountCodeFreeShipping
  • maximumShippingPrice field was added to type DiscountCodeFreeShipping
  • shareableUrls field was added to type DiscountCodeFreeShipping
  • totalSales field was added to type DiscountCodeFreeShipping

New mutations

  • discountCodeBulkActivate was added
  • discountCodeBulkDeactivate was added
  • discountCodeBulkDelete was added
  • discountCodeRedeemCodeBulkDelete was added

New arguments

  • after argument was added to field discountRedeemCodeSavedSearches in type QueryRoot
  • before argument was added to field discountRedeemCodeSavedSearches in type QueryRoot
  • first argument was added to field discountRedeemCodeSavedSearches in type QueryRoot
  • last argument was added to field discountRedeemCodeSavedSearches in type QueryRoot
  • query argument was added to field discountRedeemCodeSavedSearches in type QueryRoot
  • reverse argument was added to field discountRedeemCodeSavedSearches in type QueryRoot
  • sortKey argument was added to field discountRedeemCodeSavedSearches in type QueryRoot
  • ids argument was added to mutation discountCodeBulkActivate
  • savedSearchId argument was added to mutation discountCodeBulkActivate
  • search argument was added to mutation discountCodeBulkActivate
  • ids argument was added to mutation discountCodeBulkDeactivate
  • savedSearchId argument was added to mutation discountCodeBulkDeactivate
  • search argument was added to mutation discountCodeBulkDeactivate
  • ids argument was added to mutation discountCodeBulkDelete
  • savedSearchId argument was added to mutation discountCodeBulkDelete
  • search argument was added to mutation discountCodeBulkDelete
  • discountId argument was added to mutation discountCodeRedeemCodeBulkDelete
  • ids argument was added to mutation discountCodeRedeemCodeBulkDelete
  • savedSearchId argument was added to mutation discountCodeRedeemCodeBulkDelete
  • search argument was added to mutation discountCodeRedeemCodeBulkDelete
  • query argument was added to field codes in type DiscountCodeBasic
  • savedSearchId argument was added to field codes in type DiscountCodeBasic
  • sortKey argument was added to field codes in type DiscountCodeBasic
  • query argument was added to field codes in type DiscountCodeBxgy
  • savedSearchId argument was added to field codes in type DiscountCodeBxgy
  • sortKey argument was added to field codes in type DiscountCodeBxgy
  • query argument was added to field codes in type DiscountCodeFreeShipping
  • savedSearchId argument was added to field codes in type DiscountCodeFreeShipping
  • sortKey argument was added to field codes in type DiscountCodeFreeShipping

New and updated types

  • DiscountShareableUrl type was added
  • DiscountCodeBulkActivatePayload type was added
  • DiscountCodeBulkDeactivatePayload type was added
  • DiscountShareableUrlTargetType type was added
  • DiscountCodeBulkDeletePayload type was added
  • DiscountCodeRedeemCodeBulkDeletePayload type was added
  • DISCOUNT_CODE was added to enum ResourceType
  • DISCOUNT_REDEEM_CODE was added to enum SearchResultType
  • COLLECTION was added to enum DiscountShareableUrlTargetType
  • HOME was added to enum DiscountShareableUrlTargetType
  • PRODUCT was added to enum DiscountShareableUrlTargetType
  • INCLUSION was added to enum DiscountErrorCode
  • job field was added to type DiscountCodeBulkActivatePayload
  • userErrors field was added to type DiscountCodeBulkActivatePayload
  • job field was added to type DiscountCodeBulkDeactivatePayload
  • userErrors field was added to type DiscountCodeBulkDeactivatePayload
  • job field was added to type DiscountCodeBulkDeletePayload
  • userErrors field was added to type DiscountCodeBulkDeletePayload
  • job field was added to type DiscountCodeRedeemCodeBulkDeletePayload
  • userErrors field was added to type DiscountCodeRedeemCodeBulkDeletePayload
  • maximumShippingPrice field was added to type DiscountCodeFreeShippingInput

We added new fields to the Order object that capture the current representation of order values. Previously, apps could only use fields such as totalPriceSet and totalTaxSet and had to manually subtract order values from returns and refunds.

New fields

  • currentCartDiscountAmountSet was added to object Order
  • currentSubtotalLineItemsQuantity was added to object Order
  • currentSubtotalPriceSet was added to object Order
  • currentTaxLines was added to object Order
  • currentTotalDiscountsSet was added to object Order
  • currentTotalPriceSet was added to object Order
  • currentTotalTaxSet was added to object Order
  • currentTotalWeight was added to object Order

Apps can now edit orders they created. Previously, apps could only edit orders created through a Shopify channel (for example, POS, online store, or draft orders).

To determine if your app can edit an order on Shopify, you can query the merchantEditable field on the Order object. If the return value of this field is true, your app can edit the order.

We also added a new merchantEditableErrors field to the Order object. If your app can't edit an order, then you can use this field to determine the reason why.

You can now query the order that is associated to a refund.

New field

  • order field was added to object Refund

You can now query a list of line items that contain shipping costs on existing orders.

New connection

  • shippingLines was added to object Order

You can now add discounts while editing orders. The following are use cases for adding discounts during order editing:

  • Build out post-purchase discount workflows to entice buyers into adding upgrades, complementary products, or subscriptions to their existing orders.
  • Offer items for free to first-time buyers.
  • Discount items after purchase if a buyer forgets to use their discount code at checkout.

To learn how to use the GraphQL Admin API to add discounts during order editing, refer to our Edit an existing order with Admin API guide.

New mutations

  • OrderEditAddLineItemDiscount was added
  • OrderEditRemoveLineItemDiscount was added

Updated mutation

  • allowDuplicates argument was added to OrderEditAddVariant

New types

  • OrderEditRemoveLineItemDiscountPayload was added
  • CalculatedDiscountApplication object was added
  • CalculatedDiscountAllocation object was added
  • OrderStagedChangeAddLineItemDiscount object was added
  • OrderEditDiscountInput input object was added
  • DiscountApplicationLevel enum was added

New field

  • CalculatedDiscountAllocation field was added to object type CalculatedLineItem

New connection

  • CalculatedDiscountApplication was added to object type CalculatedOrder

You can now query the delivery method on fulfillment orders. A fulfillment order delivery method can help you figure out how the line items represented by the fulfillment order should be delivered, or if they need to be picked up in-store.

New and updated types

  • DeliveryMethod type was added
  • DeliveryMethodType type was added
  • deliveryMethod field was added to type FulfillmentOrder
  • id field was added to type DeliveryMethod
  • methodType field was added to type DeliveryMethod
  • LOCAL enum value was added to type DeliveryMethodType
  • NONE enum value was added to type DeliveryMethodType
  • PICK_UP enum value was added to type DeliveryMethodType
  • RETAIL enum value was added to type DeliveryMethodType
  • SHIPPING enum value was added to type DeliveryMethodType

Use the GraphQL Admin API to identify, filter, and manage products based on their current product status.

Each product can have one of the following statuses:

  • draft: The product isn't ready to sell and is unavailable to customers on sales channels and apps.
  • active: The product is ready to sell and can be made available to customers on the online store, sales channels, and apps. By default, existing products are set to active.
  • archived: The product is no longer being sold and isn't available to customers on sales channels and apps.

To learn how to use product statuses, refer to the Use statuses to identify, filter, and manage products tutorial.

New and updated mutations

  • ProductChangeStatus mutation was added
  • newStatus argument was added to mutation ProductDuplicate

New fields

  • status field was added to object Product
  • status field was added to input object ProductInput

New and updated types

  • ResourcePublicationV2 object was added
  • ProductStatus enum was added
  • ResourcePublicationsV2 connection was added to type Publishable

You can now use the GraphQL Admin API to add a media image to a product variant. To learn how to add a media image to a product variant, refer to our Manage variant media with the GraphQL Admin API tutorial.

New and updated mutations

  • ProductVariantAppendMediaInput input object was added
  • ProductVariantDetachMediaInput input object was added
  • mediaSrc input field was added to ProductVariantInput

New and updated types

  • ProductVariantAppendMediaInput input object was added
  • ProductVariantDetachMediaInput input object was added
  • mediaSrc input field was added to ProductVariantInput
  • media connection was added to object type ProductVariant

New error codes

  • BLANK was added to enum MediaUserError
  • MEDIA_DOES_NOT_EXIST_ON_PRODUCT was added to enum MediaUserError
  • TOO_MANY_MEDIA_PER_INPUT_PAIR was added to enum MediaUserError
  • MAXIMUM_VARIANT_MEDIA_PAIRS_EXCEEDED was added to enum MediaUserError
  • INVALID_MEDIA_TYPE was added to enum MediaUserError
  • PRODUCT_VARIANT_SPECIFIED_MULTIPLE_TIMES was added to enum MediaUserError
  • PRODUCT_VARIANT_DOES_NOT_EXIST_ON_PRODUCT was added to enum MediaUserError
  • NON_READY_MEDIA was added to enum MediaUserError
  • PRODUCT_VARIANT_ALREADY_HAS_MEDIA was added to enum MediaUserError
  • MEDIA_IS_NOT_ATTACHED_TO_VARIANT was added to enum MediaUserError

Use the GraphQL Admin API to update the text content of legal policies associated with a shop. Policies are specified by policy type.

New mutation

  • ShopPolicyUpdate was added

New types

  • ShopPolicy object type was added
  • ShopPolicyInput input object was added
  • ShopPolicyType enum was added
  • ShopPolicyUserError was added

New field

  • shopPolicies was added to object shop

Use the GraphQL Admin API to query the price range of a product (the lowest and highest priced variants).

New and updated types

  • ProductPriceRangeV2 type was added
  • priceRangeV2 field was added to type Product

Use the GraphQL Admin API to query if a shop is eligible to enable international domains.

New field

  • internationalDomains was added to type ShopFeatures

Use the GraphQL Admin API to create a new marketing activity.

New mutation

  • marketingActivityCreate was added

We've added new error codes to better represent the different types of errors that can occur when creating media objects. We also added a new field to the MediaImage object.

New error codes

  • VIDEO_METADATA_READING_ERROR was added to enum MediaErrorCode
  • VIDEO_INVALID_FILETYPE_ERROR was added to enum MediaErrorCode
  • VIDEO_MIN_WIDTH_ERROR was added to enum MediaErrorCode
  • VIDEO_MAX_WIDTH_ERROR was added to enum MediaErrorCode
  • VIDEO_MIN_HEIGHT_ERROR was added to enum MediaErrorCode
  • VIDEO_MAX_HEIGHT_ERROR was added to enum MediaErrorCode
  • VIDEO_MIN_DURATION_ERROR was added to enum MediaErrorCode
  • VIDEO_MAX_DURATION_ERROR was added to enum MediaErrorCode
  • MODEL3D_THUMBNAIL_GENERATION_ERROR was added to enum MediaErrorCode
  • MODEL3D_GLB_TO_USDZ_CONVERSION_ERROR1 was added to enum MediaErrorCode
  • MODEL3D_GLB_OUTPUT_CREATION_ERROR was added to enum MediaErrorCode
  • UNSUPPORTED_IMAGE_FILE_TYPE was added to enum MediaErrorCode
  • INVALID_IMAGE_FILE_SIZE was added to enum MediaErrorCode

New field

mimeType was added to object MediaImage

You can now use the GraphQL Admin API to query a customer's activity on a shop's online store.

New type

  • CustomerJourneySummary was added

You can now subscribe to delivery profiles event webhooks.

New topics

  • PROFILES_CREATE value was added to enum WebhookSubscriptionTopic
  • PROFILES_UPDATE value was added to enum WebhookSubscriptionTopic
  • PROFILES_DELETE value was added to enum WebhookSubscriptionTopic

GraphQL Storefront API changes

Below are all the changes currently introduced in the 2020-10 version of the GraphQL Storefront API.

You can now query a shop's shipping policy using the shippingPolicy field.

New field

  • shippingPolicy was added to object Shop

REST Admin API changes

Below are all the changes currently introduced in the 2020-10 version of the REST Admin API.

You can no longer change tax field data using the Country or Province resources.

We've deprecated the include-risk-analysis header that includes order risks and risk analysis objects in the Order payload.

The existence of this deprecated header was not previously documented. The REST Admin API and GraphQL Admin API are not affected by this change.

If you request the header using an API version earlier than 2020-10, then the header will still be returned.

Use the Product resource to identify, filter, and manage products based on their current product status.

Each product can have one of the following statuses:

  • draft: The product isn't ready to sell and is unavailable to customers on sales channels and apps.
  • active: The product is ready to sell and can be made available to customers on the online store, sales channels, and apps. By default, existing products are set to active.
  • archived: The product is no longer being sold and isn't available to customers on sales channels and apps.

To learn how to use product statuses, refer to the Use statuses to identify, filter, and manage products tutorial.

New property

status property added to Product resource

New query parameter

status parameter added to Product resource

Use the Refund resource to add refund duties to your request body. This capability provides parity with the GraphQL Admin API.

The refund_duties object includes two fields: duty_id and refund_type. You can specify how you want the duty refunded by setting one of the following values on refund_type:

  • FULL: Refunds all the duties associated with a duty ID.
  • PROPORTIONAL: Refunds duties in proportion to the line item quantity that you want to refund.

We've added a new checksum property to the Asset resource.

The checksum property provides the MD5 representation of the content, which consists of a string of 32 hexadecimal digits. This property might be null if you haven't updated an asset recently.

We've added better reporting and feedback for batch discount code creation jobs. The new logs property specifies when no discount codes were created because the provided data was invalid.

New property

Use the PriceRule resource to specify the minimum purchase amount required to be entitled to a Buy X Get Y discount.

New properties

  • prerequisite_to_entitlement_purchase was added to PriceRule
  • prerequisite_amount was added to PriceRule

You can now subscribe to delivery profiles event webhooks.

New topics

  • profiles/create topic was added to webhook resource
  • profiles/update topic was added to webhook resource
  • profiles/delete topic was added to webhook resource