Shopify Developers Release Notes

Introducing the orders/link_requested webhook topic

As of API version 2026-01 of the GraphQL Admin API, your app can subscribe to the orders/link_requested webhook topic.

This webhook is triggered when a customer requests a new order link from the expired Order status page. This allows your app to be notified when customers need to access their order details after their original order link has expired.

The webhook is triggered when: A customer visits an expired order status page and requests a new order link.

Payload: The webhook delivers the full Order object, which includes:

• Order ID and details
• Customer information
• Order status
• Fulfillment information

Find more information and view the full payload in the Shopify dev docs.

You can now use the new Return Reason Definition type to capture more granular, category-specific return reasons when managing returns. This replaces the previous Return Reason enum with a richer data model that helps provide merchants with better insights in their return analytics, and more tailored return experiences for their buyers.

What's new
■ A new Return Reason Definition type with id, handle, and name fields. Use the stable handle for programmatic logic.
■ The return Reason Definitions query retrieves the full library of available return reasons.
■ A new suggested Return Reason Definitions connection on Line Item provides return reasons tailored to each product's category.
■ The return Create, return Request, and order Request Return mutations now accept return Reason Definition Id in their line item inputs.
■ Access return Reason Definition on Return Line Item and Unverified Return Line Item types.

Deprecations
The return Reason field on input types and return line item types is deprecated. Use return Reason Definition Id for inputs and return Reason Definition for reading return data.

Migration
If your app creates returns, update your mutations to use return Reason Definition Id instead of return Reason. Query suggested Return Reason Definitions on Line Item to get contextually relevant reasons for each product. For reading returns, update your queries to use return Reason Definition instead of return Reason.

These changes are available in API version 2026-01.

What's New

Tax calculation request payloads now feature a new merchant_business_entity field at the root level of the request. This field includes the following details:

• id: The global ID of the business entity (format: gid://shopify/BusinessEntity/{id})
• company_name: The legal name of the business entity
• display_name: The display name of the business entity
• address: The business entity's address, including:
  • Province
  • Address lines (address1, address2)
  • City
  • Zip code

Structure

Before (2026-01):

{
  "shop": { ... },
  "cart": { ... },
  "currency_code": "USD",
  "session_id": "session_123"
}

After (2026-01):

{
  "shop": { ... },
  "cart": { ... },
  "currency_code": "USD",
  "session_id": "session_123",
  "merchant_business_entity": {
    "id": "gid://shopify/BusinessEntity/456",
    "company_name": "Test Company",
    "display_name": "Test Display",
    "address": {
      "country": "US",
      "province": "CA",
      "address1": "123 Main St",
      "address2": "Suite 100",
      "city": "San Francisco",
      "zip": "94102"
    }
  }
}

As of API version 2026-01, the tax_summaries/create webhook for Tax Partner Apps now include merchant business entity information. This addition provides details about the legal entity responsible for transactions, which is crucial for accurate tax calculation.

What's New

The tax webhook payload now feature a new merchant_business_entity field at the root level of the tax summary. This field includes the following details:

• id: The global ID of the business entity (format: gid://shopify/BusinessEntity/{id})
• company_name: The legal name of the business entity
• display_name: The display name of the business entity
• address: The business entity's address, including:
  • Country
  • Province
  • Address lines
  • City
  • Zip code
  • Company name

This field is optional and will only be present when the merchant has configured a legal business entity for their shop.

Structure

Before (2026-01):

{
  "summary": {
    "idempotent_key": "abc123",
    "shop": { ... },
    "order_details": { ... }
  }
}

After (2026-01):

{
  "summary": {
    "idempotent_key": "abc123",
    "shop": { ... },
    "order_details": { ... },
    "merchant_business_entity": {
      "id": "gid://shopify/BusinessEntity/12345",
      "company_name": "Acme Corporation",
      "display_name": "Acme Corp",
      "address": {
        "country": "CA",
        "province": "ON",
        "address1": "123 Main St",
        "city": "Toronto",
        "zip": "M5V 2T6",
        "company": "Acme Corporation"
      }
    }
  }
}

As of API version 2026-01, tax calculation requests for Tax Partner Apps can now include cart line item properties. These properties are custom name-value pairs that merchants can add to individual line items.

Tax Partner Apps can now receive line item properties in tax calculation requests by configuring which property keys they want to receive.

Property Configuration

• Merchants configure properties on individual cart line items (e.g., "token", "personalization", "gift_wrap")
• Tax Partner Apps specify which property keys they want to receive across all line items (maximum 5 keys)
• Only the requested property keys are included in calculation requests

How It Works: Per-Line-Item Properties

The 5-key limit applies to which property keys the partner wants to receive, not the number of line items:

• Partner configures: ["token", "personalization"] (2 keys)
• Cart has: 10 line items
• Result: All 10 line items will include their own token and personalization values (if present)

Request Payload Changes

Cart line items in the delivery_groups[].cart_lines[] objects now include an optional properties field per line item:

Before (2026-01):

{
  "delivery_groups": [{
    "cart_lines": [{
      "id": "gid://shopify/CartLine/123",
      "quantity": 1,
      "merchandise": {
        "id": "gid://shopify/ProductVariant/456",
        "title": "Custom T-Shirt"
      },
      "cost": {
        "amount_per_quantity": {
          "currency_code": "USD",
          "amount": "25.00"
        }
      }
    }]
  }]
}

After (2026-01):

{
  "delivery_groups": [{
    "cart_lines": [
      {
        "id": "gid://shopify/CartLine/7",
        "quantity": 1,
        "merchandise": {
          "id": "gid://shopify/ProductVariant/456",
          "title": "Custom T-Shirt"
        },
        "cost": {
          "amount_per_quantity": {
            "currency_code": "USD",
            "amount": "25.00"
          }
        },
        "properties": {
          "token": "abc-123",
          "personalization": "John Smith"
        }
      },
      {
        "id": "gid://shopify/CartLine/6",
        "quantity": 2,
        "merchandise": {
          "id": "gid://shopify/ProductVariant/789",
          "title": "Custom Mug"
        },
        "cost": {
          "amount_per_quantity": {
            "currency_code": "USD",
            "amount": "15.00"
          }
        },
        "properties": {
          "token": "def-456",
          "personalization": "Jane Doe"
        }
      }
    ]
  }]
}

Deprecation of Shop.billingAddress in favor of Shop.shopAddress

As of API version 2026-01, the shopAddress field will be introduced to the Shop object in the GraphQL Admin API. This new field replaces the now-deprecated billingAddress field, which will be removed in a future version. shopAddress will have identical structure and values as billingAddress.

Billing account address currently corresponds to the shop address. This change makes that relationship clearer, and supports potential future separation of billing and shop addresses.

Action required

You should update your queries to use the new shopAddress field when accessing the Shop object in the GraphQL Admin API. Replace instances of shop { billingAddress { ... } } with shop { shopAddress { ... } }.

For example, update your query from:

query ShopAddress {
  shop {
    billingAddress {
      address1
      address2
      city
      province
      zip
      country
    }
  }
}

to:

query ShopAddress {
  shop {
    shopAddress {
      address1
      address2
      city
      province
      zip
      country
    }
  }
}

By making these changes, you ensure compatibility with future API versions.

As of API version 2026-01

The Storefront API returns a GIFT_CARD_RECIPIENT_INVALID error when adding a gift card to a cart with missing or invalid recipient details, such as in this example.

Previously, when adding a gift card to a cart using either the cartCreate or cartLinesAdd mutations, an empty cart and empty userErrors would be returned if any of the recipient details were invalid, such as a missing email address. With this change a GIFT_CARD_RECIPIENT_INVALID error is returned for both cartCreate or cartLinesAdd mutations, so that you can use the information to surface gift card recipient errors back to the client.