2024-07 release notes

Similar to creating a new order through checkout, the availability of inventory is now checked during the billing attempt process.

Where product variants are configured to prevent overselling and one or more items in the contract are out of stock, then the billing attempt will fail with the new INSUFFICIENT_INVENTORY error code.

Learn more about subscription contracts and billing attempts.

The discountedPriceSet and discountedPrice fields on the ShippingLine object now include cart-level discounts applied to an order, including the free shipping discount, when calculating the discounted price.

In API versions prior to 2024-07, you needed to subtract the discountAllocations from discountedPriceSet or discountedPrice fields to get an accurate value. If you do this in API version 2024-07 and higher, then you'll subtract the same discount twice.

You can now query the cash transactions that are associated with each cash tracking session. The new cashTransactions connection returns all of the cash order transactions that affected the amount in the cash drawer during a cash tracking session.

You can use the checkoutBrandingUpsert mutation to configure the styling and visibility of dividers in checkout.

With this change, the dividers below the header, above the footer, between the main and order summary columns, and between sections in the main column can now be customized with visibility, style, and width controls.

The following new types are available:

You can now query the typOspPagesActive field on the CheckoutProfiles object. The typOspPagesActive field returns the status of the Thank You page (TYP) and Order Status page (OSP) on a checkout profile, providing insight as to whether the pages have enabled checkout extensibility.

If typOspPagesActive is true, then both the Thank You and Order Status pages are using checkout extensibility, and render the appropriate checkout UI extensions while also making use of pixels, and Functions. If typOspPagesActive is false, then the Thank You and Order Status pages still use scripts and other deprecated features.

Combined listings bring together products that are merchandised by an option, such as color, model, or dimension, for enhanced display in the product details page.

As of API version 2024-07, you can use the GraphQL Admin API to manage combined listings.

We've added the dataSaleOptOut mutation, which opts a customer out of data sales and sharing, and supports compliance with US state laws like CCPA and CPRA. The dataSaleOptOut mutation also applies the opt-out to the Customer Privacy API.

We've also added the dataSaleOptOut field to the Customer object.

To learn more about data sales and sharing opt-outs, refer to Configuring customer privacy settings.

We've added the DeliveryPromiseProvider object, which represents an entity, such as a third-party service, that can provide delivery estimates on behalf of a store.

Each DeliveryPromiseProvider object is associated with a shop Location.

A DeliveryPromiseProvider object can be created or updated using the deliveryPromiseProviderUpsert mutation, and retrieved using the deliveryPromiseProvider query.

DraftOrderInput now accepts discountCodes, acceptAutomaticDiscounts, and allowDiscountCodesInCheckout. These optional input fields allow you to apply discount codes to a draft order and decide whether to accept automatic discounts when a draft order is calculated.

We've also added the platformDiscounts field which provides details about how the platform discount has been allocated across the draft order line items, the discount type, its name, and more.

The following new types are available:

The DUPLICATE_VALUE error code has been added to the ProductSetUserErrorCode enum.

The id field on the ProductVariantSetInput input object now has validation support to prevent duplicate values. This enhancement ensures that there are no collisions when updating variants.

You can now use the GraphQL Admin API to interact with exchanges.

The returnCreate mutation can now take exchange line items with optional discounts, return shipping fees, and restocking fees to be applied to return lines. A return with exchange line items will also create a new FulfillmentOrder for the new items to be sent to the customer.

You can use the returnLineItemRemoveFromReturn mutation to remove return lines from a return. With returns creating sales, removing a return line from a return will also reversely impact return sales.

Additionally, you can use the returnCalculate query to calculate financials before return creation, including inputs for return lines, exchange lines, fees and discounts. Learn how to use the returnCalculate query.

The following new types are available:

The following customer query filters in the search syntax have been deprecated:

• accepts_marketing
• city
• company
• country
• customer_date
• email_marketing_state
• last_abandoned_order_date
• order_date
• orders_count
• province
• sms_marketing_state
• state
• tag
• tag_note
• territory_code
• total_spent

You can filter customers by these attributes using segments instead.

When you create, update, or query a webhook subscription, you can now include a filter parameter. Filter parameters, which are specified using Shopify search syntax, allow you to specify conditions as to when webhooks should be emitted for a subscription.

We've added the MAXIMUM_FULFILLMENT_CONSTRAINT_RULES_REACHED error code to the fulfillmentConstraintRuleCreate mutation. The error code is returned when you add more than a maximum of ten fulfillment constraint rules to a store.

You can now access assigned fulfillment orders from the assignedFulfillmentOrders connection on the QueryRoot object instead of from the pre-existing assignedFulfillmentOrders connection on the Shop object. This change includes the deprecation of the Shop.assignedFulfillmentOrders query in favour of the newly added QueryRoot.assignedFulfillmentOrders query.

The DeliveryMethodType enum also now includes the PICKUP_POINT value to identify fulfillment orders containing deliveries to pickup point locations.

Learn how to generate pickup point options.

The variant field has been added to the FulfillmentOrderLineItem object.

The field enables order management apps to reference the specific product details that are related to each fulfillment order line item without needing to directly compare SKUs in the order line items.

Learn more about order management apps.

We've added new types to the GraphQL Admin API to provide parity with the following REST resources: CarrierService, Customer, Fulfillment, FulfillmentEvent, FulfillmentService, InventoryItem, Location, Order, and Product.

The following new types are available:

The includeFields that are specified on a webhook subscription are now available for all webhook topics. Previously, some webhook topics weren't respecting the includeFields configuration.

We've added new fields to the ShopPolicy object. A ShopPolicy is a policy that a merchant has configured for their store, such as their refund or privacy policy.

We've made several improvements to Shopify Payments payouts and balance transactions in the GraphQL Admin API to provide parity with the REST Admin API:

• You can now use Shopify's API search syntax to filter and sort payouts using the sortKey and savedSearchId parameters. This functionality allows you to efficiently search and organize payouts based on specific criteria such as ledger_type, status, amount, currency, and issued_at.

• You can now use the following new fields on the ShopifyPaymentsBalanceTransaction object:

  • sourceID: Represents the ID of the object that led to the transaction.
  • sourceOrderTransactionID: Indicates the ID of the order transaction that triggered the balance transaction. If the sourceType is an adjustment, then this value is null.
  • adjustmentOrderTransactions: An array of associated order transactions that resulted in the balance transaction. If the sourceType is not an adjustment, then this array is null. Each object in the array includes adjustmentReason, which specifies the reason for the adjustment associated with the transaction. If the sourceType is not an adjustment, then value is null.

The LEDGER_DOCUMENT_INVALID error code has been added to the inventorySetScheduledChanges mutation. The error code is returned when the ledgerDocumentUri provided is not a valid URI.

Prior to API version 2024-07, you could send inventory item data using ProductVariant mutations or on the InventoryItemUpdate mutation. Each of these places has a different input object type with very similar fields, and with some fields showing up in one mutation instead of the other.

As of API version 2024-07, the two input types are unified. InventoryItemInput is now the input object type on the inventoryItemUpdate mutation instead of the InventoryItemUpdateInput input object.

The Location object is now gated by the read_locations access scope. If you attempt to read the Location object without the read_locations access scope, then an access denied error is returned.

You can now use the urlParameterValue field as a tracking parameter in the marketingActivityCreateInput and marketingActivityUpdateInput input objects. This field is currently only available to select partners. Most partners should continue to use UTMs for tracking parameters.

Additionally, the MarketingActivityUserError enum is now a required type on the userError field for the marketingEngagementCreate mutation.

The PRODUCTS_CREATE and PRODUCTS_UPDATE webhook payloads now contain information about the media on a product.

You can now use the fileUpdate mutation to connect files to products.

The following new types are available:

You can now use the GraphQL Admin API to read and modify menus on the Online Store.

The following new types are available:

Apps can now query the access field of metafield definitions that they have access to but don't own. Previously, an AuthorizationError error was returned when accessing the field for metafield definitions that an app didn't have permissions to manage.

The admin and storefront fields on the MetafieldAccess object now return values in more cases instead of null. For example, metafields that don't have associated access grants return PUBLIC_READ_WRITE for admin access and LEGACY_LIQUID_ONLY for storefront. In addition, definitions that were created with a storefront access of NONE now return NONE instead of null. As of API version 2024-07, you can set PUBLIC_READ_WRITE as the admin access control.

Additionally, the admin and storefront fields on the MetafieldAccessInput input object now use dedicated input enum types, MetafieldAdminAccessInput and MetafieldStorefrontAccessInput, respectively.

The following new types are available:

You can now use the metafields and metafieldDefinitions connections on the OnlineStoreArticle, OnlineStoreBlog, and OnlineStorePage objects. Previously, you could only retrieve metafields and metafield definitions connections using the REST Admin API.

We've added new types for reading standard conditional metafields and filtering metafield definitions by constraints:

We've added a new error code for mutations that set metafields. The INTERNAL_ERROR error code has been added to the MetafieldsSetUserErrorCode enum.

The Metafield and MetaobjectField objects now have a jsonValue field that returns the stored value as a JSON scalar.

By using the jsonValue field, metafield values that are stored as JSON strings don't have to be parsed on the client-side. The field is set for all metafield types and is also available in all Function APIs. The jsonValue field can be used in Function input queries to improve function performance and reduce the instructions needed to parse JSON metafield values, which are commonly used for function configuration.

We've added the RESERVED_NAMESPACE_ORPHANED_METAFIELDS error code to the MetafieldDefinitionDelete mutation.

The MISSING_CUSTOMER_PAYMENT_METHOD error code is now returned when payment information is missing on the subscriptionDraftCommit mutation.

We've added the DISPLAY_NAME_CONFLICT error code value to the MetaobjectUserErrorCode enum.

You can now retrieve information about the storefront password of an online store using the OnlineStorePasswordProtection and OnlineStore objects.

The variants and productOptions fields on the ProductSetInput input object are now optional. In API versions prior to 2024-07, the variants and productOptions fields were required.

Shopify Plus merchants using Shopify Payments are able to partially capture authorizations more than once. However, you might know that the capture you're about to perform will be the last one. To reflect this, we've added the finalCapture field to the orderCaptureInput input object.

When you know you're capturing an authorization for the last time, setting the finalCapture field to true releases any uncaptured funds back to your customer. Doing so is likely to increase customer satisfaction and decrease the risk of chargebacks.

For merchants not on the Shopify Plus plan, the finalCapture field has no effect: these authorizations can only be captured once, and uncaptured funds are always returned immediately to the customer.

Currently, the finalCapture field only applies to transactions made through Shopify Payments. When capturing authorizations processed through other gateways, finalCapture must either be omitted, or set to null.

You can now use the transactionsCount field on the Order object to return the number of transactions associated with a given order.

We've also added the authorizationExpiresAt field on the OrderTransaction object. The authorizationExpiresAt field is available only to stores on a Shopify Plus plan and is populated only for Shopify Payments authorizations.

We've added the customAttributes field on the LineItemGroup object, which allows you to query a list of attributes that represent custom features or special requests. A line item group is also known as a bundle.

Apps can now also do the following:

• Retrieve a bundle item's components on a draft order by using the bundleComponents field on the DraftOrderBundleLineItemComponentInput input object.
• Add a bundle item to a draft order by including the bundleComponents field on the draftOrderLineItemInput input object.

Additionally, the CartTransform function now automatically runs on all draft orders.

Learn more about bundles.

The following new types are available for creating and updating product bundles:

As of API version 2024-07, the variant image field in the PRODUCT_FEEDS_INCREMENTAL_SYNC and PRODUCT_FEEDS_FULL_SYNC webhook subscription topics won't return an image unless one has been set. Previously, the variant image field would return the product's first image when an image wasn't explicitly set for the variant.

If this change doesn't work for your use case, then you can replicate the old behavior by assigning the first product image to the variant.

The LINKED_METAFIELD_DEFINITION_NOT_FOUND value has been added to the ProductOptionUpdateUserErrorCode enum.

You can now use the sourceReference field on the DeliveryMethod object to return promise provider data associated with a delivery promise.

You can now use the published_at filter on the product query to determine the date and time when a product was published to the Online Store.

The following types now have a category field, which accepts the global ID (GID) of a taxonomy category that's specified by a merchant:

• ProductInput input object
• Shop object
• MetafieldReference union

We've also deprecated the allProductCategories field on the Shop object. Use the allProductCategoriesList field on the Shop object instead.

You can now use the includesTranslations field on the ProductDuplicateAsyncInput input object to specify whether to include translations when running the productDuplicateAsyncV2 mutation.

If includesTranslations is set to true, then all translations that are saved on the product, its variants, and its metafields are copied over to the new product.

We've removed several fields on product variants that are duplicates of linked inventory items. For a complete list of changes to the GraphQL Admin API, and to learn more about the types that you can use instead, refer to the developer changelog.

You can now use the files query to retrieve 3D models and external videos.

The following new types are available:

We've removed the following types and fields from the GraphQL Admin API:

You can now use the retailLocation field on the Order object to query the physical location where a retail order is created or completed.

You can now use the id field on the RefundLineItem object to return the global ID of the specified refund line item object.

Shopify's suggestion for a refund is now inclusive of payable charges, such as exchange items and fees, alongside returns.

The Return.suggestedRefund query and ReturnRefund mutation now have a different expectation on the refund amount. The refund amount considers exchange line items and fees on the return, as well as any outstanding amount owed by the buyer on an order. Previously, the refund amount logic only accounted for return line items.

As of API version 2024-07, the Return.returnLineItems connection is an interface type. This change is designed to accommodate more diverse return item types in the future, and provides more flexibility in handling returns.

To maintain compatibility with existing implementations, adjust your queries to use an inline fragment. The following adjustment ensures that queries continue to function correctly with the new interface type:

Metafields are now supported on the SellingPlan object.

The following new types are available:

You can now set metafields using compare-and-swap (CAS) with the compareDigest field on the metafieldsSet mutation. By using CAS, you can properly handle concurrency requests.

As of API version 2024-07, we're introducing a new MobilePlatformApplication type. This type facilitates the development and operational integration of shared web credentials and app link systems for Shopify mobile apps on both iOS and Android platforms.

The following new types are available:

You can now query the following new types related to Shopify Payments balance transactions:

We've deprecated the shopifyqlQuery query. Use the GraphQL Admin API instead to extract data for your use cases.

The following CustomerSortKeys are now deprecated:

• LAST_ORDER_DATE
• ORDERS_COUNT
• TOTAL_SPENT

You can order customers by these attributes if you filter customers using segments.

You can now use the StoreCreditAccount object to retrieve information about the monetary balance that can be redeemed at checkout for purchases in the store.

The productSet mutation now defaults to running synchronously unless the input parameter synchronous is set to false.

We've also increased the input limit on product variants to the existing asynchronous limit. API versions prior to 2024-07 had a limit of 100 variants. You should set synchronous to false if you need to consider input complexity / size, or are experiencing timeouts.

We've added 14 additional LocalizationExtensionsKey values to support the collection of tax and shipping credentials in several new countries.

You can now use the following metafield definition types to save link-related content:

• LINK: A link consisting of an anchor text and URL
• LIST_LINK: A list of link metafields

Learn more about metafields.

You can now use the validationResultSummary field on the MailingAddress object to query the validation status of a shipping address. Possible values are ERROR, WARNING, NO_ISSUES, and NULL. A NULL value indicates that the address has not undergone validation.

Learn more about how Shopify validates customer addresses.

The subTopic field has been removed from the WebhookSubscription object. Use the filter field instead.

We've added the following new webhook topics to the GraphQL Admin API:

The Shopify Payments Transactions resource now returns the adjustment_reason property to describe the reason an adjustment was made.

The Checkout resource is now deprecated. For more information, refer to the Developer changelog.

We've also deprecated all endpoints on the Country and Province resources. For a complete list of affected endpoints, and the GraphQL type equivalents to use instead, refer to the Developer changelog.

The following properties have been added to delivery_method property on the FulfillmentOrder resource:

• branded_promise: The branded promise that was presented to the customer during checkout. For example, "Shop Promise".
• additional_information: The additional information to consider when performing the delivery.
• service_code: A reference to the shipping method.
• source_reference: The promise provider data associated with delivery promise.

The orders/edited webhook payload now includes a committed_at field. You can use this field to identify when an edit to an order is finalized.

You can now use the cartBillingAddressUpdate mutation to associate a billing address with a cart.

The NOTE_TOO_LONG error code is now returned in cart mutations when a note exceeds the maximum limit of 5000 characters.

We've deprecated the following types:

• walletPreferences argument on the CartBuyerIdentityInput input object
• walletPreferences field on the CartBuyerIdentity object

Use CartBuyerIdentityInput.preferences.wallet instead.

We've removed checkout types from the Storefront API, following their deprecation in the 2024-04 API version.

For more information, refer to the developer changelog.

We've added the targetType field to the CartDiscountAllocation interface. The targetType field ensures comprehensive discount calculations, which are crucial for payment integrations.

You can now manage gift cards on a cart in the following ways:

• When creating a cart: Add the giftCardCodes field to the CartInput input object.
• After a cart is created: Run the cartGiftCardCodesUpdate mutation.
• Querying for applied gift cards: Use the appliedGiftCards field.

The following new types are available:

We've removed the following types and fields from the Storefront API:

You can now use the following types to manage Shop Pay payment request checkouts:

Carts now support single-use delivery addresses with the oneTimeUse field on the DeliveryAddressInput input object.

You can use the oneTimeUse field to pass a delivery address that shouldn't be saved to the customer's account after checkout. For example, you might want to use this field for one-time gifting purposes.

The HasMetafields interface is now available on the SellingPlan object associated with each Function API.

We've added the lines field to the FulfillmentGroup object. The lines field returns a list of cart lines containing information about the items that are part of the fulfillment group.

API clients installed on Shopify Plus stores can now make use of the optional placements argument in the hide operation. This allows you to explicitly hide payment methods from the accelerated checkout or payment selection.

Learn more about payment customization functions.

Previously, the PaymentCustomizationPaymentMethod object returned multiple payment methods with the name "Shopify Payments" when a store has wallets enabled through Shopify Payments (for example, Apple Pay or Google Pay). This made it impossible for app developers to target the credit card or a specific wallet option for hide, rename, or move operations.

To fix this issue, we've changed the name value for wallets to the following values:

The Product Discount API now supports CartLineTarget object, which enables you to apply discounts on specific cart lines. This functionality was historically only possible with Shopify Scripts.

You can use the CartLineTarget object to link discounts to attributed cart lines such as upsell products, free gifts with purchase, or buyer customized products.

You can now determine whether the financial status of an order is expired using the EXPIRED value on the OrderFinancialStatus enum.

You can now set metafields using compare-and-swap (CAS) with the compareDigest field on the metafieldsSet mutation. By using CAS, you can properly handle concurrency requests.

Customers who are authenticated with a customer account can now review and spend their store credit at checkout.

You can now use the metafieldsSet mutation to assign metafield values on Customer, Order, Company, and CompanyLocation objects.

As part of this change, the Customer Account API needs to be granted explicit read or read/write access to metafield definitions to have access to metafield values. This represents a breaking change because as of API version 2024-07, metafield definitions without access permissions will not be available to the Customer Account API.