2022-10 release notes

What's new in 2022-10

The following features were added in version 2022-10 of Shopify's APIs.

Highlights from the GraphQL Admin API changes:

• Checkout Profiles API
• B2B API released
• Web Pixel API released
• New mutation to bulk activate or deactivate a single inventory item at multiple locations
• Support for custom content by market through the Translations API
• Location Management API released
• Full markets and multi-currency support for DraftOrders
• SellingPlan and SellingPlanGroup fields are now supported by the Translations API
• New references connection on Metafields
• Metafield support for Locations
• Duplicate and Create Inventory Reservations in DraftOrders
• Local Delivery & Pickup for Subscriptions

Highlights from the GraphQL Storefront API changes:

• You can now use the Storefront API to attach shipping address preferences to the carts of non-logged-in customers and the fetch cart delivery groups through the new deliveryAddressPreferences field, which has been added to the Storefront API's CartBuyerIdentity and CartBuyerIdentityInput objects
• New references connection on Metafields
• Querying for CheckoutProfiles
• New deliveryAddressPreferences field added to cart buyer identity objects

Highlights from the REST Admin API changes:

• New merchant_of_record_app_id field on the Order object
• New marketing_sms_consent_enabled_at_checkout field on the Shop object

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 Protected customer data requirementsProtected customer data requirements

As of version 2022-10, published, public apps that use GraphQL Admin API and REST Admin API resources must meet the protected customer data requirements.

The protected customer data requirements focus on data minimization, transparency, and security so that you can better support merchants' path towards compliance with privacy and data protection rules.

Anchor to Deleting a reference type metafield definitionDeleting a reference type metafield definition

As of version 2022-10, if you delete a reference type metafield definition with the deleteAllAssociatedMetafields argument set to false, then REFERENCE_TYPE_DELETION_ERROR is returned with the following error message:

Deleting a reference type metafield definition requires deletion of its associated metafields.

Anchor to Deprecated Fulfillment cancel endpoint on the REST Order APIDeprecated Fulfillment cancel endpoint on the REST Order API

The Fulfillment cancel endpoint on the REST Order API is now deprecated: /orders/{order_id}/fulfillments/{fulfillment_id}/cancel.json. Use /fulfillment/{fulfillment_id}/cancel.json on the Fulfillment endpoint instead.

Anchor to Deprecated ,[object Object], field on ,[object Object], resourceDeprecated title field on ProductVariant resource

You will no longer be able to register title translations on the ProductVariant resource. The title will be automatically generated using the option translations when they are registered.

Anchor to Deprecated customer-related ,[object Object], propertiesDeprecated customer-related Order properties

The following Customer object properties on the REST Admin API's Order resource have been deprecated:

• last_order_id
• last_order_name
• orders_count
• total_spent

These properties will still be available in the Customer resource.

Anchor to Deprecated Order and LineItem propertiesDeprecated Order and LineItem properties

We've introduced a breaking change to the LineItem resource. The fulfillment_service field is no longer supported in the REST and GraphQL Admin APIs. Fulfillment services will all be opted into SKU sharing in 2023-04. Consider using one of the following options instead:

• assigned_location property on the RESTFulfillmentOrder resource
• assigned_location field on the GraphQLFulfillmentOrder object

When a fulfillment service app sets permits_sku_sharing to true, some existing behaviour will break. When a product variant's fulfillmentService parameter (REST and GraphQL) is set to manual, it no longer means that the variant is stocked only at a merchant-managed location. Therefore, apps that use the fulfillmentService parameter in this way should instead use the location parameter on the FulfillmentOrder resource to determine which location or fulfillment service fulfills for a given line item.

The following other line item properties on the REST Admin API's Order resource are deprecated:

• origin_location
• destination_location

The following object property on the REST Admin API's Order resource is deprecated:

• total_price_usd

Anchor to Subscription billing cyclesSubscription billing cycles

We've added subscription billing cycles to the existing Subscriptions Contract APIs so that you can make changes to an upcoming order without affecting the base subscription contract.

The following changes are included:

• Skipping future orders
• Making changes to the line items of an upcoming order, including any additions, quantity changes, or removals
• Combining the orders of one or more subscriptions contracts to save on shipping costs

Anchor to Changes to MoneyV2 related fieldsChanges to MoneyV2 related fields

The Money scalar is being removed from the Storefront API. It was previously used for monetary fields that don't have a V2 suffix (<name>: Money). As a result, the following changes have been made:

• Non-V2 fields now use MoneyV2 objects for their type (<name>: MoneyV2).
• Monetary fields that do have the V2 suffix (<name>V2: MoneyV2) are deprecated in favor of the <name>: MoneyV2 equivalent. These fields will be removed in subsequent releases.

The Money V2 changes help to improve the consistency of the GraphQL Admin API and make it clearer to use these fields.

Anchor to GraphQL Admin API changesGraphQL Admin API changes

The following are all the changes currently introduced in the 2022-10 version of the GraphQL Admin API.

Anchor to Deleting a reference type metafield definitionDeleting a reference type metafield definition

Anchor to BreakingBreaking

As of the API version 2022-10, if you delete a reference type metafield definition with the deleteAllAssociatedMetafields argument set to false, then REFERENCE_TYPE_DELETION_ERROR is returned with the following error message:

Deleting a reference type metafield definition requires deletion of its associated metafields.

New error code

• REFERENCE_TYPE_DELETION_ERROR was added to MetafieldDefinitionDelete mutation

Anchor to Protected customer data requirementsProtected customer data requirements

Anchor to BreakingBreaking

As of version 2022-10, published, public apps that use the GraphQL Admin API must meet the protected customer data requirements.

The protected customer data requirements focus on data minimization, transparency, and security so that you can better support merchants' path towards compliance with privacy and data protection rules.

Anchor to Deprecated title field on ProductVariantDeprecated title field on ProductVariant

Anchor to BreakingBreaking

You will no longer be able to register title translations on the ProductVariant resource. The title will be automatically generated using the option translations when they are registered.

Learn more about TranslatableResourceTypes.

Anchor to Deprecated Order and LineItem propertiesDeprecated Order and LineItem properties

Anchor to BreakingBreaking

We've introduced a breaking change to the LineItem resource. The fulfillment_service field is no longer supported in the GraphQL Admin API. Fulfillment services will all be opted into SKU sharing in 2023-04. Consider using the assigned_location field on the GraphQLFulfillmentOrder object instead.

When a fulfillment service app sets permits_sku_sharing to true, some existing behaviour will break. When a product variant's fulfillmentService parameter (REST and GraphQL) is set to manual, it no longer means that the variant is stocked only at a merchant-managed location. Therefore, apps that use the fulfillmentService parameter in this way should instead use the location parameter on the FulfillmentOrder resource to determine which location or fulfillment service fulfills for a given line item.

Anchor to Subscription billing cyclesSubscription billing cycles

Anchor to BreakingBreaking

We've added subscription billing cycles to the existing Subscriptions Contract APIs so that you can make changes to an upcoming order without affecting the base subscription contract.

The following changes are included:

• Skipping future orders
• Making changes to the line items of an upcoming order, including any additions, quantity changes, or removals
• Combining the orders of one or more subscriptions contracts to save on shipping costs

Anchor to Disable transactional SMS ,[object Object]Disable transactional SMS

Due to carrier constraints, Shopify can no longer send customized SMS messages. This change risks a degraded experience for merchants using the feature. You can disable transactional SMS to mitigate a negative impact on the merchant experience. By disabling transactional SMS sent by Shopify, you can enable third parties to take over this job and provide customizable SMS.

New fields:

• transactionalSmsDisabled field was added to the Shop object

New webhook subscription topics:

• transactionalSmsDisabled field was added to the SHOP_UPDATE webhook subscription topic, which is now triggered when the transactionalSmsDisabled state of a shop changes

Anchor to Bulk activate or deactivate a single inventory itemBulk activate or deactivate a single inventory item

You can now use the new inventoryBulkToggleActivation mutation to bulk activate or deactivate a single inventory item at many locations, with a maximum of 250 locations at a time.

Anchor to Retrieve manually held fulfillment ordersRetrieve manually held fulfillment orders

You can now use the new manualHoldsFulfillmentOrders query to retrieve all of the manually held fulfillment orders for a shop. Fulfillment orders can also be filtered based on Order filters:

• order_risk_level - The fraud risk level of the order.
• order_financial_status - The financial status of the order
• shipping_address_coordinates_validated - Whether the shipping address was geolocated and it is a valid address.

Anchor to Merchant of RecordMerchant of Record

You can now access information on the application acting as the Merchant of Record on the Order object. This information is only populated for supported applications.

New fields:

• merchantOfRecordApp field has been added to the Order object.

Anchor to MarketWebPresence association is accessible through ShopLocale endpointsMarketWebPresence association is accessible through ShopLocale endpoints

As of 2022-10 you can now add, remove, and view the MarketWebPresence object that's associated with a Locale through the ShopLocale GraphQL object.

New fields:

• marketWebPresences field has been added to ShopLocale

Anchor to MetafieldsMetafields

You can now access a references connection on a metafield. Use this connection to resolve metafield values of a list reference type to their underlying resource. This new connection is paginated and works similarly to the existing reference field, which is used for single references.

Anchor to Unpublished locales can now be added to a MarketWebPresenceUnpublished locales can now be added to a MarketWebPresence

As of 2022-10 the marketWebPresenceUpdate endpoint now supports adding unpublished locales as alternateLocales.

Anchor to Support for custom content by marketSupport for custom content by market

You can now use the Translations API to surface custom content to buyers in a specific market, including custom content for a store's default language. This feature enables merchants to provide localized and custom content, such as:

• Support showing regional spelling or preferred terms. For example, a "Sweaters" menu title for a United States market, and a "Jumpers" menu title for a United Kingdom market.
• Display promotional content based on the buyer's market. For example, a custom Thanksgiving announcement bar in October for Canadian buyers.

New queries and mutations:

• translatableResource
• translationsRegister
• translationsRemove

Anchor to SellingPlan and SellingPlanGroup fields are now supported by the Translations APISellingPlan and SellingPlanGroup fields are now supported by the Translations API

The following SellingPlan and SellingPlanGroup fields are now supported by the Translations API:

• SellingPlanGroup.name - Public-Facing Name of the Selling Plan Group
• SellingPlan.description - Optional, more verbose description of the Selling Plan
• SeillingPlan.option1 - Delivery frequency
• SellingPlan.option2 - Delivery frequency (optional)
• SellingPlan.option3 - Delivery frequency (optional)

Anchor to New metafield definition types have been addedNew metafield definition types have been added

Two new metafield definition types have been added:

• collection_reference: A reference to a collection on the online store.
• list.collection_reference: A list of collection references on the online store.

Anchor to Duplicate and Create Inventory Reservations in DraftOrdersDuplicate and Create Inventory Reservations in DraftOrders

You now have the ability to do the following on DraftOrders:

• Duplicate drafts
• Creating drafts from orders
• Execute bulk operations such as add/remove tags and deleting drafts
• Create drafts with inventory reservations
• Access previously hidden fields, such as metafields, on drafts and line items

Anchor to Custom and Standardized Product Types have been deprecated in favor of Product Category and TypeCustom and Standardized Product Types have been deprecated in favor of Product Category and Type

On the Product object, the standardizedProductType field is deprecated in favor of productCategory and the customProductType field is deprecated in favor of productType.

New fields:

• The productCategory field has been added to the Product object.

Anchor to Full markets and multi-currency support for Draft OrdersFull markets and multi-currency support for Draft Orders

We have added full support for markets and multi-currency on DraftOrders. You will now be able to specify the market region that should apply to a DraftOrder, inheriting your configured market settings such as pricing. The selected market region's attributes will be available on their respective objects.

Additionally, we have built out full support for multi-currency in draft orders. You will now be able to query a new set of fields that expose all monetary values relevant to a draft order in multi-currency. As part of these changes, you will now be able to use all draft order payment completion flows in multi-currency.

Learn more about these fields in the DraftOrder, DraftOrderLineItem, DraftOrderAppliedDiscount, DraftOrderInput, CalculatedDraftOrder and CalculatedDraftOrderLineItem API reference.

Anchor to Create B2B DraftOrders via PurchasingEntityInputCreate B2B DraftOrders via PurchasingEntityInput

You can use the PurchasingEntityInput input object to create and update B2B DraftOrders. This input object attaches company, location, and contacts to the DraftOrder object. The input object can also be used to create and update a traditional direct-to-consumer (D2C) draft order, requiring only a customer ID.

Anchor to Metafield support for locationsMetafield support for locations

As of API version 2022-10, the Location object supports metafields. You can use metafields to store additional information, such as store hours, and then reference the information in Liquid.

Anchor to Local delivery and pickup for subscriptionsLocal delivery and pickup for subscriptions

You can now manage delivery methods of subscriptions contracts with shipping, local delivery, and pickup.

A new deliveryOptions field on the SubscriptionDraft object provides a SubscriptionDeliveryOptionResultSuccess type for all three delivery methods.

To edit or create contracts, localDelivery and pickup fields can be included in the extended SubscriptionDeliveryMethodInput input object, which can be used in the SubscriptionDraftInput.

Anchor to New mutations for marketing activitiesNew mutations for marketing activities

You can now use the marketingActivityCreateExternal and marketingActivityUpdateExternal mutations to create and manage marketing activities, without the need to implement a marketing activity app extension. These endpoints allow app developers to more easily link their marketing efforts, and accompanying tracking information to Shopify, so merchants can have a more complete picture of their marketing performance.

New mutations:

• marketingActivityCreateExternal mutation was added
• marketingActivityUpdateExternal mutation was added

Anchor to Subscription billing cyclesSubscription billing cycles

We have added subscription billing cycles to the existing SubscriptionsContract APIs so that you can make changes to an upcoming order without affecting the base subscription contract.

This includes the following changes:

• Skipping future orders:
• Making changes to the line items of an upcoming order, including any additions, quantity changes, or removals
• Combining the orders of one or more subscriptions contracts in order to save on shipping costs

Anchor to New mutations to manage locationsNew mutations to manage locations

We have added mutations that allow you to manage your locations using GraphQL. The mutations enable you to add, edit, deactivate, re-activate, and delete locations.

New mutations:

• locationActivate mutation was added
• locationAdd mutation was added
• locationDeactivate mutation was added
• locationEdit mutation was added
• locationDelete mutation was added

Anchor to B2B APIs are now availableB2B APIs are now available

We have added queries, objects, and mutations to introspect and manage B2B primitives, including companies, company, locations, and company contacts with associated roles.

For a full listing of queries and mutations, refer to the B2B section in the GraphQL Admin API reference.

Anchor to Web Pixel API is now availableWeb Pixel API is now available

You can use web pixel app extensions to connect your marketing and analytics pixels to a merchant's online store for collecting customer events. For more information, refer to the Web Pixel Extension API reference.

Anchor to GraphQL Storefront API changesGraphQL Storefront API changes

The following are all the changes currently introduced in the 2022-10 version of the GraphQL Storefront API.

Anchor to Changes to MoneyV2 related fieldsChanges to MoneyV2 related fields

Anchor to BreakingBreaking

The Money scalar is being removed from the Storefront API. It was previously used for monetary fields that do not have a V2 suffix (<name>: Money). As a result, the following changes are being made:

• Non-V2 fields now use MoneyV2 objects for their type (<name>: MoneyV2).

• Monetary fields that do have the V2 suffix (<name>V2: MoneyV2) are being deprecated in favor of the <name>: MoneyV2 equivalent. These fields will be removed in subsequent releases.

  The Money V2 changes help to improve the consistency of the GraphQL Admin API and make it clearer to use these fields.

Anchor to New field added to cart buyer identity objectsNew field added to cart buyer identity objects

You can now use the Storefront API to attach shipping address preferences to the carts of non-logged-in customers and the fetch cart delivery groups.

New fields:

• deliveryAddressPreferences field was added to the CartBuyerIdentity and CartBuyerIdentityInput objects.

Anchor to New references connection on metafieldsNew references connection on metafields

You can now access a references connection on a metafield. Use this connection to resolve metafield values of a list reference type to their underlying resource. This new connection is paginated and works similarly to the existing reference field, which is used for single references.

Anchor to New metafield definition types have been addedNew metafield definition types have been added

Two new metafield definition types have been added:

• collection_reference: A reference to a collection on the online store.
• list.collection_reference: A list of collection references on the online store.

Anchor to Access to a shop's brand settingsAccess to a shop's brand settings

You can now query a shop's brand settings and assets via the new Shop.brand field.

New fields:

• The brand field has been added to Shop.

Anchor to Querying for checkout profilesQuerying for checkout profiles

You can now query for a CheckoutProfile or multiple CheckoutProfiles, which provide insights about the profiles on a shop.

New queries:

• checkoutProfile query was added
• checkoutProfiles query was added

Anchor to New deliveryAddressPreferences field added to cart buyer identity objectsNew deliveryAddressPreferences field added to cart buyer identity objects

You can now use the Storefront API to attach shipping address preferences to the carts of non-logged-in customers and the fetch cart delivery groups. To attach shipping address preferences, the deliveryAddressPreferences field has been added to the Storefront API's CartBuyerIdentity and CartBuyerIdentityInput objects.

New fields:

• deliveryAddressPreferences field was added to CartBuyerIdentity object
• deliveryAddressPreferences field was added to CartBuyerIdentityInput input object

Anchor to REST Admin API changesREST Admin API changes

The following are all the changes currently introduced in the 2022-10 version of the REST Admin API.

Anchor to Protected customer data requirementsProtected customer data requirements

Anchor to BreakingBreaking

As of version 2022-10, published, public apps that use the REST Admin API must meet the protected customer data requirements.

The protected customer data requirements focus on data minimization, transparency, and security so that you can better support merchants' path towards compliance with privacy and data protection rules.

Anchor to The Fulfillment cancel endpoint on the Order API has been deprecatedThe Fulfillment cancel endpoint on the Order API has been deprecated

Anchor to BreakingBreaking

The Fulfillment cancel endpoint on the REST Order API is now deprecated: /orders/{order_id}/fulfillments/{fulfillment_id}/cancel.json. Use /fulfillment/{fulfillment_id}/cancel.json on the Fulfillment endpoint instead.

Anchor to Deprecated customer-related Order propertiesDeprecated customer-related Order properties

Anchor to BreakingBreaking

The following Customer object properties on the REST Admin API's Order resource have been deprecated:

• last_order_id
• last_order_name
• orders_count
• total_spent

These properties will still be available in the Customer resource.

Anchor to Deprecated Order and LineItem propertiesDeprecated Order and LineItem properties

Anchor to BreakingBreaking

We introduced a breaking change to the LineItem resource. The fulfillment_service property is no longer supported in the REST Admin API. Fulfillment services will all be opted into SKU sharing in 2023-04. Consider using the assigned_location property on the FulfillmentOrder instead.

When a fulfillment service app sets permits_sku_sharing to true, some existing behaviour will break. When a product variant's fulfillmentService parameter is set to manual, it no longer means that the variant is stocked only at a merchant-managed location. Therefore, apps that use the fulfillmentService parameter in this way should instead use the location parameter on the FulfillmentOrder resource to determine which location or fulfillment service fulfills for a given line item.

The following other line item object properties on the Order resource are deprecated:

• origin_location
• destination_location

The following object property on the REST Admin API's Order resource is deprecated:

• total_price_usd

Anchor to Cursor-based pagination supported for retrieving locationsCursor-based pagination supported for retrieving locations

As of API version 2022-10, GET requests for a list of locations are paginated. By default, you can display up to 50 locations on each page.

For more information about REST endpoints that support cursor-based pagination, refer to Make paginated requests to the REST Admin API.

Anchor to Disable transactional SMSDisable transactional SMS

Due to carrier constraints, Shopify can no longer send customized SMS messages. This change risks a degraded experience for merchants using the feature. You can disable transactional SMS to mitigate a negative impact on the merchant experience. By disabling transactional SMS sent by Shopify, you can enable third parties to take over this job and provide customizable SMS.

New properties:

• transactional_sms_disabled property was added to the Shop object

New webhook subscription topics:

• transactional_sms_disabled property was added to the shop/update webhook topic, which is now triggered when the transactional_sms_disabled state of a shop changes.

Anchor to Order IDs for the Order Risk resourceOrder IDs for the Order Risk resource

As of API version 2022-10, you can't create or update order risks without specifying an order ID.

Previously, you could create order risks by specifying the order_id property as null. This enabled you to create order risks prior to creating the order and block checkout. However, this functionality isn't used by apps. As a result, the update to specify an order ID isn't a breaking change.

Anchor to New Merchant of Record application field on Order objectNew Merchant of Record application field on Order object

You can now access information on the application acting as the Merchant of Record on the Order object. This information is only populated for supported applications.

New fields:

• merchant_of_record_app_id field has been added to the Order object.

Anchor to New Marketing SMS Consent property on Shop objectNew Marketing SMS Consent property on Shop object

A new marketing_sms_consent_enabled_at_checkout property has been added to the Shop object. The property is also present on the shop/update webhook, which now triggers when the marketing_sms_consent_enabled_at_checkout state of a shop changes.

New property:

• marketing_sms_consent_enabled_at_checkout property was added to the Shop resource