2022-10 release notes

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

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.

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.

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.

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

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

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.

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.

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.

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

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.

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

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

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)

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.

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

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.

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.

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.

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.

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.

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

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

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

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.

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.

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.

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.

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.

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.

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.

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

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

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.

While the Fulfillment API has already been deprecated as of version 2022-07, the cancel endpoint was missed. This change rectifies that mistake.

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.

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

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.

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.

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.

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.

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