This guide explains how to integrate Shopify product purchases using the Headless Checkout API.

​
Product Locator Format

When creating an order for a Shopify product, use the productLocator parameter with the Shopify product URL and variant ID:

{
    "lineItems": [
        {
            "productLocator": "shopify:https://www.gymshark.com/products/gymshark-arrival-5-shorts-black-ss22:39786362601674"
        }
    ]
}

The format for the product locator is shopify:<product-url>:<variant-id>, where:

  • shopify: is the prefix identifying this as a Shopify product
  • <product-url> is the full URL to the product page
  • <variant-id> is the unique variant ID for the specific product option (size, color, etc.)

​
Example Flow

1

Create the order

  • Specify the recipient’s email
  • Specify their shipping information
  • Specify the payment method used
  • Specify the product locator

For a full list of supported currencies, refer to the supported currencies page.

POST /api/2022-06-09/orders
{
  "recipient": {
    "email": "buyer@example.com",
    "physicalAddress": {
      "name": "John Doe",      // required
      "line1": "123 Main St",  // required
      "city": "San Francisco", // required
      "state": "CA",           // required for US addresses
      "postalCode": "94105",   // required
      "country": "US"          // required - only US is currently supported
    }
  },
  "payment": {
    "method": "ethereum-sepolia",
    "currency": "eth"
  },
  "lineItems": [
    {
      "productLocator": "shopify:https://www.gymshark.com/products/gymshark-arrival-5-shorts-black-ss22:39786362601674"
    }
  ]
}
2

Check order status

With all required information provided, the order’s response will include payment preparation details, as shown below.

{
    "order": {
        "orderId": "...",
        "quote": {
            "status": "valid",
            ...
        },
        "payment": {
            "preparation": {
                ...  // Payment details will be present here
            }
        }
    }
}

​
Additional Information

  • Monitor order statuses through the Developer Console
  • Review the Order Lifecycle guide for detailed status handling
  • Check this guide for details on supported currencies and payment methods
  • Note: Delivery destinations are limited to regions supported by the Shopify store itself. The ability to ship to a specific address depends on the merchant’s shipping configuration.