Developer changelog

As of 2024-04, new GraphQL product APIs are now available in stable release.

These new APIs increase per-product variant support from our historical max of 100 to a new limit of 2000.

In addition to higher variant support, you can use the product option mutations to manage options and option values on your products. You can also query for your product's productOptions and your product variants' optionValues.

Learn more about the new product and option value GraphQL APIs on Shopify.dev.

Also included in this stable release, you can use the productSet mutation to set the entire state of a product from an external data source into Shopify, in addition to the existing mutations for adding/deleting/updating individual variants.

Learn more about the new productSet GraphQL API on Shopify.dev.

See our guide to sync product data from an external source for more information.

With the 2024-04 API release, we will also be deprecating management of both variants and options via the GraphQL ProductInput object and the /products and /variants REST API endpoints. Learn more here.

As of 2024-04, you can use priceWithCurrency to provide the price of the shipping rate along with the currency, whereas price uses the shop currency. If priceWithCurrency is provided, price will be ignored.

Learn more about priceWithCurrency on Shopify.dev.

As of 2024-04, you can set LineItem attributes on Bundle items using CartTransform Merge and Expand operations.

You can set custom attributes to either the Bundle item or its components using the new field.

Learn more about Bundles on Shopify.dev.

As of Storefront API version 2024-04, you can use the @inContext directive to query product and productVariant fulfillable inventory for specified market country. The Fulfillable Inventory feature must be enabled.

query Contextualized @inContext(country:CA){
  product(id:"gid://shopify/Product/1" )
  {
        availableForSale
        totalInventory
        variants(first:1)
        {
          edges
          {
            node
            {
              id
              availableForSale
              quantityAvailable
              currentlyNotInStock

            }
          }
        }
      }
}

Learn more about Fulfillable Inventory on Shopify help docs.

As of 2024-04 developers can now sort and search Fulfillment Orders in GraphQL queries by the UPDATED_AT field.

This will help app developers and fulfillment services to prioritize their work on fulfillment orders and reduce the query cost when sorting and searching through other filters.

Learn more about sort and search parameters for fulfillment orders on Shopify.dev

As of API version 2024-04 the Checkout API’s will be marked as deprecated. This deprecation will impact both the Admin REST API (excluding Abandoned Checkout) and Storefront GraphQL API endpoints. To maintain continuity and unlock new capabilities, apps will need to migrate to either the Storefront Cart API, and or Checkout Sheet Kit for mobile apps.

Deprecation Schedule:

April 1, 2024 (Version: 2024-04) All affected fields within the Checkout APIs will be marked as deprecated. This is the final stable version where the Checkout APIs will remain available. The fields will also be removed from unstable and the 2024-07 Release Candidate versions onwards. We strongly recommend you to start migrating to the new API when possible to avoid any disruptions.

April 1, 2025 (Version: 2025-04) The 2024-04 API version will reach its end of life. As a result, Checkout mutations will no longer be available on any version.

Recognizing the need for a high throughput cart, Shopify introduced the Storefront Cart API in 2021 as the successor to the Checkout API, and we have been continually enriching it with new features. The Cart API offers improved performance, scalability, and a richer feature set including subscriptions, product bundles, and contextual pricing. Additionally, it integrates with Shopify's web checkout for further customization using Shopify Functions and UI extensions.

The Checkout Sheet Kit, compatible with Android, Swift, and React Native, streamlines mobile app development by integrating a fully-featured web checkout. This eliminates the need for a separate checkout build, reducing maintenance while preserving all customizations and business logic.

Action Required:

Follow the Cart API Migration Guide to update any application calling Admin REST API or Storefront GraphQL API checkout endpoints prior to 2025-04 to utilize the Cart API or Checkout Sheet Kit to avoid disruption.

If you have questions, please utilize the feedback repository.

As of 2024-04, OrderTransaction.receipt will be removed from the Admin GraphQL API. The field has been deprecated since 2019-04 and is replaced by OrderTransaction.receiptJson

Both fields contains the same data but in different formats. receipt was returning a Ruby hash formatted as a string, while receiptJson is returning JSON.

Standardizing around JSON-formatted receipts will make it easier for developer to build consistent integrations and removing duplicate fields will simplify our API.

Learn more about the change in the OrderTransaction GraphQL API documentation

As part of the GraphQL Storefront API 2024-04 API release, we've updated the cartNoteUpdate API to make the note argument required.

Learn more about the Cart object on Shopify.dev.

As of GraphQL Admin API version 2024-04, the following Customer sort keys have been deprecated: LAST_ORDER_DATE, ORDERS_COUNT, TOTAL_SPENT. Ordering customers by these attributes is available when filtering customers using segments.

Learn more about customer segmentation on Shopify.dev.

As of 2024-04, you can use the metafieldsDelete mutation to delete up to 25 metafields at once.

Learn more about metafields on Shopify.dev.

As of Admin API 2024-04, we are removing the following fields and mutations:
- InventoryLevel.available
- InventoryLevel.incoming
- InventoryLevel.deactivationAlertHtml
- Mutation.InventoryAdjustQuantity
- Mutation.InventoryBulkAdjustQuantityAtLocation

After building new fields to handle inventory quantities other than available, new fields and mutations that can handle all quantities were needed and released in 2023-01.

InventoryLevel.available and InventoryLevel.incoming should be replaced with InventoryLevel.quantities.

InventoryLevel.deactivationAlertHtml should be replaced with InventoryLevel.deactivationAlert.

Mutation.InventoryAdjustQuantity and Mutation.InventoryBulkAdjustQuantityAtLocation should be replaced with Mutation.InventoryAdjustQuantities or Mutation.InventoryMoveQuantities.

For those still using these fields on unstable, they will continue to work until 2024-04 is no longer supported.

More information on how to use these new fields can be found here

As of 2024-04 version Admin GraphQL API, you can update inventory_management boolean value on the FulfillmentService object using the [fulfillmentServiceUpdate mutation]((https://shopify.dev/docs/api/admin-graphql/2024-04/mutations/fulfillmentServiceUpdate) .

Learn more about inventory_management argument on Shopify.dev.

As of Admin version 2024-04 , there cannot be multiple of the same fulfillment_order_id within the line_items_by_fulfillment_order param for the REST "Creates a fulfillment for one or many fulfillment orders" API and GraphQL fulfillmentCreateV2 mutation.

Please combine any payload with the same fulfillment_order_id into one group.

The fulfillmentOrdersOptIn field on the FulfillmentService GraphQL and REST API objects, along with the related mutations and endpoints, is being deprecated as the migration to the Fulfillment Orders API has been completed. All properly functioning fulfillment services now have the fulfillmentOrdersOptIn field set to true.

In the 2024-04 API version, the fulfillmentOrdersOptIn field becomes nullable and defaults to true in the fulfillmentServiceCreate mutation and the Create Fulfillment Service REST endpoint. This field will be removed from the mutation input and the REST endpoint parameters in the subsequent API version (2024-07). To prepare for the 2024-07 API version release, stop supplying the fulfillmentOrdersOptIn parameter when creating a new fulfillment service.

As of 2024-04, we're removing the deprecated productDuplicateAsync mutation. The mutation was deprecated since 2023-07 version.

Use the productDuplicateAsyncV2 mutation instead.

As of API version 2024-04, you can retrieve a subset of fulfillment orders which are assigned to locations owned by the app performing the request but have not been requested for fulfillment so far.

The assignment_status parameter in the assignedFulfillmentOrders query can now accept a value of FULFILLMENT_UNSUBMITTED for filtering in addition to the existing FULFILLMENT_REQUESTED, FULFILLMENT_ACCEPTED, and CANCELLATION_REQUESTED filter values.

As of GraphQL Storefront API version 2024-04, we are adding support for query contextualization for B2B buyers via the @inContext directive. This allows developers to query the products and prices a B2B buyer may have for a particular company location.

Developers will also be able to query associated volume pricing and quantity rules, and work with a Cart that is aware of B2B specific rules and pricing.

Developers will also be able to query a purchasing company associated with a cart.

Learn more about B2B on Shopify.dev.

As of the 2024-04 release of the GraphQL Customer API, you can now query for a customer's subscription contracts using the subscriptionContracts or subscriptionContract fields.

This allows developers to query for all subscription contracts belonging to a customer, or to query for a specific subscription contract.

Learn more about querying for a customer's subscription contracts on Shopify.dev.

As of 2024-04, Added the following fields to the SubscriptionBillingAttemptErrorCode enum

• InsufficientFunds
• PurchaseTypeNotSupported
• Paypal Error
• CardNumberIncorrect
• FraudSuspected

Additionally, the following payment error code mappings have changed: * “Insufficient Funds” has been removed from “Invalid Payment Method” and now receives its own billing attempt error * “Pick up card” has been removed from “Payment Method Declined” and is now classified as “Fraud Suspected” * “Invalid Item Total” has been added to “Payment Method Declined”

And the following codes from payment processors have changed:

• Braintree

  • 2007 now maps to “Card Number Incorrect”
  • 2014 now maps to “Fraud Suspected”
  • 2105 now maps to “Transient Error”
  • 2106 now maps to “Transient Error”
  • 2107 now maps to “Invalid Payment Method”
  • 2108 now maps to “Invalid Payment Method”

• Paypal

  • 10417 now maps to “Paypal Error General”

• Stripe

  • cardnotsupported now maps to “Invalid Purchase Type”
  • invalid_account now maps to “Card Number Incorrect”
  • invalid_amount now maps to “Payment Method Declined”

As of version 2024-04 of the Admin API, you can use the checkoutBrandingUpsert mutation to configure two new color schemes: scheme3 and scheme4.

With this change, up to four color schemes can be configured and used in different sections.

Learn more about these new color chemes here

As of version 2024-04 of the Admin API, you can use the checkoutBrandingUpsert mutation to configure styling for the header and footer of your checkout.

With this change, header and footer sections can now be customized with color and spacing controls.

You can learn more about customizable header and footer in the GraphQL Admin API docs.

The new customizable fields are colorScheme and padding.

Shopify has introduced a public product taxonomy, serving as an open-source, standardized, and global classification of products sold on Shopify. This taxonomy, composed of product categories, attributes, and attribute values, is utilized across Shopify and integrated with numerous marketplaces. You can view the latest product taxonomy on our taxonomy explorer.

The new product taxonomy is now available in our public API with the 2024-04 release. This feature allows developers to navigate the taxonomy tree for categories, attributes, and values.

In order to support this change a number two existing APIs have been deprecated and replaced in favor of queryRoot.taxonomy.categories

• queryRoot.productTaxonomy
• queryRoot.productTaxonomyNodes

Additionally the following changes have been made:

• The ProductTaxonomyNode type has been replaced with a TaxonomyCategory type.
• The productCategory field on Product has been deprecated and replaced by category. This field directly references the new TaxonomyCategory type.

Orders with payment terms no longer always include an OrderTransaction when created from a Draft Order. Going forward, the transactions field on these Orders will be treated as an output that provides specific information about payments and other financial events related to the order, rather than as an implicit signal or side effect of creating an order from a draft.

If your app depends on implicit OrderTransactions that are added by creating an order from a draft, then you will need to switch to alternative options, for example recording payments or payment methods on an order to create an OrderTransaction.

Introducing Pickup Points, a new Shopify Function that enables developers to build custom apps for Plus shops that offer pickup points in checkout to locations like post-offices and parcel lockers.

Developers can integrate third-party pickup locations from any network of their choice, customize delivery information based on business logic, and define location-based pricing.

Pickup Points is only available for Shopify Plus merchants.

We want your feedback! Try Pickup Points early and share feedback that will directly guide development. To request access, contact us at pickup-point-generator-early-access@shopify.com.

Visit the developer documentation for more information.

We are changing how trials can be configured on your app listing:

• Trials will now be plan-level rather than app-level
• Free plans can no longer have a trial associated with them as they should not be time bound
• The change applies to apps with recurring monthly/annual subscription plans
• The change does not impact apps that are listed as completely free, or free to install

This update gives you more control on how you market trials on the App Store.

Shopify has auto-filled the app-level trial data to each plan card based on the last app listing submission form configuration. Please update these default values in the app listing submission form if you have plans with different trial lengths.

There is a grace period before plan-level trial changes appear on Shopify App Store app listing pages, which will happen on April 29th. This grace period does not apply to other fields in your app listing submission form, which you can still edit and update in real-time.

To modify trial durations, manage your app’s listing in the Partners Dashboard under the Distribution tab. Learn more about configuring your app listing on Shopify.dev.

Get your apps published faster with our streamlined app review experience. It provides a clear, guided process that ensures you’ve checked off some key requirements before submitting and contextual guidance that reduces rework. You'll know exactly where you are in the process at a glance with actionable statuses that let you know what to expect next.

Learn more about the app submission process on Shopify.dev.

As of 2024-04, we are making it easier to use our External Marketing API by removing old deprecated values and exposing is_external as a value.

Breaking Changes

• The deprecated follow_up, receipt, display, search, seo and direct marketing tactics are being removed from the 2024-04 API version. See the MarketingTactic documentation for which tactics should be used instead.

Non-breaking Changes

• The is_external attribute can be fetched in the MarketingActivitiesquery to know if an activity was created and is managed by an external platform.

Network access for Shopify Functions is now available in early access. Primarily for merchants on Shopify for enterprise, this powerful new capability allows merchants to integrate Shopify with their own commerce ecosystem and fetch information from external services.

Network access is currently supported in early access on the following Shopify Functions:

• Cart and Checkout Validation
• Local Pickup Delivery Option Generator
• Pickup Point Delivery Option Generator

To learn more about Network access for Shopify Functions, please refer to the documentation.

As of REST API 2024-04, we’re deprecating the Reports resource.

The REST API Reports resource used to create custom reports in analytics has been deprecated. You can still use previous, stable versions of the REST API to continue creating custom reports in admin for the time being.

As of API version 2024-07, the variant image field in the product_feed/incremental_sync and product_feed/full_sync webhooks will no longer fall back to the product's first image when an image has not been explicitly set for the variant. Instead, no image will be returned.

If this change is undesirable for your use case, you can replicate the old behavior by assigning the first product image to the variant when it is null after receiving the webhook.

In May 2022, Shopify announced that unpublished apps would no longer be supported. To ensure merchant trust and security, all apps must now pass Shopify App Store review to guarantee the best app experience including branding, installation, onboarding, functionality, and quality. Developers with unpublished apps are required to take action by either converting them to public apps by meeting Shopify App Store requirements and submitting them to Shopify for review, or sunsetting their unpublished apps.

Impacted developers will receive an email outlining next steps, including the deadline to submit your apps for review. Please ensure your contact information is up to date.

If your unpublished apps have not been submitted for review or sunset by the deadline, these apps will have their API access revoked and will be uninstalled from all merchant stores. Developers will be notified at least 60 days prior to any changes being made.

For more information, please visit our documentation.

To enhance the security of merchant and customer information and provide additional protection for customer data, we’ve implemented level 2 protected customer data requirements for partners and developers, alongside new timeout parameters and login requirements to the Order Status Page.

After an order is created, customers can access the Order Status Page without logging in for a limited timeframe and/or number of browser visits. After these timeout parameters have been reached, customers must provide credentials to access the Order Status Page, such as phone number, email address, order number, or by using passwordless login.

We recommend that partners and developers who send transactional SMS on behalf of merchants include the customer’s order number alongside any links to the Order Status Page.

Learn more about changes to the Order Status Page in our developer documentation.

As of version 2024-04 of the GraphQL Admin API, a new optional field title has been added to validationCreate and validationUpdate. This will allow you to create multiple instances of the same Validation function where the unique title will help merchants easily differentiate between them.

As of version 2024-04 in the GraphQL Admin API, new fields createdAt, updatedAt, and isFulfillmentService have been added to the Location object.

Learn more about Location fields on the GraphQL Admin API at Shopify.dev.

We are requiring apps to meet Level 2 Protected Customer Data Requirements in order to acess the field order.statusPageUrl on the Admin GraphQL API and on the Admin REST API. This change is applicable to all API versions. We recognize that this may be a breaking change for some apps. However, this change is necessary to ensure the protection of customer data.

Learn more about Protected Customer Data, including the actions you need to take to enable existing apps to continue to have access to order.statusPageUrl on Shopify.dev.

With the latest version of App Bridge, you can use the ui-save-bar component and the SaveBar React component to declaratively control the contextual save bar, including setting loading and disabled states of the Save and Discard buttons. Learn more about it in the documentation.

With the latest version of App Bridge, you can use the src attribute with the ui-modal component and the Modal React component to display content from the provided URL. Learn more about it in the documentation.

As of version 2024-04, you can use the GraphQL Admin API to query a shop's Shopify POS cash tracking sessions. The API returns cash tracking data for locations that have a Shopify POS Pro subscription

Below are some examples of the data that's available on the new CashTrackingSession type:

• Opening and closing times, and the staff member who performed each action
• Adjustments to add or remove cash from the cash drawer, and the staff member who performed each action
• Notes attached to the actions listed above
• Aggregations, such as the total cash sales, total cash refunds, and the net cash sales that were processed during the cash tracking session
• Discrepancies between the amount counted in the cash drawer and the amount expected

To find out more, see CashTrackingSession in the GraphQL Admin API reference.

As of version 2024-04 of the Storefront API, you can use new attributes of the Filter and FilterValue objects to create visual filters for your custom storefront.

We are adding FilterValue.swatch intended for color and pattern swatches and FilterValue.image for more detailed imagery. Use the new Filter.presentation attribute to know the intended display of each filter.

Merchants must use Shopify's Search & Discovery app to set visual filters for their store.

As of March 13, we added the following updates to POS UI Extensions:

• Added a discounts property to the Cart object, which includes all cart discounts.
• Added addCartCodeDiscount to the Cart API, which allows the UI extension to add a code discount. The existing applyCartDiscount will still function for code discounts, too.
• Added remove AllDiscounts to the Cart API, which allows the UI extension to remove all cart discounts.
• Added a listHeaderComponent to the List component.

All of the changes are available for POS UI extensions version 1.7.0 and POS app version 9.4.0. See the version log for all version details.

As of Admin GraphQL API version 2024-04, the isGiftCard field that was present on DraftOrderLineItem and CalculatedDraftOrderLineItem is now also present on:

• ExchangeCheckoutLineItem
• ExchangeV2LineItem
• LineItem
• LineItemMutable

It is now preferable to use this field to check whether a line item is a gift card instead of using the fulfillment service.

As of March 13th, 2024, net new Shopify App Store apps must use the latest Shopify App Bridge by adding the app-bridge.js script tag to the <head> of each document of your app.

As of version 2024-04 of the Admin GraphQL API, the subscriptionContractAtomicCreate and subscriptionContractCreate mutations will return a new error code CUSTOMER_REDACTED when creating new subscription contracts for customers scheduled for redaction or have been redacted.

Learn more about customer redaction here.

You can now use a Liquid swatch drop to create visual filters for your Online store themes.

The filter value display drop is now considered deprecated in favour of swatch. The display drop will continue to function as it does today for backwards compatibility in merchants’ themes.

As of Storefront API's 2024-04 release, you can use cart.deliveryGroups.groupType to determine whether a delivery group represents a single delivery (ONE_TIME_PURCHASE) or is a recurring delivery (SUBSCRIPTION)

You can now collect the id of a customer within the order object of the checkout_completed customer event. This gives you more customer insights to improve marketing campaign targeting and analytics.

Learn more about the checkout_completed event in our developer documentation

• Clarified webhooks-related terminology in the Webhooks Overview page to make it easier to get started
• Updated accuracy of Limitations on webhook delivery guarantees
• Updated technical implementation accuracy of Avoiding debounces

Hydrogen v2024.1.3 is out today. The March 2024 Hydrogen release contains several new features:

• Hydrogen now includes experimental support for Vite.
• A new env push__unstable command to upload local environment variables to Oxygen from the command line
• You can now get comments on GitHub PRs when Oxygen creates a preview deployment on your connected storefront.

In addition to these new features, Hydrogen 2024.1.3 includes a range of updates, performance upgrades, and bug fixes, including an upgrade to Remix v2.8.

Check out our full Hydrogen March 2024 release blog post for more details. And please drop your comments, feedback, and suggestions in GitHub Discussions!

Developers must create a video demo that illustrates how to use their app, as a now mandatory requirement for submission.

New apps that are in a Draft status will be asked to provide this prior to submitting for initial review. Submitted apps that are already in initial review may be asked to provide one before they can be published. Published apps that become Delisted may be asked to provide one before they can become published again.

This requirement will substantially help our review team to understand app flows and functionality during testing, and will speed up the review process.

Returns will now create corresponding Sales entries.

As of 2024-04, SalesAgreements made as part of a return will have the type ReturnAgreement. The OrderActionType enum can have a type of RETURN.

As of 2024-04, the SaleLineType enum can now have a type of FEE. Fees can be of the type RestockingFee or ReturnShippingFee, representing corresponding fees on a return.

Any Admin API consumers of OrderActionType or SaleLineType will need to accept this new enum value. Previous versions of the Admin API will show these values as "UNKNOWN".

You can now view ExchangeLineItems on their associated return. This provides context on returns that will be resolved with an exchange.

A new webhook "returns/update" has been added. This webhook will fire when fees or line items on a return are modified or removed. All returns webhooks will now display restock and shipping fees, as well as exchange line items.

Dispositions can no longer be created for canceled reverse fulfillment orders. This will result in the new error code INVALID_STATE.

Restocking returned items in the Admin will now create ReverseFulfillmentOrderDispositions.