Developer changelog

The Order object now has fields representing additional fees as of API version 2023-04. Additional fees are extra costs associated with an international package that aren't duties or taxes.

The new fields on the GraphQL Order object are:

• additionalFees
• currentTotalAdditionalFeesSet
• originalTotalAdditionalFeesSet

The new fields on the REST Order resource are:

• currenttotaladditionalfeesset
• originaltotaladditionalfeesset

Learn more about these new fields in the GraphQL reference docs or REST reference docs.

We’re continuously improving our systems to effectively and efficiently identify and remove fake reviews to ensure a safe, fair, and useful ecosystem for both merchants and developers.

As part of these efforts, you may receive an email notifying you that a review for your app has been removed because it doesn’t comply with our policies.

Learn more about our policies for leaving a review in the Shopify App Store in the Shopify Help Center.

As of 2023-04, we're introducing the ability to access the Focal Point setting value for images using the Storefront API.

Focal Points can be set from the Admin API or from the shop admin when editing your image files.

Learn more about Focal Points on Shopify Help

As of 2023-04 we're introducing the ability to read presentation attributes for 3D models in the storefront api.

When a 3D model is customized via the no code 3D viewer configuration the properties associated with lighting, zoom, camera angle and background color are available in the Storefront API.

Learn more about this feature on Shopify Help

As of March 15, you can geotarget Shopify App Store advertising campaigns, giving greater control over how you market your apps and grow your business. Create effective and relevant regional campaigns with country-specific attribution, metrics, and even recommended bids.

Learn more about creating geotargeted ads on Shopify.dev.

As of March 15, the templates schema attribute is no longer supported in the apps.liquid section.

• The templates schema attribute cannot be specified in the apps.liquid section.
• The enabled_on/disabled_on schema attribute cannot contain templates attribute in the apps.liquid section.

As of the Admin API 2023-04 Release, we are providing webhook notifications for changes to the major entities within the B2B Customers product. The following webhooks are provided:

• companies/create
• companies/update
• companies/delete
• company_locations/create
• company_locations/update
• company_locations/delete
• company_contacts/create
• company_contacts/update
• company_contacts/delete

Learn more about these webhooks on Shopify.dev

As part of the GraphQL Storefront API 2023-04 API release, we are adding wallet_preferences to the Cart object. The wallet preferences from the cart will allow to pass through a buyer's wallet preference to the checkout.

Learn more about the Cart object on Shopify.dev.

The JavaScript support developer preview enables you to write functions in JavaScript or TypeScript, compile them to WebAssembly with Shopify CLI, deploy them to Shopify, and execute them on development stores.

Learn more about the developer preview on Shopify.dev.

In the Admin GraphQL API version 2023-04, appUsageRecordCreate now supports an optional parameter idempotencyKey which ensures the merchant will not be charged twice. When idempotencyKey is provided, the mutation will return the same response as any previous appUsageRecordCreate mutations with identical idempotencyKey for the intended shop and requesting app, rather than creating a new record and charging the merchant again.

This means that an idempotencyKey could be reused by an app to create appUsageRecords on different shops to charge the merchant. Different apps can also use the same idempotencyKey on the same shop and still charge the shop. But we recommend a UUID.

The appUsageRecordCreate will behave like past API versions when idempotencyKey is not provided and create a new record on every mutation.

As of 2023-04 we're introducing a new capability to translate metaobjects.

Similar to the publishable capability, the translatable capability can be enabled when creating and updating a metaobject definition. When enabled all metaobjects belonging to the definition will be eligible for translations through the Translations API as well as the Translate and Adapt app.

Learn more about the Translatable Capability on Shopify.dev

We've added headings as well as ordered lists to the rich text setting within online store editor. This means that themes can now take advantage of this new semantic styling within the editor to allow merchants to configure multiple headings of different semantic sizing and craft lists (now both ordered and unordered) right in the theme.

Learn more about the rich text input setting on Shopify.dev.

In the Admin GraphQL API version 2023-04, you can use the productVariantsBulkUpdate mutation to update valid variants even if some variants are invalid. The new allowPartialUpdates parameter is optional and defaults to false for backwards compatibility, but by enabling it, the mutation will modify valid variants, instead of not updating any variants due to invalid variants.

Learn more about the mutation here.

As of February 27, Shopify App Store’s search algorithm folds in more data on how merchants interact with results after they search.

In other words, apps that merchants find most relevant, given what they’re searching for, will rank higher overall. While term matching will still inform results, this update will reduce the impact of keyword stuffing.

Learn more about search on our blog.

You can now use the $app: metafield namespace prefix in Shopify Functions input queries to ensure your app's ownership of metafields used in your function.

We recommend use of reserved prefixes by default for all functions, so that you can control access to metafields used by your function. By default, they will be private to your app.

Learn more about metafield ownership and using metafields with input queries on Shopify.dev.

The CompanyAddress is no longer supporting the use of firstName/lastName fields, preferring instead to use a single recipient field. English-based UI elements may call this new field Attention. This is due to requests from merchants who are not dispatching orders to named individuals, but rather to locations, departments, or roles.

The field recipient has been added to the liquid API for CompanyAddress to display this field. However, there are a large number of existing templates that use the firstName/lastName fields. In order to minimize the impact on these templates, we populate the lastName field with the recipient, and leave the firstName field blank (specifically, it is null).

The previous paragraph is true for those CompanyAddresses where the recipient field has been populated. Where the address is still using firstName/lastName, the firstName/lastName fields will be populated as before, with the recipient field being the concatenation of these fields in a locale aware manner (in the same way as the name field). We are in the process of porting all CompanyAddresses to use the recipient field only.

Shopify will be making changes to the certificate used to secure subdomains of myshopify.com (eg: https://test.myshopify.com/) effective February 13, 2023. The current certificate which is being used is issued by Cloudflare via DigiCert. We will be adding in additional certificates signed by Lets Encrypt and Google Trust Services.

Note: This will not affect the certificate used for mTLS connections.

For more information refer to the community notice.

JavaScript support for Shopify Functions is now available in a local developer preview. This means you can try Shopify Functions with JavaScript locally, on your own development machine, but you can't deploy functions to production yet. We are releasing this preview now to get your feedback on our JavaScript development experience.

Learn more about JavaScript support for functions on Shopify.dev.

We are introducing Mock.Shop, a free prototyping tool to build a proof-of-concept storefront without having to set up a shop or run any server-side code. Use Mock Shop API to query live commerce data such as sample products, variants, and carts to help you quickly prototype commerce storefronts.

Mock.Shop is publicly available - no server, or access tokens required.

Visit Mock.Shop to learn more and build a proof-of-concept.

The Shopify Functions API for cart and checkout validations is now available in the Checkout Extensibility developer preview.

This API allows you to apply validation rules that run in both the cart and checkout, ensuring that purchases meet certain criteria before checking out, or completing the order.

Learn more about building cart and checkout validations in our dev docs: Cart and Checkout validations

We released new checkout branding API properties to make it possible to customize more of checkout’s look and feel. These consist of API-only capabilities that can style interactive elements like buttons and form inputs, as well as more typography controls on heading styles and font styles.

These customizations are automatically inherited by checkout UI extensions and include:

• Font properties for all font surfaces like case and kerning
• Form controls such as corner radius, border presence, label position and label typography
• Button styles such as padding, corner radius and button typography

For more information, view the checkout branding API reference.

The Order Routing Location Rule API is now available in a developer preview. You can use this new Shopify Functions API to write custom order routing rules that determine how to best fulfill and ship orders, based on the needs of the merchant.

For example, keeping orders within the country, balancing inventory levels to prioritize locations with more items in stock, or shipping directly from stores, just to name a few.

Learn more about the Order Routing Location Rule Function API here

The Shopify Functions APIs for delivery and payment customizations are now generally available. These Functions APIs allow you to hide, reorder, or rename delivery and payment options directly in the checkout.

One of the most popular delivery customizations include the ability to surface unique shipping options to specific buyers — like bike shipping options, that only display to customers that live within certain ZIP or postal codes.

With regards to payment customizations, one of the most popular use cases is to hide certain payment options based on a dollar threshold.

• Start building with the Delivery Customization API
• Start building with the Payment Customization API

The Cart Transform API is now available in a developer preview. You can use this new Shopify Functions API to create unique product bundle offerings that display directly in the checkout.

There are two key parts building a product bundle. First, you can determine which specific products can be merged into a bundle. Second, the Cart Transform API can also expand a bundle product into its individual components, making it easier to complete tasks on the backend—like calculating taxes, shipping weights, decrement inventory, and more.

Learn more about how to use the Cart Transform Function API to build product bundles here

Checkout UI extensions on the order status page are now available in the Checkout Extensibility developer preview. Add app-powered extensions or content to post-checkout pages such as surveys, social shares or referral links so merchants can install and configure apps without code. Learn more

New Checkout UI Extensions APIs

With this new API release, checkout UI extensions can access the storefront API without needing to be a sales channel. They can also read and edit discount codes and gift cards, and generate a signed token to be verified on an app server. Extensions can also verify that they are rendering in the checkout editor.

• Buyer journey and order hooks - Extensions can use the buyer journey API to render different extensions on the order status page based on the intended step in the customer journey (e.g. on checkout completion, or order fulfillment). For more details about extensions on the order status page, see here
• Storefront Direct Access API - Extensions can query the storefront API of a shop to get additional information like product tags, product recommendations, or currency conversions. Shopify handles authentication, so the extension only needs to pass in the query. This API is available to all apps and does not require the app to be a sales channel.
• Rendered in editor API - Extensions can now detect when they are being rendered inside the checkout editor. Extensions that only conditionally render to buyers should always use this to render content for merchants configuring the extension.
• Discount Code API - Extensions can now read discount allocations and discount codes in checkout, and add or remove the discount code(s).
• Gift Card API - Extensions can now read the gift card code applied to a checkout along with the amount. They can also add or remove gift card codes.
• Session Token API - Shopify provides a token signed with the app’s secret to the extension. This token can be passed via external call to an app server, and the app can trust that the contents of the token were created by Shopify

New UI Components

With the following new components, checkout UI extensions can progressively disclose information that buyers can opt in to. Using the overlay activation pattern on interactive components, extensions can show buyers information on customer trust like terms and conditions, trust badges, or warranties. Additional conditional styles offer more props to build performant UI.

• Pressable - Extensions can now use this generic interactive component without the styling that comes with a button or link.
• Component Overlays - Extensions have access to a set of accessible UI component overlays that provide additional information on interaction from Button, Link or Pressable components.
• Conditional style additions to Button, GridItem and Image
• Text has access to a visibility prop that allows visually-hidden content
• GridItem has added styling props on background, BlockSize and InlineSize

Shop Minis are a new way for Shopify App developers to bring their experiences into Shop and in front of 100 million buyers.

Our React Native SDK is designed to get you started with just one command, and it comes with all the components you’ll need, like search, product pages, and cart, to make an incredible shopping experience faster than ever before.

Learn more about early access.

As of the latest unstable GraphQL API version, you can use the Catalogs API to create a set of rules that determine the available products and their prices in different customer contexts. The Catalogs API lets you link Shopify Markets and B2B primitives to Publications and PriceLists to customize product offerings for different audiences. The same APIs also allow you to manage product publishing for sales channels.

To learn more about Catalogs API, read B2B Catalogs and Catalogs for Markets.

Shopify increased Admin API rate limits for Shopify Plus by 10x over standard limits. Apps installed on Shopify Plus stores will now get 500 points/second on the GraphQL Admin API and 20 requests/second on the REST Admin API. In addition, merchants on Commerce Components by Shopify now have unlimited API calls.

Read more about API rate limits.

Now, you can populate your store with test data in a single click, so you can start developing your app or theme faster.

The generated test data set includes the most common commerce primitives and configurations that you need to test an app, theme, or custom storefront, including some Shopify Plus exclusive features.

Read the developer documentation for more information and try it in your Partner Dashboard today.

EFFECTIVE FEBRUARY 06, 2023 ACTION REQUIRED

We've made changes to our Partner Program Agreement and API License and Terms of Use. These updates include terms that clarify a partner's responsibility to promptly take certain actions, including as necessary to resolve failed requirements and/or violations to our terms, as well as other important updates.

These changes come into effect as of today, February 06, 2023.

We encourage all developers on our platform to review and be familiar with the API License and Terms and the Partner Program Agreement, so that you understand how to build, run, and grow your app and development business on our platform.

For more information and frequently asked questions, please visit the Shopify Help Center.

As of version 2023-04 of the Admin REST API, requests for Transaction will now return total_unsettled_set. This represents the remaining amount to be captured on the transaction. total_unsettled_set is returned in both shop and presentment money objects with currency.

If you are leveraging manual capture and the authorized amount from Transaction, you should switch to referencing total_unsettled_set. The authorized amount can differ from the total amount to capture due to adjustments during order finalization such as tax adjustments.

As of January 23, 2023, a new resource type for query suggestions has been added to the Predictive Search API.

Notably, several other improvements have been made to the Predictive Search API:

• Resources[type] is now optional with a default set to queries, products, collections and pages
• Performance improvements when requesting multiple resource types
• New parameter: limit_scope to decide whether the limit parameter applies to the total number of returned results, or the total that each resource type returns.

Learn more about query suggestions on Shopify.dev.

We've added intelligent code completion features in Theme Check so that you can speedup writing Liquid code.

You can easily explore Liquid attributes as you type and benefit from type inferences, smart filters and scope awareness. With in-line documentation, you can check the most updated version of our documentation for objects, attributes, filters, and tags.

To start using, install Theme Check

Shopify Functions now support the use of variables in input queries, so that you can use merchant input for GraphQL field arguments.

Learn more about input query variables on Shopify.dev.

Empower your merchants to easily customize their online store with intuitive new color scheme settings. Online store color schemes are now available in developer preview.

You can define the structure of a color scheme in settings_schema.json and set values for each color scheme in settings_data.json. You can then reference the color schemes in the settings of a given section or block.

ColorSchemesDrop provides access to the colors schemes and color values in each scheme. You can define your CSS by iterating over the new drop. This way, merchants no longer need to edit their CSS or liquid file to add or remove color schemes.

Learn more about color scheme and color schemes settings.

In order to make the Cart SFAPI experience more seamless, we're rolling out changes to Cart Update mutations so they return a new, valid Cart even if the provided token is no longer valid. If a Cart is found for the provided token, the mutations will work the way they always have. That way you get back a a valid, updated Cart in your response, no matter what.

These mutations will return a new, empty cart:

• cartLinesRemove
• cartLinesUpdate
• cartSelectedDeliveryOptionsUpdate

The following mutations will update the new cart with the requested input:

• cartAttributesUpdate
• cartBuyerIdentityUpdate
• cartDiscountCodesUpdate
• cartLinesAdd
• cartNoteUpdate

To take advantage of this, use the new Cart ID from the returned Cart when you receive the FailedToRetrieveCart error code in your response. Please note that the new cart is not a copy of the cart whose token was invalid.

As of Admin Graphql API version 2023-04, you can now get inventoryItemId on the FulfillmentOrderLineItem resource.

From January 19th to January 20th, 2023, all private apps will be automatically converted to custom apps managed through the Shopify admin.

Custom apps support all the functionality that private apps did, and provide better security.

Learn more about the different types of app you can build.

You can now use the new enabled_on / disabled_on section schema attributes to specify where a section can be used. These new attributes replace the existing templates attribute and work for both templates and section groups.

• Use the enabled_on attribute to limit a section to specific templates and section groups.
• Use the disabled_on attribute to prevent a section from being used in specific templates and section groups.

Please keep in mind that you can use only one of enabled_on or disabled_on.

The Functions APIs for delivery customizations and payment customizations are now available in a developer preview.

With these new APIs, you can hide, reorder, or rename payment and delivery options to help merchants increase conversions and stand out from the competition.

Learn more about building with delivery and payment Functions in our dev docs: Delivery Customization Payment Customization

We've just released enhancements that allow merchants to approve or decline return requests in their admin for partners using the returnRequest mutation.

This changelog post announced new ways for managing returns via the GraphQL Admin API, including the ability to approve or decline a return automatically.

Partners can now choose to automate this behavior or allow merchants to take action themselves.

As of the 2023-04 version of the Admin GraphQL API, the publicationId and channelId fields of the PublicationInput will be validated on calls to publishableUnpublish and productUnpublish mutations.

This allows you to ensure that ids sent into a mutation correspond to existing records in the database.

The validation message for the publicationId field will change from "Channel can't be blank" to "Publication does not exist" on a PublicationInput object.

Learn more about publishableUnpublish and productUnpublish on Shopify.dev.

As of API version 2023-04, both FulfillmentOrder hold and move operations for both GraphQL and REST support a fulfillment_order_line_items parameter to allow you to place only a specified subset of the line items on hold, or move them to another location where they are in stock.

GraphQL

• FulfillmentOrderMove
• FulfillmentOrderHold

REST

• move
• hold

You can now query verifiedByShopifyTier on the MerchantApprovedSignals object to determine what tier of pre-approval a merchant is in if available.

This query helps you to accelerate the onboarding of merchants to sales channels based on the tiers.

For more information, refer to the release notes.

GraphQL Admin API 2023-04 introduces support for sorting orders by destination, based on the order's shipping address.

Orders will be sorted first by country, then zone (e.g. state or province), then city.

Returns apps can now use the stable version of the GraphQL Admin API to give merchants greater visibility into critical returns data across platforms, and help them manage orders more efficiently.

Returns apps can automate the return management process by taking actions on behalf of merchants. These actions can include the following:

• Creating and canceling returns
• Approving or declining return requests
• Managing reverse fulfillment orders and deliveries, including creating a reverse delivery with shipping information, and disposing or restocking items
• Issuing refunds
• Closing and reopening returns

We’ve also added new webhooks that your app can use to listen for events related to returns, refunds, reverse fulfillment orders, and reverse deliveries.

Learn more about returns management workflows on Shopify.dev.

As part of the 2023-01 GraphQL Admin API release, we've updated the metafieldsSet API to make the MetafieldsSetInput.type field nullable. When the metafield you are trying to mutate already has corresponding metafield definitions, you can simplify the mutation by omitting the type field from its arguments. The type field is still required when the metafield doesn't have a corresponding definition to the given ownerId, namespace and key.

For more information, refer to the metafieldsSet mutation.

You can now use the Storefront API to filter products by tags if tags are enabled as a filter setting on the shop.

The tag field has been added to the Storefront API's ProductFilter object, for this purpose.

With GraphQL Storefront API version 2023-01, you can use Metaobject queries to display custom content that's associated with resources like products, customers, and orders. Metaobjects created with the CONTENT category with an Active status are available through Metaobject queries.

This change is related to the GraphQL Admin API's support for content management and metaobjects.

As of 2023-01, Selling Plan Groups will have their limit on the number of associated Selling Plans increased from 20 to 31. We recommend paginating all queries on a Selling Plan Group's Selling Plans, rather than relying on this fixed limit.

To learn more about Selling Plan Groups, refer to the purchase options documentation.

You can now use the near parameter to search StoreAvailability by proximity, via Storefront API.

The type is GeoCoordinateInput, so far also used as parameter for Locations.

As of GraphQL Admin API version 2023-01, we are adding mutations productDuplicateAsync and productDeleteAsync. This will allow you to asynchronously duplicate and delete products that have a high number of variants that are stocked at several locations. This is because the mutations productDuplicate and productDelete may time out for these larger products.

Learn more about the mutations at productDuplicateAsync and productDeleteAsync.

As of 2023-01, you can use the EditedAt to see when checkout profile has been edited. Checkout profiles are sorted by EditedAt field instead of updatedAt.UpdatedAt field may be deprecated in the future.

As of the Admin API 2023-01 release candidate, fulfillment service and order management apps can subscribe to webhooks notifications related to fulfillment orders and events relating to them.

Learn more about fulfillment order webhooks at Shopify.dev.

As of the 2023-01 release of the admin GraphQL, you can access fulfillment orders from QueryRoot.fulfillmentOrders in addition to the pre-existing Shop.fulfillmentOrders connection.

This change will also include the deprecation of the Shop.fulfillmentOrders query in favour of the newly added QueryRoot.fulfillmentOrders

This change aligns with direction of the admin API moving forward ensuring that domain primitives are available on QueryRoot and the Shop field is reserved for key information related to the shop in the scope of the request.

You can learn more about fulfillment orders here

As of the 2023-01, you can use the fulfillmentOrdersReleaseHolds mutation to release holds on multiple fulfillment orders in a single request.

This will allow developers to reduce the number of individual requests used to complete bulk fulfillment actions with their apps.

For more details on the fulfillmentOrdersReleaseHolds mutation see here.

GraphQL Admin API 2023-01 introduces support for creation of shop resource feedback.

You can now use shopResourceFeedbackCreate mutation to create resource feedback on a shop to let merchant know what steps they need to take to make sure that your app is set up correctly.

For more information, refer to https://shopify.dev/api/admin-graphql/unstable/mutations/shopResourceFeedbackCreate.

As of the 2023-01 release candidate in the Admin API, you can use the GraphQL FulfillmentOrderLineItemsPreparedForPickup mutation to mark line items associated with a fulfillment order as being ready for pickup by a customer.

Learn more about FulfillmentOrderLineItemsPreparedForPickup mutation on Shopify.dev.

As of 2023-01 in GraphQL Admin API stable version, you can use shippingPackage as a required argument in shippingPackageUpdate mutation. shippingPackage is a set of attributes that describes a shipping package, including: weight, dimensions, name, default and type.

Learn more about shippingPackageUpdate.

As of the 2023-01 release candidate in the Admin API, new fields are available under the REST Transaction payment_details property, and the GraphQL OrderTransaction includes a new payment_details property.

New fields added to REST Transaction payment_details

• credit_card_name: The holder of the credit card.
• credit_card_wallet: The wallet type where this credit card was retrieved from.
• credit_card_expiration_month: The month in which the credit card expires.
• credit_card_expiration_year: The year in which the credit card expires.

Learn more about the REST Transaction resource on Shopify.dev.

New paymentDetails property added to GraphQL OrderTransaction

A new field, payment_details, is available under the GraphQL OrderTransaction resource. The type of this field is PaymentDetails, a new union type. Only one type is available at the moment, CardPaymentDetails, which defines the following properties:

• avsResultCode: The response code from the address verification system (AVS).
• bin: The issuer identification number (IIN), formerly known as bank identification number (BIN) of the customer's credit card.
• company: The name of the company that issued the customer's credit card.
• cvvResultCode: The response code from the credit card company indicating whether the customer entered the card security code, or card verification value, correctly.
• expirationMonth: The month in which the credit card expires.
• expirationYear: The year in which the credit card expires.
• name: The holder of the credit card.
• number:  The customer's credit card number, with most of the leading digits redacted.
• wallet: Digital wallet used for the payment.

Learn more about the GraphQL OrderTransaction resource on Shopify.dev.

As of API version 2023-01, the lineItem field on the FulfillmentOrderLineItem resource has been deprecated. The order line item associated with a FulfillmentOrderLineItem shouldn't be used to determine what to fulfill.

Use the FulfillmentOrderLineItem and FulfillmentOrder objects instead. An order LineItem represents a single line item on an order, but it doesn't represent what should be fulfilled.

As of GraphQL Admin API version 2023-01, metafields are being added to the Company and CompanyLocation primitives for B2B. Additionally, a subset of mutations are now available for use asynchronous usage via BulkOperation. Learn more about B2B on Shopify.dev.

As of the 2023-01 Admin API release, you can optionally supply the key argument to metafield queries on resources in the format of namespace.key to simplify your queries on the metafield field. You will also be able to optionally supply the keys argument to the metafields connection as a list of strings in the same format. The key returned will also be in the format of namespace.key.

As of 2023-01, Merchants with B2B enabled on their stores can import Orders in a B2B context using the REST API.

Learn more about B2B order imports on Shopify.dev.

As of GraphQL Admin API version 2023-01, we are removing the error code INVALID from LocationDeactivateUserError as we never return this error code when using the mutation locationDeactivate to deactivate a location. If you are explicitly checking for this error code, you should remove references to it.

Learn more about { Location deactivate user error codes } on Shopify.dev.

As of Admin API 2023-01, Shop Policy now supports the "Contact Information" policy. This policy is intended to allow users to add regulatory information like VAT and Trade number.

As of Admin API version 2023-01, you can use the shopifyqlQuery API to query analytical data from merchant stores to create reporting apps that provide business insights for merchants on the Plus plan.

We are removing the unstable sales dataset as a part of this stable channel release.

Learn more about ShopifyQL on Shopify.dev.

As of Admin API 2023-01, you can subscribe to the new PAYMENT_SCHEDULES_DUE webhook topic to be notified of when a PaymentSchedule.due_at date is reached.

Learn more about the PAYMENT_SCHEDULES_DUE topic on Shopify.dev.

As of 2023-01 in GraphQL Admin API stable version, we’ve introduced a few changes that will improve managing delivery settings for merchants with a high number of locations.

Delivery Profile mutation changes

We’ve added a new and more efficient way of managing locations associated with groups within a delivery profile. Instead of using the locations field (which always requires the full list of locations to have in a location group), you can now use the locationsToAdd and locationsToRemove fields to specify exactly the locations you want to adjust from a group.

Delivery Profile query changes

We’ve added a new argument locationGroupId to profileLocationGroups field. You can use this to query a specific location group and fetch its paginated locations more efficiently. We’ve added a new field unassignedLocationsPaginated. You can use this field to query locations that are not assigned to a delivery profile in a more efficient way.

We’ve added a new field locationsCount to the DeliveryLocationGroup object.

Local Pickup settings

Local Pickup API introduced in the 2022-10 release is now part of the stable version.

Documentation changes

In addition to the changes above, we’ve also updated documentation for DeliveryProfileInput and DeliveryProfileLocationGroupInput in which we raise awareness regarding performance considerations and input array limits. This also includes examples for the deliveryProfileCreate and deliveryProfileUpdate mutations, where we show how to manage profiles in a more efficient way, using changes introduced in this version.

As of 2023-01, you can tag fulfillment order holds with an external ID.

This can be used to track states within your own application on why a fulfillment order has been placed on hold and when it needs to be released. This can be done by utilizing the new FulfillmentOrderHoldInput.externalId field argument described here.

To learn more about the fulfillment order API see the fulfillment order object documentation

As of the 2023-01 Admin API release, you can optionally specify an access setting when you create or update metafield definitions via the API. This new setting will allow you to control who else can access the metafields under your definition via the Admin API.

Note that this setting can only be set when the definition is in your own reserved namespace.

Possible settings you can use are PRIVATE (no one else can access the metafields), MERCHANT_READ (the merchant has read-only access to the metafields via the admin UI), and MERCHANT_READ_WRITE (the merchant can view and edit the metafields via the admin UI).

Learn more about reserved namespaces.

Learn more about access controls.

As of 2023-01, the Shop.billingAddress field uses a new ShopAddress type instead of the customer-centric MailingAddress type.

Since Shop.billingAddress never returns non-null first or last names, these fields have been marked as deprecated on the new ShopAddress type. You should stop requesting those fields as they will be removed in a later version.

As of Admin API 2023-01, there are new mutations that allow 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.

Details about these new endpoints are in the Inventory management apps section of the developer docs.

As of GraphQL Admin API 2023-01, you can load the associated Order or DraftOrder object when querying for a PaymentTerms object.

Until now you could only go from Order or DraftOrder to PaymentTerms that relationship is now available in both directions.

Learn more about these new fields on Shopify.dev.

As of GraphQL Admin API 2023-01, you can load the associated PaymentTerms object when querying for a PaymentSchedule object.

Until now you could only go from PaymentTerms to PaymentSchedule, that relationship is now available in both directions.

Learn more about the new field on Shopify.dev.

As of GraphQL Admin API 2023-01, you can use the paymentReminderSend mutation to send payment reminder emails to customers.

Learn more about sending payment reminders on Shopify.dev.

As of 2023-01, we're introducing a new Admin API to allow you to create custom data structures called Metaobjects.

Similar to metafields, which enable custom fields to be associated with core resources in Shopify, Metaobjects provide a way to create and associate entirely new data models. The API enables you to do the following:

• Define objects with granular access control on how merchants and apps can interact with them.
• Create entries of custom defined objects and make them publishable to storefronts.

As of Shopify Functions API 2023-01, you can use the purchasing company as buyer identity in a B2B context to customize B2B checkout.

As of API version 2023-01, you can create fulfillment events using the GraphQL mutation fulfillmentEventCreate which was previously only accessible via the REST API.

As of GraphQL Admin API 2023-01, we are giving apps the capability for Apps to integrate into our Re-engagement marketing automation.

You will now be able to integrate Marketing Automation Flow Actions inside our Re-engagement marketing automation workflows. These are "Browse", "Cart", as well as "Checkout" abandonment automations. Here is the link for more detail about the re-engagement suite for marketing automations.

As of today, you can format your code instantly with our Liquid prettier plugin (1.0.0) for consistent code styles so you can avoid discussing styles and focus on what matters. Available both in-admin and locally in your favorite code editor.

Learn more about the Liquid Prettier Plugin on Shopify.dev.

You’ll now be able to trigger a webhook test payload to a specified destination directly from the CLI. Previously, developers needed to create a dev store and manually click around with an app installed in order to test their app logic. This manual process added significant time and friction to the development loop. With this new feature, it’ll be easy to test your subscriptions for each topic, so you can see what the payload will look like before your app is in production.

We’re also reducing the number of emails sent each time a webhook delivery fails. Previously, there was one email sent per attempt - which could quickly add up and become ineffective for monitoring. Now only one email will be sent for each one per consecutive string of failed attempts, over a two-day period, in order to keep your inbox clean and actionable.

To learn more about testing webhooks, check out the Shopify CLI command reference. If you have any questions about these changes, contact Partner Support with any questions.

The Voice and tone section of the App Design Guidelines has been shortened, with a new link to the complete Polaris documentation for voice and tone.

As of GraphQL Admin API version 2023-01, you can use webhooks with subscription billing cycles API.

We introduced subscription_billing_cycle_edits_create, subscription_billing_cycle_delete and subscription_billing_cycle_edits_update to WebhookSubscriptionTopic.

We also added some new error codes to SubscriptionBillingAttemptUserError and SubscriptionBillingCycleUserError.

Learn more about the Subscription Billing Cycles API on Shopify.dev.

The Localization API now supports online store media as a localizable resource. Metafield file references and "image" type theme sections can now be translated and localized to different markets using the translationsRegister mutation.

Note: media localization is currently only supported for theme sections & metafield file references. Product media localization is not yet supported.

Starting today, Shopify Functions are available to Shopify Plus brands who are not leveraging a checkout.liquid customization. This means that Plus merchants can start building their own product or order discount Functions and deploy them with a custom app.

Please note that the rollout to eligible Plus shops will take a couple of weeks to complete. Plus brands that leverage a checkout.liquid customization are not eligible to use Functions at this point in time.

Learn more about Shopify Functions here.

On December 6, we released new designs that make it easier for developers to showcase the value of their apps and for merchants to discover the right apps for their businesses, including:

• Optimized app listing
• Personalized home page
• Educational category pages
• New story pages

We will continue to build in public, with new features rolling out over the upcoming weeks.

Accelerated checkout buttons will now always appear in checkout even if customers have previously seen them in cart. This change will gradually roll out to eligible shops over the next two weeks.

To learn more, refer to accelerated checkout buttons.

This spring, we added app highlights to app store listings to help merchants find high quality apps and make better informed decisions. These highlights show tested indicators of merchant success, including its impact to storefront performance, how it works with other Shopify features, and integration with Admin.

Starting December 1, we’re providing visibility into how to achieve these highlights within the Distribution section of the Partner Dashboard. Initial data shows that app highlights are a major factor for merchant exploration and installation.

As of 2023-01, the authorV2 field is being removed from the Storefront API. It was previously used to reference nullable author scenarios. As a result, the following changes are being made:

• authorV2 will now be deprecated.
• author will be used instead, and will now be a nullable field.

These changes will help improve consistency of the API and avoid confusion when using these fields.

Merchants based in Kuwait can now add governorates to their shipping zones.

As a result, merchants in this region can give their customers the opportunity to provide more accurate address information at checkout as well as set up more specific shipping zones for the governorates that they add.

The 'Speed Tested' app highlight in the app store has been adjusted as of November 17th to better reflect your app's current performance, as well as impact on checkout experience.

We continue to measure how apps affect store performance using Google Lighthouse, but we now focus on your app's affect from recent installations, as opposed to all historical installations. This change gives merchants more accurate info about which apps perform quickly on their stores. As developers improve their app's performance, those improvements will be reflected more quickly in the app highlights.

For a shipping app to be eligible to receive the 'Speed Tested' app highlight, we will now consider its response time and error rate for shipping rate requests. Because there is some variability in performance between checkouts, we will only feature apps with a sufficient number of installs and requests in order to ensure a stable measurement.

You can now use Line Item Shopify Scripts with the Storefront API Cart to create discounts that are applied to a cart and reflected in the API response.

The App Design Guidelines have been updated to improve clarity on high quality app experiences.

In the app navigation section, it is now mandatory to use App Bridge’s Navigation Menu to integrate with the Shopify admin navigation experience if your app has different sections.

The existing requirement in the responsive grid section that apps must have responsive layouts for all device sizes has been moved to a callout card to make it more noticeable.

The wording of one callout card in the single-column layout section has been updated to make it clear that tables should only use the full width page if they have enough columns to require the extra space. Otherwise, they should use normal width pages.

Starting November 1, 2022, you can self-categorize your app once using the app submission form in the Partner Dashboard. Categories can be chosen by selecting up to two tags from our updated app categories that best describe the main function of your app. You can later appeal to change your app’s categorization if its capabilities change.

Learn more on Shopify.dev.

Shopify Functions are available for developers to start customizing the backend logic of discounts. All non Shopify Plus merchants are able to install your apps today. Shopify Functions are not yet available to Shopify Plus merchants. We will provide an update when Functions become generally available to Plus brands.

Discount the entire cart with order discounts applying a fixed amount of percentage off.

Discount specific products with product discounts applying a fixed amount or percentage off.

Learn more about Shopify Functions on Shopify.dev

Merchants can create selling plan specific shipping rates (for subscriptions) and have those names from those rates surface in checkout.

We've added new functionality to replace the default subscription rate names (ie. "subscription shipping", "subscription pickup", "subscription local") to now expose the merchant defined rate names during checkout, admin order and in the email notification. If merchants do not create selling plan specific shipping rates then the general rate name will be surfaced in checkout.

We've implemented an automatic GIF to animated WebP conversion process in our image processing pipeline, which improves performance by reducing delivered bytes by up to 50%.

For more information, please visit Shopify Help Center .

Support for themes has been added to Shopify CLI 3.20. In addition to migrating over theme commands, Shopify CLI 3.20 now includes the ability to integrate Shopify CLI into your CI/CD pipeline to perform actions like pushing, pulling and publishing a theme. Most theme commands on Shopify CLI 3.20 will continue to work the same with the exception of a few differences outlined here. More information on using Shopify CLI in a CI/CD pipeline can be found here.

We've added the video setting. You can use the video setting to surface videos uploaded to the Files Page in your theme.

As of 2023-01 a unique ID is sent by Shopify to payment providers when a customer pays at checkout. Use this ID to match order information between Shopify and your payment provider. An order can have more than one Payment ID. It only includes successful or pending payments. It does not include captures and refunds.

Steps: 1. From your Shopify admin, go to Orders. 2. Search using the custom term payment_id: and the payment ID value. For example payment_id:xxx. 3. Alternatively, you can search using the payment_id directly, without any explicit filters. 4. Click the order.

Requests made to Storefront API from SSL provisioned domains that are registered in the domains list on the Admin Panel will now return a two new headers:

Access-Control-Allow-Credentials: true Access-Control-Allow-Origin: ${origin_domain}

With that mechanism in place, Storefront API securely shares resources such as cookies with the browser, allowing for cart events originated from API Clients other than Online Store to be accounted for in the conversion metrics out of the box, as long as the origin request complies with CORS policy.

As of GraphQL Admin API version 2022-10, you can use Web Pixel Extensions to connect your marketing and analytics pixels to a merchant's online store for collecting customer events.

Learn more about Web Pixels on Shopify.dev.

Checkout extensibility capabilities are available for developers to start building apps for checkout customizations. We’re gradually rolling out checkout extensibility to Shopify Plus merchants so they can install and use your apps in production. Merchants will be able to discover apps with checkout UI extensions via the checkout editor.

Add new functionality with checkout UI extensions in various places in checkout and Shop Pay. Use these extensions to add in unique elements like product offers, custom fields, custom banners and more that are adaptable to various flows, creating a unified experience for buyers wherever they choose to checkout.

Track events using the new web pixel extension, to provide customer events that merchants can subscribe to. Apps will be able to hook into the events in the Pixels API, including checkout, to allow merchants access privacy-compliant customer behavior analytics.

Merchants are now able to use the new checkout branding API to customize the styling, to truly make checkout feel like their own, adapting the visual appearance such as the logo, font, and colors. Checkout UI extensions will inherit the brand settings from this API, so your app automatically reflects a brand’s style.

To learn more about building apps for checkout, please review our developer documentation.

As of GraphQL Admin API version 2022-10, you can query for a CheckoutProfile, or mulitple CheckoutProfiles, providing insights about existing checkout profiles on your shop.

Learn more about Checkout Profiles on Shopify.dev.

As of GraphQL Admin API version 2022-10 when you register any option translations on a ProductVariant resource, a title translation will be automatically generated using the option translations and surfaced for you.

You will no longer be able to register title translations on the ProductVariant resource.

Learn more about TranslatableResourceTypes.

The REST Admin API now disallows requests to either create or update order risks without specifying an order ID.

Previously, the REST Admin API allowed you to create OrderRisk models using order_id: null. This could have been used to create checkout order risks that exist prior to creating the order and block checkout. External apps do not use this feature.

This change is not breaking.

You can now access a references connection on a metafield in the GraphQL Admin and Storefront APIs.

Use the references 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.

This new endpoint is available in unstable, and will be part of the 2022-10 release.

For more information, refer to the Admin API and Storefront API documentation.

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.

ThedeliveryAddressPreferences field has been added to the Storefront API's CartBuyerIdentity and CartBuyerIdentityInput objects, for this purpose.

Refer to our documentation on cartCreate and cartBuyerIdentityUpdate to learn more about how to create a cart or update a cart's buyer identity to send delivery address preferences.

As of GraphQL Admin API version 2022-10, you can use the new manualHoldsFulfillmentOrders connection to fetch all the manually held fulfillment orders for a shop. Fulfillment orders can also be filtered based on order filters like - * 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.

As of Admin API version 2022-10, a new field transactional_sms_disabled has been added to the Shop object in the GraphQL and REST Admin APIs.

The field is also present on the "shop/update" webhook, which now will trigger when the transactional_sms_disabled state of a shop changes.

As of GraphQL Admin API and REST Admin API version 2022-10, information on application acting as the Merchant of Record for the order would be available through the Order object. This information would only be populated with supported applications.

New merchantOfRecordApp field in GraphQL Admin API returns OrderApp object and merchant_of_record_app_id field in REST Admin API returns the id of the application .

Learn more about the Order object on Shopify.dev.

As of 2022-10, Location resources support metafields. Use metafields APIs to store additional information in metafield values, like store hours, and then reference them in Liquid.

To learn more about metafields, refer to the metafields documentation. To use location metafields in Liquid, refer to the store_availability Liquid reference.

The Fulfillment API was deprecated in the Shopify 2022-07 release. However the cancel endpoint was missed and this change rectifies that mistake.

Apps will have until the 2023-04 release to migrate away from the deprecated API and use Fulfillment Orders instead. To help you seamlessly migrate, we’ve crafted a migration guide that walks you through the process of moving to Fulfillment Orders. To learn more, visit the migration guide on Shopify.dev.

We have added the selected_delivery_option as part of the CartDeliveryGroup as well as the handle field as part of the CartDeliveryOption in the cart.

The selected_delivery_option field represents the selected delivery option in a delivery group. The handle field represents a unique identifier for the delivery option.

A default CartDeliveryOption is saved as the selected_delivery_option in each CartDeliveryGroup available.

We also added the cartSelectedDeliveryOptionsUpdate mutation, allowing you to update the selected_delivery_options of each of your delivery groups.

As of GraphQL Admin API version 2022-10, you can now use marketingActivityCreateExternal and marketingActivityUpdateExternal mutations to create and manage marketing activities, without the need to implement a marketing activity app extension.

These endpoints will allow our app partners to more easily link their marketing efforts, and accompanying tracking information to Shopify so our merchants can have a more complete picture of their marketing performance.

As of GraphQL Admin API version 2022-10, we’ve added full support for markets and multi-currency on draft orders.

You will now be able to specify the market region that should apply to a draft order, 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 on DraftOrder, DraftOrderLineItem, DraftOrderAppliedDiscount, DraftOrderInput, CalculatedDraftOrder and CalculatedDraftOrderLineItem reference docs.

As of GraphQL Admin API version 2022-10, we are releasing a new mutation inventoryBulkToggleActivation.

This new mutation will allow you to bulk activate or deactivate a single inventory item at many locations, with a maximum of 250 locations at a time.

Instead of having to call inventoryActivate or inventoryDeactivate for each location, you can now do that in bulk for a single inventory item.

Learn more about the inventoryBulkToggleActivation mutation on Shopify.dev.

As of GraphQL Admin API version 2022-10, we've introduced 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.

This includes: * The ability to skip a future order. * The ability to make changes to the line items of an upcoming order, including any additions, quantity changes, or removals. * The ability to combine the orders of one or more subscriptions contracts in order to save on shipping costs.

Please note that with the introduction of Subscriptions Billing Cycles API, SubscriptionBillingAttemptCreate will create a billing attempt for the billing cycle at the origin_time if specified. Otherwise, it will be created for the current billing cycle by default.

Alternatively, you can also use BillingCycleSelector to select the billing cycle you wish to create billing attempt for.

Learn more about the API on Shopify.dev.

As of GraphQL Admin API version 2022-10, we are adding mutations so you can manage your locations using GraphQL. This will allow you to add, edit, deactivate, re-activate and delete locations.

Learn more about Locations on Shopify.dev.

As of GraphQL Admin API version 2022-10, we are adding queries, objects, and mutations to introspect and manage B2B primitives notably Companies, Company Locations, and Company Contacts with associated Roles. Learn more about B2B on Shopify.dev.

As of GraphQL Admin API version 2022-10, you can use the purchasing entity input field to create and update B2B draft orders.

This will attach company, location and contact to the draft order.

The field can also be used to create and update a traditional D2C draft order, requiring only a customer ID.

Learn more about PurchasingEntityInput.

As of GraphQL Admin API version 2022-10, you will get access to new fields and mutations for draft orders.

In particular, you will now be able to: - 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

Learn more about DraftOrderCreate.

As of the 2022-10 version of the Admin GraphQL API, you can use the contextualPricing field on Product and ProductVariant to fetch prices for a CompanyLocation by passing a companyLocationId argument to the context input.

Learn more about the Contextual Pricing API on Shopify.dev.

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

Learn more about ShopLocale and [MarketWebPresence].(https://shopify.dev/api/admin-graphql/2022-10/objects/MarketWebPresence).

As of 2022-10, partners can manage the delivery methods of the subscriptions contracts with Shipping, Local Delivery, and Pickup.

SubscriptionContract.deliveryMethod supports two new types: SubscriptionDeliveryMethodLocalDelivery and SubscriptionDeliveryMethodPickup.

A new SubscriptionDraft.deliveryOptions provides a SubscriptionDeliveryOptionResultSuccess type for all three delivery methods.

To edit or create contracts, an extended SubscriptionDeliveryMethodInput for SubscriptionDraftInput can receive localDelivery and pickup information.

Important to note:

• SubscriptionContract.deliveryMethod returns null for clients using API versions earlier than 2022-10 when the contract is created with Local Delivery or Pickup. If you have been inferring a subscription has only digital products because the delivery method is null, then adopt our new graphql changes.
• We also recommend taking a look at general delivery terms your app might be using, such as “delivers” or “ships”. Consider replacing them with broader terminology like “fulfills” or “recurs” that cover all modes of delivery.

Learn more about Delivery Methods for Subscription on Shopify.dev.

As of 2022-10 in GraphQL Admin API version unstable, you can use the new Local Pickup mutations to:

Enable Local Pickup for a location

Disable Local Pickup for a location

Additionally, you can access the current Local Pickup settings using the new Location.localPickupSettingsV2 field.

This enables you to fully manage Local Pickup settings for a location!

Learn more about Local Pickup on Shopify Help Center.

As of GraphQL API 2022-10, two new metafield definition types are available:

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

Learn more about the new reference types in Shopify.dev, and see examples.

As of Shopify CLI version 3.13.0, you can now preview theme app extensions by running the dev command. Shopify CLI supports hot reloading for theme app extensions, so you can avoid refreshing the browser after making changes.

Learn more about previewing theme app extensions.

We've added a new Rails association to Product and use it in the Product GraphQL, so that the database queries use an indexed access path, rather than doing a full table search as is being done now.

There's no change to the API.

The Product Recommendations API now supports an intent parameter that allows theme developers to specify whether they want to show related or complementary products.

Complementary products are a new type of product recommendation intended for items that are often bought together or pair well. Complementary products can be set with the Search & Discovery app.

Learn more about the product recommendation intents on Shopify.dev

As of September 19, 2022, you can use a new set of endpoints in the GraphQL Admin API 2022-10 version to surface custom content to buyers in a specific market that is not language based.

The newly introduced endpoints are marketLocalizableResource, marketLocalizableResources and marketLocalizableResourcesByIds queries, as well as marketLocalizationsRegister and marketLocalizationsRemove mutations.

An example of market localizable content that is not language based is the newly introduced money content type metafield

You can now use authenticated access to make Storefront API requests from a server (for example, from a Hydrogen server).

Using authenticated access enables more throughput for your server than using a public token, and enables Shopify's bot protection features to work more effectively.

App categories are getting simplified for better merchant discovery. Starting in November, you’ll be able to categorize your own app. For more information, click here

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

Learn more about marketWebPresenceUpdate.

As of ** 2023-01 ** version on the Admin GraphQL schema, you can use the DelegateAccessTokenDestroy mutation to delete the delegate tokens created by the API client.

For app architectures that use delegate tokens from multiple subsystems, this makes it easy to remove those delegate tokens that are unused or leaked for better application security.

As of the 2022-10 release of the Storefront API, you can now query a shop's brand settings and assets via the new Shop.brand field.

For more information on configuring your shop's brand settings, click here.

Icons added to your app using the Partner Dashvoard App setup page now must be 1200 px by 1200 px in size. This change makes icon sizes consistent across the Partner Dashboard, the Shopify App Store, and other development surfaces.

As of 2022-10, 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 will 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.

These changes will help improve consistency of the API and avoid confusion when using these fields.

Shopify now supports automatically optimizing storefront images using the AV1 Image File Format (AVIF) format, which improves performance by reducing delivered bytes. Optimization occurs on a per image basis, where Shopify will examine the request and determine the best compatible file format (e.g. AVIF, WebP or JPEG) based on image quality and compressed bytes.

You can learn more by visiting https://cdn.shopify.com/

Hey all! Coming back at you with improvements to creating an app from the Partner Dashboard! We’re removing the need for you to enter in any kind of URL when you’re manually creating an app from the UI. Instead, we’ll generate placeholders for you in the App setup area. You can update these URLs when you're ready to test or distribute your app.

We’ve also added a new Insights section to the app navigation, so you can discover everything from app history to API health without having to hunt around!

SellingPlanGroup and SellingPlan fields will be supported by the Translations API as translatable resources. The following fields will be available in the unstable API until the 2022-10 API release:

• 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)

More information about our translation API is available in our API documentation.

As of today, theme app extensions are be able to store translations up to 15 KB per locale file.

For more information about file and content size limits for theme app extensions, refer to the theme app extension framework documentation.

You may now see new error values and descriptions if you encounter a Braintree payment method being revoked when associating Braintree payment methods with the customers that you import into Shopify.

Learn more about migrating existing subscription contracts to Shopify.

As of the API version 2022-10, upon deleting a reference type metafield definition with delete_all_associated_metafields argument set to false, REFERENCE_TYPE_DELETION_ERROR will be returned with the following error message:

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

As of 2022-10 , the following new tax exemption values will be added to the TaxExemption enum and are intended to help with B2B transactions: * United States reseller exemptions, indicating that the merchant is exempt for taxes in a specific state as they are a reseller. * European Union reverse charge exemption, indicating that VAT should not be included on the buyers invoice and that the buyer will be responsible for reporting the correct VAT on their purchase.

Shopify’s GitHub app is requesting write permissions for GitHub Actions. This update will support improvements to the developer experience for Hydrogen custom storefronts hosted on Oxygen.

Today, deployments to the Oxygen hosting platform can only be triggered by committing and pushing a change to a Hydrogen code repository. These additional permissions will enable features such as on-demand re-deploys, automatic branch deployment when creating new Oxygen environments, and other enhancements.

Learn more about Shopify’s GitHub integration.

The customer ID for logged in customers is now included as a parameter in the forwarded query for app proxy requests. The customer ID is passed in the logged_in_customer_id parameter. The parameter will be blank if no customer is currently logged in.

Tip: Make sure that your application is verifying the signature parameter of forwarded queries.

In the 2022-04 API version release, the Product.contextualPricing and ProductVariant.contextualPricing fields can now return null.

This is in preparation for future argument changes. With the current arguments, there is no case where these fields can return null. However, future arguments will introduce null cases.

Learn more about contextualPricing

You can now read and write disputes and dispute evidence for Shopify Payments using the REST and GraphQL Admin APIs. The following new objects, mutations, and endpoints are available:

GraphQL Admin API

• ShopifyPaymentsDisputeEvidence object
• ShopifyPaymentsDisputeFileUploadUpdateInput input object
• ShopifyPaymentsDisputeEvidenceFileType enum
• ShopifyPaymentsDisputeFileUpload object
• ShopifyPaymentsDisputeEvidenceUpdate mutation

REST Admin API

• POST /admin/api/2022-07/shopify_payments/disputes/{{dispute_id}}/dispute_file_uploads.json
• DELETE /admin/api/{version}/shopify_payments/disputes/{{dispute_id}}/dispute_file_uploads/{{dispute_file_upload_id}}
• PUT /admin/api/{version}/shopify_payments/disputes/{{dispute_id}}/dispute_evidences.json

For more information, refer to the Dispute resource developer documentation.

Location resources now support metafields. Use metafields APIs to store additional information in metafield values, like store hours, and then reference them in Liquid. Note: this is currently supported in our unstable API version only.

To learn more about metafields, refer to the metafields documentation. To use location metafields in Liquid, refer to the store_availability Liquid reference.

As of GraphQL Storefront API version 2022-07, the Cart object has a new field: totalQuantity. This field returns an integer representing the total number of items in the cart.

Learn more about the Cart object on Shopify.dev.

As of GraphQL Storefront API version 2022-07, the CartLineEstimatedCost object has two new fields: amount and compareAtAmount. Both fields return an object of type MoneyV2. These new fields allow the price of a product variant on a cart to be queried using buyerIdentity as the context driver.

Learn more about these fields on Shopify.dev.

As of GraphQL Storefront API version 2022-07, a new urlRedirects object has been added.

URL redirects can be used to redirect traffic from one web page to another. The new urlRedirects object can be used to query the path and target URLs for URL redirects already set up on a shop.

Learn more about this object on Shopify.dev.

As of GraphQL Storefront API version 2022-07, the fulfillmentOrderRejectFulfillmentRequest mutation has two new optional arguments:

• reason: Identify the reason the fulfillment request was declined. It can be used to filter, group, and provide workflows to help merchants solve rejection issues.
• lineItems: Identify which line items in a fulfillment request are causing the rejection, and provide a detailed message for each one.

Also in this version, the FulfillmentOrderLineItem object has a new generic warnings field, which can be used to display rejection issues for the line item.

As of the 2022-07 version of the Admin GraphQL API, the phone field of the delivery address will be validated on calls to subscriptionContractCreate and subscriptionDraftUpdate.

This allows you to ensure phone numbers are properly formatted and will prevent errors that may occur when processing subscription payments with invalid data.

Learn more about SubscriptionContractCreate and subscriptionDraftUpdate on Shopify.dev.

You can now enable standard metafields on a shop using namespace and key with our GraphQL API.

Learn more about standard metafields.

Avoid sharing an access token across systems with the new delegateAccessTokenCreate mutation. This mutation creates new tokens with a subset of the total permissions of an app.

For app architectures that require authenticated access from multiple subsystems, it's best to avoid sharing the same token across all systems. Instead, create a new token that has access to only the minimal scopes that are required for proper functioning.

As of API version 2022-07, an input field for Braintree has been added to the CustomerPaymentMethodRemoteInput object, which is used by the customerPaymentMethodRemoteCreate mutation. This field can be used to help you migrate Braintree subscription contracts to Shopify.

Learn more about migrating existing subscription contracts to Shopify.

The fulfillment service SKU sharing feature gives fulfillment service apps the ability to stock and fulfill product variants together with merchant's locations.

Merchants will be able to stock and fulfill the same variant from multiple fulfillment services. This means that they can now have the same product/variant be stocked at their merchant managed locations as well as 3PL services at the same time.

This feature introduces the permits_sku_sharing parameter when creating or updating a fulfillment service. Setting permits_sku_sharing to true allows the merchant to assign fulfillment orders to both the merchant's locations and compatible fulfillment services.

When a fulfillment service app sets permits_sku_sharing to true, some of the following behaviour will break. If you set a product variant's fulfillmentService parameter (REST & GraphQL) to manual, then it no longer means that the variant is stocked only at a merchant-managed location. Apps that use the fulfillmentService parameter in this way should instead use the location parameter on the Fulfillment Order resource to determine which location or fulfillment service fulfills a given product variant.

Learn about multi-managed inventory from merchant's perspective.

Learn more about the building a fulfillment service using the fulfillment orders API.

Learn more about managing fulfillment orders using the REST Admin API and GraphQL Admin API.

As part of the GraphQL Storefront API 2022-07 API release, we are changing how discountAllocations on Cart and CartLine are returned.

• Cart.discountAllocations returns discount allocations that are applied to the entire Cart.

CartLine.discountAllocations now only returns discount allocations that are applied to the specific CartLine.

CartLine.total reflects the line total with only line-level discounts applied, not discounts applied to the entire Cart.

Learn more about the Cart object on Shopify.dev.

The relationship between a ProductVariant and a FulfillmentService was changed in the 2022-07 API version. A ProductVariant can be stocked by multiple fulfillment services. As a result, we recommended that you no longer use the following fields: ProductVariant.fulfillment_service (REST)(GraphQL) and LineItem.fulfillment_service (REST)(GraphQL). Instead, you should use inventory items and inventory levels if you need to find or manage where a product is stocked.

If you need to determine whether a product is a gift card, you should continue to use the ProductVariant.fulfillment_service field until an alternative is available.

Learn more about managing inventory quantities and states.

Learn more about managing fulfillment orders using the REST Admin API and GraphQL Admin API.

Learn more about the building a fulfillment service using the fulfillment orders API.

The following other line item object 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

These deprecated properties will be removed from unstable. The change will be made official in the 2022-10 REST Admin API version.

For other recent deprecations on the Orders resource refer to this Change Log

The relationship between a ProductVariant and a FulfillmentService was changed in the 2022-07 API version. A ProductVariant can be stocked by multiple fulfillment services. As a result, we recommended that you no longer use the following fields: ProductVariant.fulfillment_service (REST)(GraphQL) and LineItem.fulfillment_service (REST)(GraphQL). Instead, you should use inventory items and inventory levels if you need to find or manage where a product is stocked.

If you need to determine whether a product is a gift card, you should continue to use the ProductVariant.fulfillment_service field until an alternative is available.

Learn more about managing inventory quantities and states.

Learn more about managing fulfillment orders using the REST Admin API and GraphQL Admin API.

Learn more about the building a fulfillment service using the fulfillment orders API.

Also the field presentment_prices is being deprecated in REST and GraphQL. For more context refer to this change log.

This change adds the public GraphQL fields associated with fulfillment hold automations to the 2022-07 Admin API GraphQL release. Specifically, this adds the following field - MailingAddress.coordinatesValidated

This new boolean field can be used by partners to determine if the coordinates of a mailing address have been validated by Shopify. This unlocks ability to hold fulfillments on unvalidated mailing address and ensure that merchants check prior to requesting fulfillments from their 3PL.

Learn more about holding fulfillments with GraphQL and with REST Learn more about Shopify Flow

Some of the Fulfillment API endpoints and mutations on the Fulfillment API relating to managing fulfillments via an order ID were deprecated in the 2022-04 API release. They have now been removed and replaced by the Fulfillment Orders API in the 2022-07 API release.

This means that your app/integration using the deprecated Fulfillment API endpoints will have until the 2023-04 API release to migrate away from using the deprecated end points. You can continue to use API version 2022-04 until the 2023-04 release.

To help you seamlessly migrate, we've crafted a migration guide that walks you through the process of moving to Fulfillment Orders. To learn more, visit the migration guide on Shopify.dev.

Deprecated Endpoints on the Fulfillment API

https://shopify.dev/docs/api/release-notes/2022-07#fulfillment-endpoints-removed-from-the-rest-admin-api

As of API version 2022-07 all GraphQL schemas will start using the "@deprecated" directive for input fields and arguments which have been deprecated. API versions 2022-04 and below will continue to use the description for deprecation warnings.

It is recommended you use a GraphQL client which supports deprecated input fields and arguments when using GraphQL API versions 2022-07 and above. For example graphql-js added support as of version v15.5.0. See the official GraphQL spec for more details.

As of GraphQL Admin API version 2022-07, a new statistics field has been added to the Customer object for computed customer statistics. It includes a new field predictedSpendTier which indicates the predicted spend of a customer with a shop.

For more information, refer to the CustomerStatistics field in the GraphQL Admin API reference.

Starting with API version 2022-10, we’re introducing updated requirements for apps that use customer data. Updated requirements will be published prior to the release of API version 2022-10.

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

Learn more about how you can be ready for protected customer data.

With Checkout Extensibility, you can now build apps to customize checkout and Shop Pay. You can leverage Checkout UI extensions and Shopify Functions to surface new functionality, Checkout Branding API to customize styling, and Pixels to track events.

Checkout Extensibility is now available in developer preview.

Learn more about Checkout Extensibility on Shopify.dev.

As of GraphQL Admin API version 2022-07, you can use the Discount APIs to modify combination settings on a discount. This allows a customer to apply more than one discount to their order.

Discount combinations are available now as part of the Checkout extensibility developer preview.

Learn more about how discount combinations work.

Shopify Functions lets you extend or replace key parts of Shopify’s backend with custom logic. Functions run on Shopify infrastructure, making them both scalable and performant.

Functions are now available in developer preview for product, order, and shipping discounts.

Learn more about Shopify Functions on Shopify.dev.

With the latest App Bridge enhancements, your app will now look, feel, and perform like it’s a part of Shopify.

More specifically, App Bridge mobile apps can now load 85% faster from the Shopify iOS and Android apps when you enable mobile optimization for your embedded app. App Bridge apps can also now leverage full-screen mode, just like our first-party apps, for complex workflows in the Shopify admin. Lastly, apps that use the NavigationMenu component will now have their navigation embedded into the Shopify admin for faster, more natural access.

Learn more about App Bridge on Shopify.dev.

The updated Shopify CLI 3.0 is both easier to use and more powerful than ever. With Shopify CLI 3.0, we’ve simplified the development process by reducing the number of commands that you need to get started from 13 to 5.

You can also now leverage a single project for your app and extensions, preview your entire project with one command, and push your entire project together with a single command when you’re finished.

Learn more about Shopify CLI 3.0.

As of GraphQL Admin API version 2022-07, we have expanded the Selling Plan API enabling you to integrate support for new deferred purchase options like pre-orders and try before you buy into the Shopify Checkout.

As of GraphQL Admin API version 2022-07, we have introduced new APIs that enable you to collect deferred payment on an order using a vaulted card belonging to the customer. The orderCreateMandatePayment mutation will be available for charging payments against a vaulted credit card. This API returns a GraphApi::Job and paymentReferenceId. This paymentReferenceId can be used to poll the status of the payment using the orderPaymentStatus query.

What a relief - app distribution is now decoupled from the app creation flow in the Partner Dashboard! This means you no longer have to select a public or custom app type before you start coding.

We’ve also improved the navigation within the Partner Dashboard and added a Distribution page, where can manage your Shopify App Store listing or generate your merchant install link. Also, if you’re building your app using Shopify CLI, you’ll be able to copy and paste the commands you need to get started right from the dashboard.

Learn more about app distribution and selecting a distribution method.

As of GraphQL Admin API version 2022-07, the SellingPlanAnchorInput type has an additional optional field.

cutoff_day represents a fixed cutoff day for each anchor, to be used for monthly and weekly selling plans. Use this method if the cutoff should land on the same day each month.

You can also specify a cutoff using the cutoff field of the SellingPlanRecurringDeliveryPolicyInput type, which represents a duration. Using cutoff, the exact cutoff day could be different based on the number of days in the month.

As part of the GraphQL Storefront API 2022-07 API release, the following are changes to have been made to the Cart and CartLine object:

• New attribute field with a key argument
• estimatedCost is renamed to cost on Cart.
• estimatedCost is renamed to cost on CartLine.
• Add subtotalAmountEstimated, totalAmountEstimated, totalTaxAmountEstimated, totalDutyAmountEstimated to CartCost
• amount is renamed to amountPerQuantity on CartLineCost.
• compareAtAmount is renamed to compareAtAmountPerQuantity on CartLineCost.

Learn more about the Cart object on Shopify.dev.

As of GraphQL Admin API version 2022-07, app developers can now choose their preferred update behavior when upgrading or downgrading merchant application subscriptions.

By specifying the desired AppSubscriptionReplacementBehavior type, app developers can control whether the new subscription goes into effect immediately or is deferred to the end of the current subscription's billing cycle. By default, all app subscription changes will continue with the existing behavior.

Learn more about specifying app subscription replacement behavior on Shopify.dev.

When developing a theme using Shopify CLI, you can now preview your local changes using any theme in a store. To specify a theme, run the Shopify CLI theme serve command with the new -t or --theme flag:

shopify theme serve -t my-unpublished-theme

Previously, developers could only preview changes using development themes.

Caution: Before running shopify theme serve, pull your remote theme to ensure that any recent changes don't get overwritten by your local development files.

Learn more about previewing your theme using Shopify CLI.

As of May 9, 2022, you can use the GraphQL Admin API unstable version 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 the following kinds of localized and custom content:

• 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.

For more information, refer to examples in our developer documentation for the translationsRegister, translationsRemove, and translatableResource mutations.

A much wider range of optimized GIFs, including LZW compression, are now accepted for upload.

To learn more about which image formats Shopify accepts refer to: https://help.shopify.com/en/manual/online-store/images/theme-images#image-formats

Google Pay payments are now accepted for recurring transactions. For these transactions, the CustomerCreditCard will have a source of google_pay.

For more information, refer to Building subscription apps.

The TranslationsRemove endpoint now supports deleting translations that are stored in asset files.

Learn more about the TranslationsRemove endpoint.

Based on your feedback, we've updated the number of sections and blocks you can add within a template. You can now add up to 25 sections per template and 50 blocks per section within each template.

This will support use cases like: * Adding more blocks to an FAQ section * Adding multiple profile sections on the About Us page * Creating multiple areas of focus on the homepage * Section and block support for very large collections

You can specify a lower limit with the max_blocks attribute.

Learn more about section and block limits in our theme architecture documentation.

The visibility of an app block, or app embed block, of a theme app extension can now be controlled based on a custom condition.

The condition can be included in the block's schema with the available_if attribute, and the state of the condition is stored in an app-owned metafield. The metafield can be accessed through the Liquid app object.

To learn more about conditional app blocks, refer to Theme app extensions framework.

A new Liquid app object is available for use within the context of theme app extensions and app proxies. The app object can be used to access an app's metafields.

Refer to the app object documentation for more information.

As of GraphQL Storefront API version 2022-04, a new checkoutChargeAmount field has been added to Cart. It indicates the subtotal amount to be paid for this cart at checkout, not including any deferred payments. This field is currently restricted behind the extend_selling_plans_api beta flag.

The checkoutChargeAmount field is similar to the subtotal field. The subtotal field indicates the subtotal that will be paid altogether, including any payments that will be made at a later date. The checkoutChargeAmount is the actual price that will be paid at the time of checkout.

As of API version 2022-04, the DigitalWallet enum has a new value, FACEBOOK_PAY. This change affects both GraphQL Admin and Storefront APIs.

For more information, refer to the DigitalWallet enum in the GraphQL Admin API reference or Storefront API reference.

As of GraphQL Admin API version 2022-04, a new originTime field has been added to subscriptionBillingAttempt. Fulfilment intervals for subscriptions are normally calculated using the billing attempt date, but may be overridden with this new field if the billing happens to occur after the current anchor date. This can be done to prevent fulfilment from being pushed to the next anchor date when billing is delayed.

Visit our documentation on Creating a Billing Attempt and Advanced Delivey Behaviours for Subscriptions to learn more about this new field.

As of GraphQL Storefront API version 2022-07, the Collection object has a new field: SEO. This field returns an SEO object.

Learn more about this API on Shopify.dev.

As of GraphQL Admin API version 2022-04, a new deliveryGroups connection has been added to cart. It consists of a group of delivery options available for the line items in the cart, for a specified shipping address. Delivery groups are only available for logged-in customers with a full default address.

Refer to our documentation on cartCreate and customerCreate to learn more about how to create a cart associated with a logged-in customer.

As of Admin API version 2022-04, two new fields, source_url and source_identifier have been added to the Orders and Checkout objects in both the REST and Graph APIs. The source_name field will also be updated across these APIs for the Orders, Draft Orders and Checkout object. By adding a valid source_name, the order will be attributed to a list of sales channels found within the partner's dashboard.

More information can be found here

As of GraphQL Admin API version 2022-04, a new checkoutCharge field has been added to sellingPlan. It consists of a charge type (either percentage or price), and an amount, indicating how much of the product's cost will be charged at the time of checkout. This field is currently restricted behind the extend_selling_plans_api beta flag.

After the release of Shopify Markets, we are following up with the Markets API in version 2022-04. The API allows you to create, update, and delete markets and their settings.

Shopify Markets unlocks the ability to create high-performing, localized buyer experiences by allowing merchants to specify the domain, language, currency and price that international buyers see when browsing a merchant's storefront.

You can learn more about the Markets API on shopify.dev.

GraphQL Admin API

As of GraphQL Admin API version 2022-04, we're adding the fulfillBy to the FulfillmentOrder object. The field represents the latest date and time when all items in the fulfillment order need to be fulfilled.

We're also adding the maxDeliveryDateTime and minDeliveryDateTime fields to the DeliveryMethod object. When combined, they represent a range of time when the delivery is expected to be completed.

Learn more about FulfillmentOrder and DeliveryMethod objects.

REST Admin API

As of REST Admin API version 2022-04, the following properties are added to the FulfillmentOrder resource:

• fulfill_by
• delivery_method.max_delivery_date_time
• delivery_method.min_delivery_date_time

Learn more about the FulfillmentOrder resource.

In addition to edges, GraphQL connections now have a nodes field. When you only query node on edges, you can simplify the query.

For example:

{ connection { edges { node { fields } } }

can be simplified to:

{ connection { nodes { fields } } }

PageInfo has been expanded as well to include startCursor and endCursor.

When these fields are used in tandem, it can simplify the shape of return data for pagination.

Previous query format:

{ connection { edges { cursor node { fields } } pageInfo { hasNextPage } } }

Improved query format:

{ connection { nodes { fields } pageInfo { hasNextPage endCursor } } }

We are introducing new flexible ways for app partners to offer merchants incentives for app subscriptions.

Recurring App Discounts

As of GraphQL Admin API version 2022-04, app developers can now offer limited time discounts on recurring app charges through the Billing API. Partners may define a percentage or fixed amount discount that will be applied to a designated number of billing cycles (e.g. 20% of 6 billing cycles). This will enable app partners to create introductory offers for new merchants.

Learn more about app billing discounts on Shopify.dev.

App Trial Extensions

App developers can increase the number of trial days offered to a recurring app charge by using the new appSubscriptionTrialExtend offered without merchants accepting a new app subscription. This will enable developers to provide new merchants additional time to trial products. App trial extension is currently available in the unstable version of the GraphQL Admin API.

Learn more about trial extensions on Shopify.dev.

As of GraphQL Admin API version 2022-04, checkoutChargeAmount and remainingBalanceChargeAmount fields have been added to sellingPlanAllocation. These fields indicate how much of a product variant's price must be paid upfront, and how much must be paid at a later date. This field is currently restricted behind the extend_selling_plans_api beta flag.

You can now create videos and transcode them to multiple formats, using the FileCreate mutation.

You can also attach videos to metafields using file_reference. These videos are also available using the Storefront API.

As of GraphQL Admin API version 2022-04, a new owner type ApiPermission is now available for metafields. A metafield with this permission type will only be readable and writable by the app that owns the metafield.

Theme developers can now use the Shopify CLI theme serve command with the new --theme-editor-sync flag. When active, theme editor changes are automatically synced back to the local development files.

Learn more about Shopify CLI theme commands.

Developers can now programmatically push their scripts and extensions to Shopify from their CI/CD pipelines with CLI authentication tokens.

For more information on how to set up CI/CD for your scripts and extensions, visit our developer documentation.

Two new input setting types have been added to the theme editor: product_list and collection_list. They allow merchants to quickly create curated, ordered and paginatable lists of products and collections.

Learn more about product_list and collection_list on shopify.dev.