2023-07 release notes

What's new in 2023-07

The following features were added in version 2023-07 of Shopify's APIs.

Highlights from the GraphQL Admin API changes:

• Additional fees as a sale line type
• New mutation for removing a CompanyContact from a Company
• Creation of the new Customer Merge API
• Transition of application credit creation to the Partner API
• New mutations fulfillmentOrderSplit and fulfillmentOrderMerge that enable splitting and merging fulfillment orders
• Sort orders by total item quantity
• Specify a custom filename when using the fileCreate mutation

Highlights from the GraphQL Storefront API changes:

• Search and predictive search are now available
• Local pickup inventory availability is now available

Highlights from the REST Admin API changes:

• Transition of application credit creation to the Partner API
• Discount class for applied_discounts and discount_allocations is now available on a line item for the Checkout resource
• The tax_exempt field is now available on the Order resource
• The ONLINE_STORE_POST_PURCHASE_CROSS_SELL fulfillment hold reason is now available

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 Deprecating creation of application credits through the Admin APIDeprecating creation of application credits through the Admin API

Creating app credits through the Admin API is now deprecated. This affects both the REST resource and the GraphQL mutation.

Moving forward, create app credits using the new appCreditCreate mutation in the Partner API. This change will now allow Partners to issue credits to stores that have uninstalled their app.

Learn more about awarding app credits.

Anchor to Breaking changes to the product_feeds webhook topicsBreaking changes to the product_feeds webhook topics

The following major changes have been introduced to the product_feeds webhook topics:

• Deprecation of the use of bulk in favour of full for the product_feeds/full_sync webhook topic. To continue receiving full sync notifications, use the productFullSync mutation instead of productBulkSync.
• The spelling of the occurred_at field in the metadata for product_feeds notifications has been corrected.

Anchor to Creation of region-specific subfolders on country-code top-level domains (ccTLDs)Creation of region-specific subfolders on country-code top-level domains (ccTLDs)

You can now create region-specific subfolders on ccTLDs such as shop.ca or shop.fr. This is a departure from the previous behaviour where subfolders could only be created on generic top-level domains (gTLDs).

Anchor to New error code added to inventory quantity mutationsNew error code added to inventory quantity mutations

The error code item_not_stocked_at_location has been added to the inventorySetOnHandQuantities, inventoryAdjustQuantities, and inventoryMoveQuantities mutations. This error code is returned when you attempt to change inventory quantities for an item that isn't stocked at the specified location.

Anchor to No automatic creation of a subfolder web presence for a single-country marketNo automatic creation of a subfolder web presence for a single-country market

As of API version 2023-07, a subfolder web presence for a single-country market is no longer automatically created.

To maintain the existing functionality, use the marketWebPresenceCreate mutation following the creation of a market. Passing the country code of the market region as the subfolderSuffix will create the corresponding web presence.

Anchor to Mandatory provision of the ,[object Object], field in the Payments Apps APIMandatory provision of the chargebackLiability field in the Payments Apps API

As of version 2023-07 of the Payments Apps API, the chargebackLiability field must be provided in the 3-D Secure PaymentSessionThreeDSecureAuthenticationData input object. This change allows merchants to better manage their orders.

Learn more about the Payments Apps API and 3-D Secure.

Anchor to Removal of the ,[object Object], field on order shipping linesRemoval of the delivery_category field on order shipping lines

As of API version 2023-07, we're deprecating the order shipping line delivery_category property. The property hasn't been in use since 2020-06-12 and will no longer be present.

Anchor to Translate filter settingsTranslate filter settings

As of API version 2023-07, we're introducing a new capability to translate filters.

When enabled, all filter labels will be eligible for translations through the Translations API as well as the Translate and Adapt app.

Anchor to Use of Flow action extensions to update marketing activity delivery statusUse of Flow action extensions to update marketing activity delivery status

We're deprecating the abandonmentEmailStateUpdate mutation. Instead, you can use the abandonmentUpdateActivitiesDeliveryStatuses to update the delivery status of marketing activities created using a Flow action extension.

Anchor to Use of ,[object Object], on ,[object Object], endpointUse of total_count on CustomerSegmentMemberConnection endpoint

You can now use total_count on the CustomerSegmentMemberConnection endpoint, which provides the total count of a specified customer segment. Additionally, the total_count field on SegmentStatistics object has been removed. The new total_count functionality makes it easier to know the count of members of a specified segment.

Anchor to GraphQL Admin API changesGraphQL Admin API changes

The following are all the changes introduced in the 2023-07 version of the GraphQL Admin API.

Anchor to New API to update marketing activity delivery statusNew API to update marketing activity delivery status

Anchor to BreakingBreaking

As of 2023-07, you can use the abandonmentUpdateActivitiesDeliveryStatuses to update the delivery status of marketing activities created via Flow action extension. We're deprecating the abandonmentEmailStateUpdate mutation since it's being replaced by the new API.

Anchor to New error codes added to ,[object Object], mutationNew error codes added to fileUpdate mutation

Anchor to BreakingBreaking

As of API version 2023-07, the new error codes FILENAME_ALREADY_EXISTS and INVALID_FILENAME have been added to the fileUpdate mutation. These error codes are returned when you attempt to update the filename (URL Handle) and the input either matches an existing filename (URL Handle) or it's invalid.

Anchor to New field ,[object Object], on the ,[object Object], objectNew field taxExempt on the Order object

As of GraphQL Admin API 2023-07, the taxExempt field has been added to the Order object. You can use this field to determine whether an order was exempt from taxes.

Orders can be exempt from taxes if the Charge taxes option was disabled during the creation of a draft order, or if the order was created for a customer with the Collect tax option disabled.

Anchor to Tax partners can now configure the state of a tax app configurationTax partners can now configure the state of a tax app configuration

We've added the taxAppConfigure mutation, which enables selected tax partners to configure the state of an existing integrated tax service. This extended control provides Partners with more flexibility and adaptability in managing tax services, ensuring a smoother, more efficient operation for their app.

Anchor to Additional fees as a sale line typeAdditional fees as a sale line type

As of API version 2023-07, sales records can now be of type AdditonalFeeSale, which represents a sale associated with an additional fee charge.

For more information on this new type implementation, refer to the sale interface.

Anchor to Subfolders can now exist on ccTLD domainsSubfolders can now exist on ccTLD domains

As of API version 2023-07, you can now create region-specific subfolders on country-code top-level domains (ccTLDs), such as shop.ca or shop.fr. Previously, subfolders could only be created on generic top-level domains (gTLDs).

Anchor to New mutation for removing a ,[object Object], from a CompanyNew mutation for removing a CompanyContact from a Company

As of API version 2023-07, you can use the companyContactRemoveFromCompany mutation to remove a company contact from a company, even if they have placed orders on behalf of the company.

Anchor to Webhooks for B2B Customers Flow primitivesWebhooks for B2B Customers Flow primitives

As of API version 2023-07, we're providing additional webhook notifications for changes to the major entities within the B2B Customers product. These hooks enable better integration with Flow. The following webhooks are provided:

• company_contact_roles/assign
• company_contact_roles/revoke

Learn more about the webhooks.

Anchor to [object Object], field is available behind beta flag on the ,[object Object], objectExchangeV2 field is available behind beta flag on the Order object

As of API version 2023-07, you can use the exchangeV2 field on the Order object to get a better exchange (an exchangeV2 object value). This helps ERP partners properly integrate optimal exchange values.

Learn more.

Anchor to Shop Promise details presented to buyer at checkoutShop Promise details presented to buyer at checkout

The DeliveryMethod object now has a brandedPromise field that can be used to determine if an order was branded with Shop Promise at checkout.

Additionally, the MailingAddress object now includes the timeZone field, which you can use with the DeliveryMethod's maxDeliveryDateTime field, to determine the date and time according to the time zone of the destination address.

Learn more about Shop Promise eligibility.

Anchor to Breaking changes to Product Feeds APIBreaking changes to Product Feeds API

Anchor to BreakingBreaking

As of API version 2023-07, we're introducing the following breaking changes to the product feeds webhook topics:

• Deprecated use of bulk in favour of full for the product_feeds/full_sync webhook topic
• Corrected spelling of occurred_at field in metadata for product_feeds notifications metadata

Partners who want to continue receiving full sync notifications should start using the productFullSync mutation instead of productBulkSync.

Anchor to Introducing the new Customer Merge APIIntroducing the new Customer Merge API

As of API version 2023-07, you can now use the Customer Merge API to combine two separate customer profiles with certain non-blocking criteria. You can use the new mutations and queries to do the following tasks:

• Preview a customer merge
• Merge two customers
• Follow the status of an ongoing merge

Additionally, you can check whether a customer can be merged with another customer using the new Customer.mergeable field. This field is also available on the CustomerSegmentMember.mergeable object.

Learn more about merging customer profiles.

Anchor to Adding metafield attributes to the ,[object Object], objectAdding metafield attributes to the CustomerSegmentMember object

As of API version 2023-07, the CustomerSegmentMember object now has the attributes and connections to access the metafields associated to the customer.

Anchor to Added ,[object Object], attribute to the ,[object Object], objectAdded acceptsMultipleValues attribute to the SegmentEventFilterParameter object

As of API version 2023-07, the SegmentEventFilterParameter object now has the attribute acceptsMultipleValues to denote if the parameter can handle multiple values. For example, the id parameter for the products_purchased function can accept multiple values, such as products_purchased(id: (2012162031638, 1012132033639) = false.

Learn more about segment query language.

Anchor to Function parameter values can be queriedFunction parameter values can be queried

As of API version 2023-07, you can use the new functionParameterQueryName argument on segmentValueSuggestions to query for function parameter value suggestions for customer segmentation.

For example, the products_purchased filter has the function parameter id: products_purchased(id: '2012162031638') = true. To retrieve a list of possible product IDs to use for the id function parameter, provide filterQueryName: 'products_purchased', functionParameterQueryName: 'id' as arguments to the segmentValueSuggestions query.

Anchor to Additional webhook subscription topics for customer tagsAdditional webhook subscription topics for customer tags

As of API version 2023-07, Shopify's providing additional webhook subscription topics for customer tags:

• CUSTOMER_TAGS_ADDED
• CUSTOMER_TAGS_REMOVED

Learn more about these webhooks.

Anchor to Transition of application credit creation to the Partner APITransition of application credit creation to the Partner API

Anchor to BreakingBreaking

As of API version 2023-07, we're deprecating creating app credits through the Admin API. Both the REST resource, and the GraphQL mutation include the capability to create app credits deprecated. Going forward, you should create app credits using the appCreditCreate mutation in the Partner API.

This change enables us to implement new features for creating app credits, such as allowing Partners to issue credits to stores that have uninstalled their app.

Anchor to Purchase order numbers added to ,[object Object], and ,[object Object], objectsPurchase order numbers added to Order and DraftOrder objects

As of API version 2023-07, we've added a new field called poNumber to the Order and DraftOrder objects.

The OrderInput and DraftOrderInput input objects now accept a poNumber. This sets the purchase order number during orderUpdate, draftOrderUpdate, and draftOrderCreate mutations.

Anchor to New field ,[object Object], on ,[object Object], objectNew field isMarketplace on ChannelDefinition object

As of API version 2023-07, you can use the new field isMarketplace on the ChannelDefinition object to check if a channel definition represents a marketplace, such as shops on Facebook, Instagram, or Buy on Google.

The new isMarketplace field indicates whether any object that references ChannelDefinition is related to a marketplace channel. For example, you can determine if an order was placed on a channel that's a marketplace or if the store has available channels that are marketplaces.

Anchor to New field ,[object Object], on ,[object Object], objectNew field type on TranslatableContent object

As of API version 2023-07, you can use the new field type on TranslatableContent to get the type of the translatable content.

The new type field gives more information about the underlying translatable content which enables you to conditionally render UI elements, such as input fields.

Learn more about the LocalizableContentType object.

Anchor to New ,[object Object], webhookNew tax_partners/update webhook

As of API version 2023-07, the tax_partners/update webhook is available.

The tax_partners/update webhook is called whenever a tax partner is added or updated. Partners can use this webhook to determine when a merchant has made changes to the partner's tax app.

Learn more about these webhooks.

Anchor to Translate filter settingsTranslate filter settings

Anchor to BreakingBreaking

As of API version 2023-07, we're introducing a new capability to translate filters.

When enabled, all filter labels will be eligible for translations through the Translations API as well as the Translate and Adapt app.

Anchor to [object Object], field added to ,[object Object]duplicateResolutionMode field added to fileCreate

As of API version 2023-07, you can use the new duplicateResolutionMode field on the fileCreate mutation to control how duplicate filenames are handled.

Anchor to [object Object], fulfillment hold reasonONLINE_STORE_POST_PURCHASE_CROSS_SELL fulfillment hold reason

As of API version 2023-07, you can determine whether fulfillment has been placed on hold for a post-purchase with the reason ONLINE_STORE_POST_PURCHASE_CROSS_SELL.

Anchor to Splitting and merging fulfillment ordersSplitting and merging fulfillment orders

As of API version 2023-07, you can split and merge fulfillment orders. You can split a single fulfillment order into multiple fulfillment orders by dividing the line items across multiple fulfillment orders. You can also merge fulfillment orders together into a single fulfillment order.

Learn more about the fulfillmentOrderSplit and fulfillmentOrderMerge mutations.

Anchor to Update bytes in-place using ,[object Object]Update bytes in-place using fileUpdate

As of API version 2023-07, you can use the fileUpdateInput input object to provide an originalSource, which is used to update the bytes of a file. Passing originalSource when updating is supported for media images and generic files.

Using this functionality makes it easy to do an in-place update of an existing file.

Anchor to Inventory statesInventory states

As of API version 2023-07, there are new mutations that enable you to alter the inventory quantities at a location. State quantities reserved and on_hand are adjustable through the API. In addition, there are queries to retrieve quantities for every state.

For more information, refer to Inventory management apps.

Anchor to New error code added to inventory quantity mutationsNew error code added to inventory quantity mutations

Anchor to BreakingBreaking

As of API version 2023-07, a new error code item_not_stocked_at_location has been added to the inventorySetOnHandQuantities, inventoryAdjustQuantities, and inventoryMoveQuantities mutations. This error code is returned when you attempt to change inventory quantities for an item that isn't stocked at the specified location.

Learn more about managing inventory quantities.

Anchor to [object Object], support for ,[object Object]metafieldsSet support for MediaImage

As of API version 2023-07, you can use the metafieldsSet mutation to set metafields on images using MediaImage GIDs.

Anchor to Deprecation of image-related fields in product and product variants mutationsDeprecation of image-related fields in product and product variants mutations

As of API version 2023-07, we're deprecating a set of fields used for associating images with products and variants:

• ProductInput: images field deprecation. Use the newly introduced media field instead.
• ProductVariantInput: imageId and imageSrc field deprecation. Use mediaId and mediaSrc instead.
• ProductVariantsBulkInput: imageSrc field deprecation. Use mediaSrc instead.

Anchor to [object Object], access setting for app-owned metafieldsPUBLIC_READ access setting for app-owned metafields

As of API version 2023-07, you can now apply a PUBLIC_READ access setting to your metafield definitions. If your metafield definition is PUBLIC_READ, this means the following:

• The merchant can read the metafields on the definition.
• All installed applications with proper access scopes can read the metafields on the definition.
• Only the owner of the definition can write metafields.

This new setting builds upon the PRIVATE, MERCHANT_READ, and MERCHANT_READ_WRITE access settings that were released in January 2023.

Learn more about access controls.

Anchor to Moving ,[object Object], field from ,[object Object], to ,[object Object]Moving total_count field from SegmentStatistics to CustomerSegmentMemberConnection

As of API version 2023-07, you can now use total_count on the CustomerSegmentMemberConnection endpoint, which provides the total count of a specified customer segment.

Additionally, the total_count field on SegmentStatistics object has been removed. The new total_count functionality makes it easier to know the count of members of a specified segment.

Anchor to Creating a single-country market will no longer automatically create a subfolder web presence for this marketCreating a single-country market will no longer automatically create a subfolder web presence for this market

As of API version 2023-07, we're no longer automatically creating a subfolder web presence for a single-country market. To maintain existing behaviour, you can follow up creating a market with the marketWebPresenceCreate mutation. Passing in the country code of the market region as the subfolderSuffix creates the corresponding web presence.

Anchor to Unknown sale typeUnknown sale type

As of API version 2023-07, we're introducing sales type UnknownSale with line type UNKNOWN that represents new types of sales that might be added in the future and don't exist on older versions.

This is a complimentary object type for the SalesLineType UNKNOWN and implements the Sale interface.

Anchor to Adding the ability to sort orders by total item quantityAdding the ability to sort orders by total item quantity

As of API version 2023-07, we've added TOTAL_ITEM_QUANTITY to OrderSortKeys so that you can sort orders by the total quantity of items.

Anchor to Manage quantity rules for B2B customersManage quantity rules for B2B customers

As of API version 2023-07, you can use the quantityRulesAdd and quantityRulesDelete mutations to manage product variant minimums, maximums, and increments for B2B customers. Use the quantityRules field on the ProductVariantContextualPricing object to view the quantity rules applied for the companyLocationId input.

Learn more about quantity rules.

Anchor to Sale attribution edits now can be subscribed using the ,[object Object], webhookSale attribution edits now can be subscribed using the orders/updated webhook

As of API version 2023-07, you can now subscribe to the orders/updated webhook to be notified of any sale attribution edits to an order. When a staff attribution edit is made on POS, the orders/updated webhook fires. The payload includes a new attributed_staffs field under line_items. This new field will reflect the new attributions on the order after the edit.

A user can edit the staff attributions on multiple line items at once on POS. In this case, the webhook payload could include multiple updated line items with different attributions applied to them.

Learn more about the orders/updated webhook.

Anchor to Specify a custom filename using ,[object Object]Specify a custom filename using fileCreate

As of API version 2023-07, you can now specify a custom filename when using the fileCreate mutation to create files that will appear in the Shopify admin.

Anchor to Update a filename using ,[object Object]Update a filename using fileUpdate

As of API version 2023-07, we've added a new field called filename to the fileUpdate mutation. This new field allows you to update the filename of both generic files and images.

Anchor to GraphQL Storefront API changesGraphQL Storefront API changes

Anchor to Search and predictive search are now availableSearch and predictive search are now available

As of API version 2023-07, you can now use search and predictiveSearch queries to enable natural language search on your custom storefronts.

The search query returns the most relevant search results among product, page and article resource types. Merchants can use the Shopify Search & Discovery app to change the default value of the resource types and customize search results.

The predictiveSearch query helps you implement a predictive search dropdown interface where suggested results are displayed immediately as buyers type into the search bar.

Learn more.

Anchor to Determining local pickup inventory availabilityDetermining local pickup inventory availability

As of API version 2023-07, you can now use the quantityAvailable field on the StoreAvailability object to determine the inventory available for a product variant at a particular local pickup location.

Anchor to GraphQL Payments Apps API changesGraphQL Payments Apps API changes

Anchor to New ,[object Object], field for onsite credit card payments apps with 3-D SecureNew chargebackLiability field for onsite credit card payments apps with 3-D Secure

Anchor to Action-requiredAction-required

As of API version 2023-07, you must provide the chargebackLiability field in the 3-D Secure PaymentSessionThreeDSecureAuthenticationData input object. Merchants will benefit from this information to better manage their orders.

Learn more about the Payments Apps API and 3-D Secure.

Anchor to REST Admin API changesREST Admin API changes

Anchor to Transition of application credit creation to the Partner APITransition of application credit creation to the Partner API

Anchor to BreakingBreaking

As of API version 2023-07, we're deprecating creating app credits through the Admin API. Both the REST resource and the GraphQL mutation include the capability to create app credits deprecated. Going forward, you should create app credits using the appCreditCreate mutation in the Partner API.

This change allows Shopify to implement new features for app credit creation, such as allowing Partners to issue credits to stores that have uninstalled their app.

Anchor to Removal of the ,[object Object], field on order shipping linesRemoval of the delivery_category field on order shipping lines

Anchor to BreakingBreaking

As of API version 2023-07, we're deprecating the order shipping line delivery_category property. The property hasn't been in use since 2020-06-12 and will no longer be present.

Anchor to Purchase order numbers added to ,[object Object], and ,[object Object], objectsPurchase order numbers added to Order and DraftOrder objects

As of API version 2023-07, we've added a new field called poNumber to the Order and DraftOrder resources.

Anchor to Discount class for ,[object Object], and ,[object Object], on a line item in the ,[object Object], resourceDiscount class for applied_discounts and discount_allocations on a line item in the Checkout resource

As of API version 2023-07, the Checkout resource includes the discount_class attribute in the line_items[n].applied_discounts and line_items[n].discount_allocations.

The discount_class identifies the type of discount applied to a line_item:

PRODUCT: Denotes a product class discount that applies to specific products only. ORDER: Denotes an order class discount that applies across all line items.

Anchor to New field tax_exempt on the ,[object Object], resourceNew field tax_exempt on the Order resource

As of API version 2023-07, we've added the tax_exempt field to the Order resource. You can use this field to determine whether an order was exempt from taxes.

Orders can be exempt from taxes if the Charge taxes option was disabled during the creation of a draft order, or if the order was created for a customer with the Collect tax option disabled.

Anchor to [object Object], fulfillment hold reasonONLINE_STORE_POST_PURCHASE_CROSS_SELL fulfillment hold reason

As of API version 2023-07, you can determine whether a fulfillment has been placed on hold for a post-purchase with the reason ONLINE_STORE_POST_PURCHASE_CROSS_SELL.

Learn more.

Anchor to Splitting and merging fulfillment ordersSplitting and merging fulfillment orders

As of API version 2023-07, you can split and merge fulfillment orders. You can split a single fulfillment order into multiple fulfillment orders by dividing the line items across multiple fulfillment orders. You can also merge fulfillment orders together into a single fulfillment order.

Learn more about the FulfillmentOrder resource.

Anchor to Sale attribution edits now can be subscribed using the ,[object Object], webhookSale attribution edits now can be subscribed using the orders/updated webhook

As of API version 2023-07, you can now subscribe to the orders/updated webhook to be notified of any sale attribution edits to an order. When a staff attribution edit is made on POS, the orders/updated webhook fires. The payload includes a new attributed_staffs field under line_items. This new field will reflect the new attributions on the order after the edit.

A user can edit the staff attributions on multiple line items at once on POS. In this case, the webhook payload could include multiple updated line items with different attributions applied to them.

Learn more about the orders/updated webhook.