Skip to main content

​
Quickstart

This guide walks you through making your first API requests.

​
Prerequisites

  • A Headless Commerce account with API keys
  • curl or any HTTP client

​
Step 1: Get Your API Keys

After creating a store in the dashboard, you will receive two types of keys:
Key TypePrefixUsage
Secret Keysk_test_* / sk_live_*Server-side only. Full API access.
Publishable Keypk_test_* / pk_live_*Client-side safe. Storefront API only.
Never expose secret keys in client-side code. Use publishable keys for browser and mobile applications.

​
Step 2: List Products

Fetch active products from the Storefront API: 
curl https://api.headlesscommerce.io/v1/storefront/products \
  -H "Authorization: Bearer pk_test_your_key_here"
Response
{
  "data": [
    {
      "id": "prod_abc123",
      "name": "Classic T-Shirt",
      "status": "active",
      "type": "physical",
      "variants": [...]
    }
  ],
  "has_more": false,
  "next_cursor": null
}

​
Step 3: Create a Cart

curl -X POST https://api.headlesscommerce.io/v1/storefront/carts \
  -H "Authorization: Bearer pk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"session_id": "guest-session-123"}'

​
Step 4: Add an Item

curl -X POST https://api.headlesscommerce.io/v1/storefront/carts/{cart_id}/items \
  -H "Authorization: Bearer pk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"variant_id": "var_xxx", "quantity": 1}'

​
Step 5: Checkout

curl -X POST https://api.headlesscommerce.io/v1/storefront/carts/{cart_id}/checkout \
  -H "Authorization: Bearer pk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "payment_provider": "stripe",
    "payment_method_id": "pm_xxx"
  }'

​
Next Steps