Skip to main content
Crossmint’s Headless Checkout now supports purchasing physical products using a wallet’s crypto balance through the productLocator parameter. This guide explains how to integrate physical product purchases and handle shipping requirements.

​
Physical Address Requirement

When purchasing physical products, a shipping address is required (currently only US addresses are supported). You can provide this in two ways:

​
1. Include Address During Order Creation

POST /api/2022-06-09/orders
{
    "recipient": {
        "email": "buyer@example.com",
        "physicalAddress": {
            "name": "John Doe", // required
            "line1": "123 Main St", // required
            "line2": "Apt 4B", // optional
            "city": "San Francisco", // required
            "state": "CA", // required for US addresses
            "postalCode": "94105", // required
            "country": "US" // required - only US is currently supported
        }
    }
}

​
2. Update Address After Order Creation

If you create an order without specifying a physicalAddress, the quote cannot proceed until a valid shipping address is provided. See the full list of statuses on the Status Codes page. To resolve this, update the order with the physical address: 
PATCH /api/2022-06-09/orders/{orderId}
{
  "recipient": {
    "physicalAddress": {
      "name": "John Doe",      // required
      "line1": "123 Main St",  // required
      "line2": "Apt 4B",       // optional
      "city": "San Francisco", // required
      "state": "CA",           // required for US addresses
      "postalCode": "94105",   // required
      "country": "US"          // required - only US is currently supported
    }
  }
}
After providing the physical address, the order status will update and include the necessary payment.preparation parameters to proceed with payment.

​
Order Status Handling

When purchasing physical products, provide a shipping address up front or update the order after creation. Until a valid address is present, the order cannot proceed to payment preparation. For the complete, authoritative list of statuses and their meanings, see the Status Codes page.

​
Supported Providers

​
Amazon

Amazon products can be purchased using either their ASIN or product URL. See the Amazon Integration Guide for details.

​
Shopify

Shopify products can be purchased using the product URL and variant ID. See the Shopify Integration Guide for details.