Shopify Integration

How to enable crypto purchases of Shopify products using Headless Checkout

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": "[e-mail]",
    "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.