Developer changelog

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 create section groups in your theme’s layout. Section groups are JSON containers that allow merchants to add, remove, and reorder sections in areas of the layout file such as the header and footer.

To include a section group in a layout file, add the section group to the sections directory of your theme, then add a {% sections '<filename>' %} Liquid tag that references your new sections file to the layout file where you want it to be rendered.

To learn more, refer to section groups.

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.

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.

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

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

Starting in January 2023, on the 2023-01 API release, some queries could be processed and returned asynchronously based on complexity and the amount of shop data. Most queries will continue to be evaluated synchronously. This breaking change allows you to build the best possible user experience as we introduce more complex filters in Segmentation. Async queries should revolve within 5 seconds but some queries might take up to 1-2 minutes or even longer.

To get up to date, make sure you are handling responses returning an error code because the query must be processed asynchronously. You can follow our migration guide.

Learn more about building for asynchronous queries in our developer documentation or visit our API forum for questions.

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 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, 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 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 2023-01, the metafieldsSet mutation is atomic and will not persist changes if any errors are encountered.

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

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.

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

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

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.

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.

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 2022-07 API version, it's mandatory for a fulfillment service to follow a fulfillment order based workflow and have fulfillment_orders_opt_in set to true in FulfillmentService resource. The last API version serving the legacy fulfillment APIs is 2022-04.

With 2023-01 release, we add observability to the migration process.

Errors will be returned if a legacy (fulfillment orders opt-out) fulfillment service is intended to be created on an API version, where the legacy fulfillment APIs are not available.

Errors will be returned on fulfillment service create REST and GraphQL API calls if fulfillment_orders_opt_in field is not set into true in the parameters.

Errors will be returned on fulfillment service update REST and GraphQL API calls if the fulfillment service being changed has fulfillment_orders_opt_in set to false and the update request does not promote fulfillment_orders_opt_in into true. fulfillment_orders_opt_in and callback_url become required parameters for fulfillment service create request/mutation.

Follow Migrate to fulfillment orders guide to learn how to migrate. Follow Manage fulfillments as a fulfillment service app guide to learn how to fulfill fulfillment orders.

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 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 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 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 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 January 1, 2023 stores on Starter and Basic plans (globally), will no longer be able to request access to the Carrier Service API. The option to request access by transitioning to annual billing or by paying an additional monthly fee for these plan types will be removed.

Stores on Advanced and Shopify Plus plans will continue to have access to Carrier Service API. Stores on Shopify plans can continue to request access by contacting Shopify Support. Stores on Starter or Basic plans that were previously granted access are not impacted by this change.

Learn more about CarrierService access requirements on Shopify.dev.

As part of GraphQL Admin API version 2023-01, we are removing SMS Templates as a translatable resource. This means the SMS_TEMPLATE value will be removed from the TranslatableResourceType enum and the following GraphQL endpoints will stop accepting SMS Template IDs:

• translationsRemove
• translationsRegister
• translatableResource
• translatableResourcesByIds

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