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 Type | Prefix | Usage |
|---|
| Secret Key | sk_test_* / sk_live_* | Server-side only. Full API access. |
| Publishable Key | pk_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"
{
"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": "[email protected]",
"payment_provider": "stripe",
"payment_method_id": "pm_xxx"
}'
Next Steps
