The shipping and billing address forms in checkout can now have street name, street number, and neighborhood fields, allowing merchants to collect address data in regionally-accepted formats. The fields that are available depend on the country selected at checkout and if a merchant has additional address fields enabled. You can review the supported countries in the help documentation.

The fields are now available for developers to test with as part of the Checkout Extensibility developer preview. The change will be rolling out to merchants in the coming weeks.

Learn how to make use of this data on Shopify.dev.

We are removing the "All count name are in your cart." error response in favour of the exisiting "You can't add more name to the cart." error response in the Cart Ajax API.

Old behaviour: - When all inventory of a variant are already in the cart and the client requests to add more of that variant to the cart, the error response description is "All count name are in your cart.", and the message is "Cart Error". - When some of the inventory of a variant is in the cart and the client requests to add more of that variant to the cart, so that the total amount in the cart is more than the available inventory, the error response description and message is "You can't add more name to the cart."

New behaviour: - When the client requests to add more than available inventory of a variant already in the cart the error response description and message is "You can't add more name to the cart."

This will affect the update.js, change.js, and add.js endpoints.

We are rolling out changes to CAPTCHA on the following forms on Storefronts:

• Customer Login
• Customer Account Creation
• Reset Password
• Contact Form
• Newsletter Signup
• Blog Comments

The changes include:

1. Migration from Google reCAPTCHA to hCaptcha

We are migrating our CAPTCHA solution to hCaptcha as part of an ongoing effort to reduce form spam. This is an ongoing, phased, rollout, and does not affect our published methods for you to work with CAPTCHA.

2. Alternative methods to bind CAPTCHA to forms

You can now force CAPTCHA wireup to Storefront forms using either declarative markup or JavaScript. This is primarily intended for App/Theme developers who wish to take control of Form submission, for example by constructing hidden forms that POST to Shopify. See the documentation for further information and examples.

3. Strict CAPTCHA validation on form submissions

Previously, forms submitted from Storefronts that contained an invalid or missing CAPTCHA token would redirect to /challenge for the user to solve an interactive CAPTCHA. Such form submissions will now cause a 400 error. Theme and App authors who submit forms to Shopify are strongly encouraged to ensure that their forms work with CAPTCHA enabled, by submitting a valid CAPTCHA without relying on the redirect to /challenge

Orders with multiple shipping lines may be refunded. You can refund shipping amounts using the refundCreate GraphQL mutation, the returnRefund GraphQL mutation, or the Refunds REST API.

As of July 18, 2024, all Admin GraphQL API versions return accurate refunds data for orders with multiple shipping lines.

1. Shipping refunds will be included in the refundShippingLines connection, in addition to shipping lines removed via an order edit.
2. For each refunded shipping line, there will be an OrderAdjustment with kind SHIPPING_REFUND. Previously, there would be a single OrderAdjustment with kind SHIPPING_REFUND regardless of how many shipping lines were present on the order.
3. The RefundAgreement has multiple shipping line sales. Each ShippingLineSale corresponds to exactly one shipping line that was refunded. The ShippingLineSale.shippingLine is now populated for all API versions for the RETURN action type.

As of July 18, 2024, all REST API versions return accurate refunds data for orders with multiple shipping lines.

1. For each refunded shipping line, there will be an order adjustment with kind = shipping_refund in the order_adjustments property. Previously, there would be a single order adjustment with kind = shipping_refund, regardless of how many shipping lines were present on the order.

Please note that Refund.refundShippingLines and RefundAgreement.sales are only available in the Admin GraphQL API. They are not present in the Admin REST API.

In the version 2024-10 release of the Admin GraphQL API, we are making the following changes in the product delete APIs

• The productDeleteAsync mutation will be removed.
• A new synchronous boolean parameter will be added to the productDelete mutation, allowing you to choose whether the product deletion should be processed synchronously or asynchronously.

Key Updates:

• Asynchronous Deletion: By setting the synchronous parameter to false in the productDelete mutation, the operation will proceed asynchronously, returning a ProductDeleteOperation object.
• Operation Tracking: You can track the status of the asynchronous deletion by querying the operation ID through the ProductOperation query.

For more detailed information and examples, visit our ProductDelete documentation on Shopify.dev.

In the version 2024-10 release of the Admin GraphQL API, we are making the following changes in the product duplicate APIs:

The productDuplicateAsyncV2 mutation will be removed.

A new synchronous boolean parameter will be added to the productDuplicate mutation, allowing you to choose whether the product duplication should be processed synchronously or asynchronously.

Key Updates:

Asynchronous Duplication: By setting the synchronous parameter to false in the productDuplicate mutation, the operation will be performed asynchronously, returning a ProductDuplicateOperation object.

Operation Tracking: You can track the status of the asynchronous duplication by querying the operation ID through the ProductOperation query.

For more detailed information and examples, visit our productDuplicate documentation on Shopify.dev.

As of GraphQL Admin API version 2024-10 we're deprecating several singular variant mutations in favor of their bulk version, namely: * productVariantCreate. Use the productVariantsBulkCreate instead. * productVariantUpdate. Use the productVariantsBulkUpdate instead. * productVariantDelete. Use the productVariantsBulkDelete instead.

As of Juy 16th, the structured_data filter outputs product information using the ProductGroup schema.org type, according to the latest recommendations from Google.

As of the GraphQL Admin API version 2024-10, we're deprecating the GREATER_THAN_ZERO and INVALID_LINE_ITEM_QUANTITY error codes on the fulfillmentOrderReleaseHold mutation. These error codes are no longer returned by the mutation.

Hydrogen v2024.7.1 is out today. The July 2024 Hydrogen release contains several new features and bug fixes, including:

• A new useOptimisticVariant hook
• sellingPlanId support for <BuyNowButton />
• New customer account session commit pattern (breaking)
• <VariantSelector /> improved handling of options (breaking)
• Update Remix to 2.10.0 which included fixes to infinite loading error
• Type fixes for optimistic cart
• CLI: Vite bundle analyzer
• CLI: Support CSS options in Vite projects

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

We have introduced a new field, Product.restrictedForResource, which allows you to query product restrictions for a given CalculatedOrder resource. This field returns both the restricted status and the reason for the restriction.

Currently, this feature supports checking for Managed Markets product restriction. You can use this field to determine if a product can be added to a CalculatedOrder during the order edit mutation process.

The achievements section of the Distribution page in Partners Dashboard will be removed as of today. You will not lose the ability to see the status of your achievements as they are available in other places on the page.

You can see your Built for Shopify status in the same card above where the Achievement section was located.

You can see your highlight achievement status in the Technical criteria checklist section below.

As of 2024-10, the CartTransform create mutation will support metafields as an argument.

The new metafields argument for cartTransformCreate allows for metafields to be set for the CartTransform at creation without the need to call metafieldsSet in a subsequent call.

Learn more about the CartTransform API.

In the 2024-07 API version of checkout UI extensions, we have introduced a new instructions API. This API will inform checkout UI extensions when a particular extension API is/is not available for the current checkout. For example, if you intend to add a discount code via the applyDiscountCodeChange method, check discounts.canUpdateDiscountCodes to ensure it's supported in this checkout.

All checkout UI extensions updating to 2024-07 will be expected to review the list of APIs that may be restricted, and incorperate fail-safes if a particular API is not available in the current checkout. This will be required for checkout UI extensions to start rendering in draft order invoice checkouts.

For more details, please refer to our 2024-07 update guide for more details and instructions on how to safely update to 2024-07.

As of GraphQL Admin API version 2024-07, you can now set and query a customer's data sale / sharing opt out status. This allows customers to be opted out of data sale / sharing in support of compliance with US state laws like CCPA/CPRA. The Admin API now includes the following updates: * Set dataSaleOptOut: Set the data sale / sharing opt out status of a customer * Query dataSaleOptOut: Query the data sale / sharing opt out status of a customer

To learn more about data sale / sharing opt-outs, refer to the Shopify Help Center and the Customer Privacy API.

As of the 2024-07 release of the GraphQL Admin API, a new error code LEDGER_DOCUMENT_INVALID will be added to the potential errors for the InventorySetScheduledChanges mutation. This error code will be returned when the ledgerDocumentUri provided is not a valid URI.

As of 2024-07, you can use the Order.transactionsCount to return the number of transactions associated with a given order.

As of 2024-07, you can use the fileUpdate mutation to connect files to products.

Learn more about working with files on Shopify.dev.

As of 2024-07, a ProductVariant connection will be added to the FulfillmentOrderLineItem object in GraphQL.

This will allow order management apps to easily 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 here.

As of GraphQL Admin API version 2024-07, you can now set available and on hand quantities for inventory via the new inventorySetQuantities graphql mutation. At the same time, the inventorySetOnHandQuantities mutation will be deprecated.

As of 2024-07 version, SellingPlan resources support metafields. Use metafields APIs to store additional information in metafield values.

You can use the sellingPlanGroupCreate mutation and sellingPlanGroupUpdate mutation to update and create metafields on the selling plan objects by specifiying the metafields field of sellingPlanInput.

To learn more about metafields, refer to the metafields documentation.

• As of GraphQL Admin API version 2024-07, the Product Set mutation will default to running synchronously unless the input parameter synchronous is set to false.
• As of GraphQL Admin API version 2024-07, the input limit on variants has been increased to the existing asynchronous limit. Versions prior to 2024-07 had a limit of 100 variants. Setting synchronous: false may be desirable depending on the input complexity/size, and should be used if you are experiencing timeouts.

As of 2024-07, the product create and update webhook payload contains information about the media on a product.

Using media GIDs allows compatibility with GraphQL Admin API mutations such as https://shopify.dev/docs/api/admin-graphql/2024-07/mutations/fileupdate and https://shopify.dev/docs/api/admin-graphql/2024-07/mutations/productupdatemedia

To receive media in the webhook payload, specify 2024-07 or greater as the webhook API version.

Stay informed with the latest enhancement to our orders/edited webhook payload! As of 2024-07, the webhook payload exposes the timestamp an order edit was committed at.

With this new attribute, you can precisely identify when an edit to an order is finalized, adding a new layer of clarity that was previously missing: created_at represents when the order edit was created, but not when it was persisted to the order.

We understand that navigating through multiple order changes can be daunting and are confident that the inclusion of committed_at will make a significant difference.

To receive this new attribute in the webhook payload, specify 2024-07 or greater as the webhook API version. You can find more details about the webhook here: Orders Edited Webhook Documentation.

As of 2024-07, we've added APIs for viewing and filtering conditional metafield definitions such as product attributes: * Use the constraints field on MetafieldDefinition to view the metafield definition's constraints. * Use the constraintSubtype argument on the metafieldDefinitions and standardMetafieldDefinitionTemplates queries to retrieve only metafield definitions that apply to the passed constraint subtype. * Use the constraintStatus argument on the metafieldDefinitions and standardMetafieldDefinitionTemplates queries to filter based on whether the metafield definitions are constrained.

Learn more about conditional metafields

As of 2024-07 in the GraphQL Admin API, you can use new return APIs to interact with exchange primitives.

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. Note that canceling a return does affect the fulfillment of exchange items. Read more on how exchanges are processed here.

The returnLineItemRemoveFromReturn mutation is now available to remove return lines from a return. With returns creating sales, removing a return line from a return will also reversely impact return sales.

The returnCalculate query is now available to calculate financials before return creation, including inputs for return lines, exchange lines, fees and discounts. Learn more about how to use this query in our dev docs.

As of 2024-07 in the GraphQL Admin API, Shopify’s suggestion for refund is inclusive of payable charges, such as exchange items and fees, alongside returns.

The Return.suggestedRefund query and ReturnRefund mutation APIs will 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.

This affects the logic for 2024-07 versions and onwards, the logic for previous API versions will continue to only account for return line items.

Here is an example for an order with a return for an item worth $50.99 CAD and a return fee of $5 CAD, given this suggested return refund query:

query {
  return(id: "exampleReturn/1") {
    suggestedRefund(
      returnRefundLineItem: [
        {
          returnLineItemId: "exampleReturnLineItem/1"
          quantity: 1
        }
      ]
    ) {
      amount {
        shopMoney {
          amount
          currencyCode
        }
      }
    }
  }
}

Result with previous behavior

{
  "data": {
    "return": {
      "suggestedRefund": {
        "amount": {
          "shopMoney": {
            "amount": "50.99",
            "currencyCode": "CAD"
          }
        }
      }  
    }
  }
}

Result with new behavior:

{
  "data": {
    "return": {
      "suggestedRefund": {
        "amount": {
          "shopMoney": {
            "amount": "45.99",
            "currencyCode": "CAD"
          }
        }
      }  
    }
  }
}

Note that if the return fee was greater than $50.99 CAD, the suggested amount cannot be lower than $0 CAD.

As of the 2024-07 release of the GraphQL Admin API, the location object will be gated by the read_locations scope. Attempting to read the location object without the read_locations access scope will return an access denied error.

As of API Version 2024-07, the Product Discount Function API now supports a new target type: CartLineTarget, allowing for the application of discounts on specific cart lines, a use case that has historically only been possible with Shopify Scripts. This update can be used to link discounts to attributed cart lines such as upsell products, free gifts with purchase, or buyer customized products. You can learn more about the Product Discount Function API here.

Starting in version 2024-07, the Return.returnLineItems connection becomes an interface type. This change is designed to accommodate more diverse return item types in the future, which will increase your flexibility in handling returns.

To maintain compatibility with existing implementations, adjust their queries to use an inline fragment, as shown in the example below. This adjustment ensures that queries will continue to function correctly with the new interface type.

returnLineItems(first: 30) {
  edges {
    cursor
    node {
      ... on ReturnLineItem {
        id
        ...ReturnLineItemAttributes
      }
    }
  }
}

As of GraphQL Storefront API version 2024-07, you can query bundles components and bundle parents on ProductVariant object.

This API change introduce three new fields on the ProductVariant object:

1. requiresComponents - A boolean field which is set to true when the variant can only be purchased as a parent bundle with components.
2. components - List of bundles components included in the variant considering only fixed bundles.
3. groupedBy - List of bundles that include this variant considering only fixed bundles.

Learn more about Bundles on Shopify.dev.

As of GraphQL Admin API version 2024-07, you can create fixed bundles using our new coarse-grained API.

This API change introduces the following new mutations:

1. productBundleCreate mutation
2. productBundleUpdate mutation

Learn more about Bundles on Shopify.dev.

As of 2024-07, Cart#deliveryGroups supports a new withCarrierRates argument, used to indicate intent to fetch carrier-calculated rates. This capability requires mandatory use of @defer directive, which ensures that the cart response is not blocked on calculating rates.

Test out the carrier-calculated rates on the cart today by following our tutorial. We value your input, please share your feedback on Github.

As of version 2024-07 of the Admin GraphQL API, we're adding 14 new LocalizationExtensionsKey values to support the collection of tax / shipping credentials in several new countries.

Learn more about LocalizationExtensionKeys on Shopify.dev.

Changelog: Deprecation Notice for Country and Province Endpoints

Version: 2024-07

As of the 2024-07 release of the GraphQL Admin API, 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 on Shopify.dev.

We are introducing updates to our API that will enhance your experience and provide you with more flexibility:

1. Support for Query Arguments on Payouts GraphQL Field:

   • You can now utilize 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.

2. Addition of Missing Attributes to ShopifyPaymentsBalanceTransaction GraphQL Object:

   • We have enriched the ShopifyPaymentsBalanceTransaction GraphQL object by introducing the following attributes:
     • source_id: Represents the ID of the resource that led to the transaction.
     • source_order_transaction_id: Indicates the ID of the Order Transaction that triggered the balance transaction. If the source_type is an adjustment, this value will be null.
     • adjustment_order_transactions: An array of associated order transactions that resulted in the balance transaction. If the source_type is not an adjustment, this array will be null. Each object in the array includes:
     • adjustment_reason: Specifies the reason for the adjustment associated with the transaction. If the source_type is not an adjustment, this value will be null.

As of GraphQL Admin API version 2024-07 you can query the following fields on the ShopifyPaymentsBalanceTransaction object: - description - amount - fee - source_type - type - associated_order - associated_payout - test

Learn more about ShopifyPaymentsBalanceTransaction on Shopify.dev.

As of API version 2024-07, you can use the webhookSubscriptionsCount field to return a count of webhook subscriptions. This field returns a Count object type with precision and count fields.

As of API version 2024-07 of the GraphQL Admin API, your app can subscribe to the customer_account_settings/update webhook topic.

This webhook is triggered when a merchant changes customer account settings.

For example, if a merchant chooses new customer account, requires login on checkout and shows login link on online store, the payload in the webhook will look like:

{
 url: 'https://shopify.com/1234567890/account',
 customer_accounts_version: 'new_customer_accounts',
 login_required_at_checkout: true,
 login_links_visible_on_storefront_and_checkout: true
}

If a merchant chooses classic customer account, does not require login on checkout and does not show login link on online store, the payload in the webhook will look like:

{
 url: null,
 customer_accounts_version: 'classic',
 login_required_at_checkout: false,
 login_links_visible_on_storefront_and_checkout: false
}

Learn more about these webhooks on Shopify.dev

As of version 2024-07, the HTTP Post request sent from Shopify to initiate a payment session on a Credit Card Payments App Extension contains a new Boolean moto field in the payment_method.data hash, to flag if the credit card information for a payment was entered by a merchant. Learn more about payment session creation on Shopify.dev.

As of 2024-07, you can use the validationResultSummary field on the mailingAddress type to query the validation status of an order's shipping address.

Possible values defined in MailingAddressValidationResult enumerated type with possible values of 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 at help.shopify.com

As of version 2024-07 in the GraphQL Admin API, the discountedPriceSet and discountedPrice fields of the object ShippingLine will include cart level discounts applied to an order, including the free shipping discount, when calculating the discounted price. Previously, you would have had to subtract the discountAllocations from discountedPriceSet or discountedPrice to get an accurate value, but doing so now will subtract the same discount twice.

Learn more about Shipping Lines on Shopify.dev.

As of version 2024-07 of the Admin GraphQL API we are introducing the following changes: * We’ve added active, supportsServiceDiscovery, and callbackUrl fields to the DeliveryCarrierService object. * We’ve added carrierServices to the query root to list and filter the carriers services of the shop. * We’ve added carrierServiceCreate to create a new DeliveryCarrierService. * We’ve added carrierServiceUpdate to update the properties of a DeliveryCarrierService. * We’ve added carrierServiceDelete to delete a DeliveryCarrierService.

As of version 2024-07 of the Admin GraphQL API, you can use the new createdAt field in FulfillmentEvent to check the date and time when the fulfillment event was created.

Learn more about FulfillmentEvent on Shopify.dev.

As of version 2024-07 of the Admin GraphQL API, you can use the new fulfillmentsCount field in Order to count the number of fulfillments including the cancelled fulfillments that belong to an order.

Learn more about Fulfillment on Shopify.dev.

We're deprecating the TRANSPARENT value on the CheckoutBrandingBackground enum of the Admin GraphQL API checkoutBranding query and checkoutBrandingUpsert mutation. Use BASE or SUBDUED instead.

We will remove this value from the mutation input and the GraphQL API in the subsequent API version (2024-07). To prepare for the 2024-07 API version release, stop using the TRANSPARENT value.

As of the 2024-07 version of the Customer Account API, you will be able to use the metafieldsSet mutation to assign metafield values on Customer, Order, Company, and CompanyLocation resources.

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

The 2024-07 version of the Admin API will allow you to set access controls as part of the metafieldDefinitionCreate and metafieldDefinitionUpdate mutations.

These changes can be tested today on the unstable versions of the Customer Account and Admin APIs.

As of 2024-07 StoreCreditAccount queries and mutations are available to merchants globally in the GraphQL Admin API. A new transactions connection has been added to the StoreCreditAccount, displaying the full transaction history of the account.

A customer who is authenticated with new customer accounts will be able to see and spend their store credit at checkout.

It's now possible to view the logged in customers StoreCreditAccount when using the GraphQL Customer Account API.

As of GraphQL Admin API version 2024-07, the following Customer filters in the search syntax have been deprecated: total_spent, orders_count, accepts_marketing, customer_date, last_abandoned_order_date, order_date, tag, tag_not, city, province, state, territory_code, country, company, email_marketing_state, sms_marketing_state. Filtering customers by these attributes is available when querying customers using segments.

Learn more about customer segmentation on Shopify.dev.