# Harmon Storefront API - Full Documentation

> Build your own ecommerce storefront on Harmon - the public, machine-authenticated commerce API for your store.

This file concatenates every documentation page as Markdown, in reading order, so an assistant can ingest the entire portal in a single fetch. The machine-readable API contract lives at https://developers.harmoncommerce.com/openapi.json.

---

# Harmon Storefront API

Source: https://developers.harmoncommerce.com/

> New here? Start with the **[Quickstart](/quickstart)** - your first API call in five minutes -
> then browse the **[Guides](/guides/)**. The interactive API reference and the recipes cookbook
> arrive in later phases.

---

# Quickstart

Source: https://developers.harmoncommerce.com/quickstart

<script setup>
// Phase 3.2 / 3.5: the same calls shown across the Phase-0 language set
// (cURL · JavaScript · Python · PHP/Laravel) via the reusable CodeTabs block.
// Keys are obvious sandbox placeholders (hk_test_…, Invariant 4/5) - a reader
// pastes their own; nothing here is a real secret. The host comes from the one
// source of truth so it never drifts (theme/config.ts → page-source.mjs).
import { API_HOST as HOST } from './.vitepress/theme/config';

const ping = [
  {
    label: 'cURL',
    lang: 'bash',
    code: `curl -s ${HOST}/v1/ping \\
  -H "Authorization: Bearer hk_test_pub_your_key_here"`,
  },
  {
    label: 'JavaScript',
    lang: 'js',
    code: `const res = await fetch("${HOST}/v1/ping", {
  headers: { Authorization: "Bearer hk_test_pub_your_key_here" },
});
console.log(await res.json());`,
  },
  {
    label: 'Python',
    lang: 'python',
    code: `import requests

res = requests.get(
    "${HOST}/v1/ping",
    headers={"Authorization": "Bearer hk_test_pub_your_key_here"},
)
print(res.json())`,
  },
  {
    label: 'PHP / Laravel',
    lang: 'php',
    code: `use Illuminate\\Support\\Facades\\Http;

$res = Http::withToken('hk_test_pub_your_key_here')
    ->get('${HOST}/v1/ping');

dd($res->json());`,
  },
];

const products = [
  {
    label: 'cURL',
    lang: 'bash',
    code: `curl -s "${HOST}/v1/products?limit=5" \\
  -H "Authorization: Bearer hk_test_pub_your_key_here"`,
  },
  {
    label: 'JavaScript',
    lang: 'js',
    code: `const res = await fetch("${HOST}/v1/products?limit=5", {
  headers: { Authorization: "Bearer hk_test_pub_your_key_here" },
});
const { items } = await res.json();
console.log(items);`,
  },
  {
    label: 'Python',
    lang: 'python',
    code: `import requests

res = requests.get(
    "${HOST}/v1/products",
    params={"limit": 5},
    headers={"Authorization": "Bearer hk_test_pub_your_key_here"},
)
print(res.json()["items"])`,
  },
  {
    label: 'PHP / Laravel',
    lang: 'php',
    code: `use Illuminate\\Support\\Facades\\Http;

$res = Http::withToken('hk_test_pub_your_key_here')
    ->get('${HOST}/v1/products', ['limit' => 5]);

dd($res->json()['items']);`,
  },
];
</script>


Your first API call in **five minutes**: get a key, confirm it's wired, then read
the catalog. Every snippet is copy-paste-runnable - paste your sandbox key and
go. You never send a store or account id; your key identifies your store.

## 1. Get a sandbox key

Create a **publishable** key on the **API keys** screen. For exploring, start
with a **sandbox** key - it has the `hk_test_` prefix and can never touch live
data.

<GetKeysButton label="Get your API keys" />

> A **publishable** key (`hk_*_pub_…`) is browser-safe and authorizes anonymous
> catalog reads. A **secret** key (`hk_*_sec_…`) is server-side only and unlocks
> customer-scoped reads, checkout, and webhooks. See
> [Authentication & keys](/guides/authentication) for the full split.

## 2. Confirm the key is wired - `GET /v1/ping`

`GET /v1/ping` echoes which store your key resolves to, the key kind, the granted
scopes, and the mode **without touching any data** - the fastest way to prove
your key works.

Paste your key once and every snippet on this page rewrites to use it:

<ApiKeyField />

<CodeTabs :tabs="ping" />

A success looks like:

```json
{
  "tenant_id": "t_demo",
  "key_kind": "PUBLISHABLE",
  "scopes": ["storefront:catalog"],
  "mode": "sandbox"
}
```

Confirm `"mode": "sandbox"` before you experiment - see
[Sandbox vs live](/guides/sandbox-vs-live).

## 3. List products - `GET /v1/products`

Anonymous catalog reads work with the publishable key. Paginate with `limit` /
`offset`; the response carries a strong `ETag` you can revalidate against
(see [Pagination & caching](/guides/pagination-and-caching)):

<CodeTabs :tabs="products" />

Each product carries a **coarse availability band** (`IN_STOCK` / `LOW` / `OUT`),
never a raw on-hand count - see [Availability](/guides/availability).

## Next steps

- **[Authentication & keys](/guides/authentication)** - the capability split and
  shopper tokens for customer-scoped reads and checkout.
- **[Pagination & caching](/guides/pagination-and-caching)** - keep a local
  catalog fresh with `ETag` and `updated_since`.
- **[API Reference](/reference)** - every operation, parameter, and schema, with
  a live Try-it console.

::: tip In the API Reference
Open these operations in the interactive reference (with a **Try it** console):

- [`GET /v1/ping`](/reference#tag/diagnostics/GET/v1/ping) - check your key + mode
- [`GET /v1/products`](/reference#tag/catalog/GET/v1/products) - list the catalog
:::

---

# Guides

Source: https://developers.harmoncommerce.com/guides/

The Harmon Storefront API lets you build your own ecommerce store: read the
catalog, price a cart, and place orders. The base URL is `https://api.harmoncommerce.com`, and
every endpoint is described in the [API reference](/reference) - these guides are
the plain-language companion to it.

## Start here

- **[Quickstart](/quickstart)** - your first API call in five minutes: get a key,
  ping, list products.
- **[Authentication & keys](/guides/authentication)** - publishable vs secret
  keys, and shopper tokens.
- **[Sandbox vs live](/guides/sandbox-vs-live)** - build against a sandbox key,
  then flip to live.

## Core concepts

- **[Errors](/guides/errors)** - partial responses (`errors[]`) and
  the hard-failure status table.
- **[Rate limits](/guides/rate-limits)** - per-key limits and `Retry-After`.
- **[Pagination & caching](/guides/pagination-and-caching)** - `page`/`page_size`,
  `ETag` / `If-None-Match`, and `updated_since` deltas.
- **[Availability](/guides/availability)** - coarse stock bands, never raw counts.

## What this API doesn't do

- **Read-only catalog, pricing, and stock.** You can't change products, prices,
  or stock through this API - the only writes are shopper sign-up/login and
  cart/checkout.
- **No online card payments yet.** Checkout uses cash on delivery or credit
  terms; card payments are coming later.

---

# Authentication & keys

Source: https://developers.harmoncommerce.com/guides/authentication

Every request carries your store's API key as a bearer token:

```
Authorization: Bearer hk_live_pub_xxxxxxxxxxxx
```

Don't have a key yet? Create one on the **API keys** screen:

<GetKeysButton label="Get your API keys" />

Your key identifies your store, so you **never** send a store or account id. Any
`tenant_id` or `customer_id` you put in a body or query is ignored.

## Publishable vs secret keys

There are two kinds of key, with a hard capability split:

| Kind            | Prefix        | Ship to a browser? | Authorizes                                                                  |
| --------------- | ------------- | ------------------ | -------------------------------------------------------------------------- |
| **Publishable** | `hk_*_pub_…`  | ✅ yes (low-priv)  | Anonymous catalog reads                                                     |
| **Secret**      | `hk_*_sec_…`  | ❌ **never**       | Everything publishable does **plus** customer-scoped reads, checkout, webhooks |

A publishable key used on a customer-scoped or webhook route is always rejected
with `403` - never silently downgraded. Keep your secret key server-side only.

Check a key against `GET /v1/ping` - it echoes which store the key resolves to
(`tenant_id`), the `key_kind`, granted `scopes`, and `mode`, without touching any
data:

```bash
curl -s https://api.harmoncommerce.com/v1/ping \
  -H "Authorization: Bearer hk_live_pub_xxxxxxxxxxxx"
# → {"tenant_id":"…","key_kind":"PUBLISHABLE","scopes":["storefront:catalog"],"mode":"live"}
```

## Shopper tokens (customer-scoped routes)

Customer-scoped reads and the cart → checkout path require an end-shopper to be
logged in. The key authenticates the *integration*; the shopper token
authenticates the *customer*. Obtain a shopper token via the auth login flow,
then send it alongside the **secret** key:

```
Authorization: Bearer hk_live_sec_…
X-Storefront-Shopper-Token: <shopper jwt>
```

The shopper token carries the `customer_id`; every order, invoice, and credit
read is automatically scoped to that customer. A shopper token that belongs to a
different store than the key is rejected (`403`).

## CORS for publishable keys

A **publishable** key carries a CORS **origin allowlist**: a browser request from
an `Origin` not on the key's allowlist is refused `403`. Register every origin
your storefront serves from when you issue the key. **Secret** keys are
server-to-server and aren't origin-checked.

## Next steps

- **[Sandbox vs live](/guides/sandbox-vs-live)** - build against a test key, then
  flip to live.
- **[Errors](/guides/errors)** - what `401` / `403` mean and how reads degrade.
- **[Quickstart](/quickstart)** - get a key and make your first call.

::: tip In the API Reference
- [`GET /v1/ping`](/reference#tag/diagnostics/GET/v1/ping) - your first authenticated call; echoes the key's mode
- [`GET /v1/me`](/reference#tag/customer/GET/v1/me) - the customer a shopper token resolves to
:::

---

# Availability

Source: https://developers.harmoncommerce.com/guides/availability

Availability is always a **coarse band** - never a raw on-hand count. This holds
everywhere stock is surfaced: catalog reads, the dedicated availability
endpoints, and `stock.changed` webhook events.

| Band       | Meaning                                            |
| ---------- | -------------------------------------------------- |
| `IN_STOCK` | Comfortably available                              |
| `LOW`      | Limited quantity - running short                   |
| `OUT`      | Currently unavailable                              |
| `UNKNOWN`  | Stock state can't be determined right now          |

Coarse bands keep exact stock counts private while still telling a shopper what
they need to know to buy.

## Reading availability

Availability rides along on catalog reads, and there are dedicated endpoints for a
single SKU or a batch:

```bash
# A single SKU:
curl -s "https://api.harmoncommerce.com/v1/products/SKU-123/availability" \
  -H "Authorization: Bearer hk_test_pub_your_key_here"
# → {"sku":"SKU-123","availability":"LOW"}

# A batch in one call:
curl -s -X POST "https://api.harmoncommerce.com/v1/availability/batch" \
  -H "Authorization: Bearer hk_test_pub_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"skus":["SKU-123","SKU-456"]}'
```

## Next steps

- **[Pagination & caching](/guides/pagination-and-caching)** - keep availability
  fresh with `updated_since`.
- **[API Reference](/reference)** - the availability operations in full.

::: tip In the API Reference
- [`POST /v1/availability/batch`](/reference#tag/availability/POST/v1/availability/batch) - coarse bands for many SKUs in one call
:::

---

# Errors

Source: https://developers.harmoncommerce.com/guides/errors

## Partial responses

A read endpoint can return part of its data instead of failing the whole request.
When one section is temporarily unavailable, the response is still `200` with an
`errors[]` array naming each affected section, while the rest of the data loads
normally:

```json
{
  "data": [ /* … the sections that loaded … */ ],
  "errors": [
    { "field": "pricing", "code": "downstream_timeout", "detail": "pricing temporarily unavailable" }
  ]
}
```

Treat a non-empty `errors[]` as **this section is temporarily unavailable** - render
the rest and retry it, not a hard failure. An empty (or absent) `errors[]` means
the whole response is fresh.

## Hard failures

Hard failures use standard HTTP status codes:

| Status | Meaning                                                                  |
| ------ | ----------------------------------------------------------------------- |
| `401`  | Missing / malformed / unknown / revoked / expired key or shopper token  |
| `403`  | A publishable key on a privileged route, the wrong store, or an origin not on the key's allowlist |
| `404`  | Not found, or a cross-customer resource accessed by URL                 |
| `429`  | Rate limit exceeded - see [Rate limits](/guides/rate-limits)            |

Checkout over a credit limit returns a **structured** `over_credit_limit` state
(with the shortfall), not a raw `409` - inspect the response body, don't just
branch on the status code.

## Next steps

- **[Rate limits](/guides/rate-limits)** - handling `429` and `Retry-After`.
- **[Authentication & keys](/guides/authentication)** - what triggers `401` / `403`.

::: tip In the API Reference
Every operation lists its error responses. A good one to inspect:

- [`GET /v1/products`](/reference#tag/catalog/GET/v1/products) - the `errors[]` partial-response envelope on a catalog read
:::

---

# Pagination & caching

Source: https://developers.harmoncommerce.com/guides/pagination-and-caching

Anonymous catalog reads (`GET /v1/products`, `/v1/products/{sku}`,
`/v1/categories`) are built to be paginated, cached, and synced
cheaply.

## Pagination

Paginate the product list with `limit` / `offset`, and filter with `q` and
`category`:

```bash
curl -s "https://api.harmoncommerce.com/v1/products?limit=20&offset=20&category=brakes" \
  -H "Authorization: Bearer hk_test_pub_your_key_here"
```

## ETag / `If-None-Match`

Responses carry a strong **`ETag`** and a `Cache-Control: max-age` header. Send
the ETag back as `If-None-Match` to revalidate - an unchanged resource returns
`304 Not Modified` with **no body**, which doesn't count against your
[rate limit](/guides/rate-limits):

```bash
# First request - capture the ETag from the response headers:
curl -s -D - "https://api.harmoncommerce.com/v1/products?limit=20" \
  -H "Authorization: Bearer hk_test_pub_your_key_here"
# → ETag: "a1b2c3…"

# Revalidate - unchanged returns 304, no body:
curl -s -o /dev/null -w '%{http_code}\n' "https://api.harmoncommerce.com/v1/products?limit=20" \
  -H "Authorization: Bearer hk_test_pub_your_key_here" \
  -H 'If-None-Match: "a1b2c3…"'
# → 304
```

## `updated_since` - incremental sync

Pass **`updated_since=<ISO-8601>`** to fetch only products changed since your last
sync. This is the efficient way to keep a local cache - or a headless storefront's
search index - fresh **between** webhook deliveries, without re-listing the whole
catalog:

```bash
curl -s "https://api.harmoncommerce.com/v1/products?updated_since=2026-06-01T00:00:00Z" \
  -H "Authorization: Bearer hk_test_pub_your_key_here"
```

A typical sync loop: store the timestamp of your last successful pull, then on the
next run pass it as `updated_since` and merge the returned deltas into your local
copy.

## Next steps

- **[Availability](/guides/availability)** - coarse stock bands on catalog reads.
- **[Rate limits](/guides/rate-limits)** - why `304`s and deltas matter.

::: tip In the API Reference
- [`GET /v1/products`](/reference#tag/catalog/GET/v1/products) - see the `limit`/`offset` params, the `ETag` response header, and `updated_since`
:::

---

# Rate limits

Source: https://developers.harmoncommerce.com/guides/rate-limits

Each key is rate-limited **per minute**. Bursting past the limit returns `429`
with a `Retry-After` header (in seconds) - back off for that long, then retry:

```
HTTP/1.1 429 Too Many Requests
Retry-After: 12
```

A simple, correct client honours `Retry-After` rather than guessing:

```python
import time, requests

def get_with_backoff(url, headers):
    while True:
        res = requests.get(url, headers=headers)
        if res.status_code != 429:
            return res
        time.sleep(int(res.headers.get("Retry-After", "1")))
```

## Tips

- **Cache aggressively.** Anonymous catalog reads carry an `ETag` - revalidate
  with `If-None-Match` so a `304` costs you nothing against the limit. See
  [Pagination & caching](/guides/pagination-and-caching).
- **Sync with deltas.** Use `updated_since` to pull only what changed instead of
  re-listing the whole catalog.
- **Ask for a higher limit.** Each key's per-minute limit is set when it's
  issued - your Harmon admin can raise it for production traffic.

## Next steps

- **[Pagination & caching](/guides/pagination-and-caching)** - spend fewer
  requests with `ETag` and `updated_since`.
- **[Errors](/guides/errors)** - the full status-code table.

::: tip In the API Reference
- [`GET /v1/products`](/reference#tag/catalog/GET/v1/products) - a rate-limited read; pair it with `If-None-Match` so a `304` costs nothing
:::

---

# Sandbox vs live

Source: https://developers.harmoncommerce.com/guides/sandbox-vs-live

A key minted with the **`hk_test_`** prefix runs in **sandbox** mode; every other
key is **live**. Mode is derived from the key alone - there is no separate
environment toggle to forget - and is echoed on every response:

```
X-Harmon-Mode: sandbox
```

`GET /v1/ping` also returns `"mode": "sandbox" | "live"`, so you can assert your
test environment is wired to a test key **before** placing an order:

```bash
curl -s https://api.harmoncommerce.com/v1/ping \
  -H "Authorization: Bearer hk_test_pub_your_key_here"
# → {"…":"…","mode":"sandbox"}
```

## How to use it

Use a sandbox key to build and test your integration end-to-end - read the
catalog, build a cart, place an order - against sandbox data, without ever
touching live data. When you're ready for production, swap in your **live** key;
nothing else about your code changes.

> **Sandbox by default when exploring.** The interactive Try-it console and the
> runnable snippets in these docs default to a sandbox (`hk_test_…`) key and host
> so you can never accidentally mutate live data while learning the API.

## Switching to live

1. Create a **live** key pair (publishable + secret) on the **API keys**
   screen - see [Authentication & keys](/guides/authentication).
2. Set the live key in your production configuration (server-side for the secret
   key).
3. Confirm `GET /v1/ping` returns `"mode": "live"`.

## Next steps

- **[Authentication & keys](/guides/authentication)** - the publishable/secret
  capability split.
- **[Quickstart](/quickstart)** - your first sandbox call.

::: tip In the API Reference
- [`GET /v1/ping`](/reference#tag/diagnostics/GET/v1/ping) - confirm whether a key resolves to `sandbox` or `live`
:::

---

# Generate an SDK

Source: https://developers.harmoncommerce.com/guides/sdk-generation

<script setup>
// Phase 5.5 - SDK generation quick action. Every snippet generates a client
// from the canonical, machine-readable contract (the single source of truth,
// Invariant 1); the URL is imported from the shared config so it can't drift
// from the rest of the portal.
import { OPENAPI_URL, API_HOST } from '../.vitepress/theme/config';

const download = [
  {
    label: 'cURL',
    lang: 'bash',
    code: `# Download the OpenAPI contract (JSON)
curl -s ${OPENAPI_URL} -o harmon-storefront.openapi.json

# …or YAML
curl -s "${OPENAPI_URL}?format=yaml" -o harmon-storefront.openapi.yaml`,
  },
  {
    label: 'JavaScript',
    lang: 'js',
    code: `import { writeFileSync } from "node:fs";

const spec = await (await fetch("${OPENAPI_URL}")).json();
writeFileSync("harmon-storefront.openapi.json", JSON.stringify(spec, null, 2));`,
  },
  {
    label: 'Python',
    lang: 'python',
    code: `import json
import urllib.request

with urllib.request.urlopen("${OPENAPI_URL}") as r:
    spec = json.load(r)

with open("harmon-storefront.openapi.json", "w") as f:
    json.dump(spec, f, indent=2)`,
  },
  {
    label: 'PHP / Laravel',
    lang: 'php',
    code: `<?php
use Illuminate\\Support\\Facades\\Http;

$spec = Http::get('${OPENAPI_URL}')->json();
file_put_contents('harmon-storefront.openapi.json', json_encode($spec, JSON_PRETTY_PRINT));`,
  },
];

const generate = [
  {
    label: 'TypeScript',
    lang: 'bash',
    code: `# Generate fully-typed bindings straight from the live spec.
npx openapi-typescript ${OPENAPI_URL} -o src/harmon-storefront.d.ts

# A tiny typed client (openapi-fetch) that uses them:
npm i openapi-fetch`,
  },
  {
    label: 'TypeScript (usage)',
    lang: 'ts',
    code: `import createClient from "openapi-fetch";
import type { paths } from "./harmon-storefront.d.ts";

const client = createClient<paths>({
  baseUrl: "${API_HOST}",
  headers: { Authorization: "Bearer hk_test_pub_your_key_here" },
});

// Fully typed path, params, and response.
const { data } = await client.GET("/v1/products", {
  params: { query: { limit: 5 } },
});`,
  },
  {
    label: 'Python',
    lang: 'bash',
    code: `# A typed, async Python client from the same contract.
pipx run openapi-python-client generate --url ${OPENAPI_URL}`,
  },
  {
    label: 'PHP',
    lang: 'bash',
    code: `# A PSR-18 PHP client via the OpenAPI Generator.
npx @openapitools/openapi-generator-cli generate \\
  -i ${OPENAPI_URL} \\
  -g php \\
  -o ./harmon-storefront-php`,
  },
];
</script>


The OpenAPI contract is the **single source of truth** for this API, so you
don't have to hand-write a client - generate a typed one from the live spec and
regenerate whenever it changes. No published Harmon SDK required.

::: tip Always generate from the canonical spec
Point your generator at the published contract - `{{ OPENAPI_URL }}` - not a
copied-down file, so your client never drifts from what the API serves.
:::

## 1. Download the contract

<CodeTabs :tabs="download" />

You can also grab it (and a ready-made Postman collection) from the
[API Reference](/reference) download menu.

## 2. Generate a typed client

Pick your stack - each command reads the canonical spec directly:

<CodeTabs :tabs="generate" />

Want the generated client to use **your** key automatically? Set it once with the
[key control on the Quickstart](/quickstart), and every snippet on that page
rewrites to your key.

## Next steps

- **[Quickstart](/quickstart)** - your first call in five minutes.
- **[Authentication & keys](/guides/authentication)** - publishable vs secret keys.
- **[API Reference](/reference)** - the interactive contract + downloads.

---

# Verify webhook signatures

Source: https://developers.harmoncommerce.com/guides/webhook-signatures

<script setup>
// Phase 5.4 - the webhook signature playground + the canonical verification
// snippet across the Phase-0 language set. The signer here matches the
// storefront-api delivery signer exactly: sha256=<hex HMAC-SHA256(secret, body)>.
const verify = [
  {
    label: 'cURL',
    lang: 'bash',
    code: `# Recompute the signature over the EXACT received bytes and compare.
BODY="$(cat webhook-body.json)"
EXPECTED="sha256=$(printf '%s' "$BODY" \\
  | openssl dgst -sha256 -hmac "$SIGNING_SECRET" -hex | sed 's/^.* //')"
# Reject unless "$EXPECTED" equals the X-Harmon-Signature header you received.
echo "$EXPECTED"`,
  },
  {
    label: 'JavaScript',
    lang: 'js',
    code: `import crypto from "node:crypto";

// raw = the UNMODIFIED request body bytes (do NOT re-serialize the JSON first).
export function verifySignature(signingSecret, raw, signatureHeader) {
  const expected =
    "sha256=" + crypto.createHmac("sha256", signingSecret).update(raw).digest("hex");
  // Constant-time compare so you leak no timing oracle on the secret.
  const a = Buffer.from(expected);
  const b = Buffer.from(signatureHeader ?? "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}`,
  },
  {
    label: 'Python',
    lang: 'python',
    code: `import hashlib
import hmac

def verify_signature(signing_secret: str, raw_body: bytes, signature_header: str) -> bool:
    expected = "sha256=" + hmac.new(
        signing_secret.encode("utf-8"), raw_body, hashlib.sha256
    ).hexdigest()
    # Constant-time compare; raw_body is the unmodified request bytes.
    return hmac.compare_digest(expected, signature_header or "")`,
  },
  {
    label: 'PHP / Laravel',
    lang: 'php',
    code: `<?php
// $raw = $request->getContent(); // the unmodified request body bytes
function verify_signature(string $signingSecret, string $raw, string $header): bool
{
    $expected = 'sha256=' . hash_hmac('sha256', $raw, $signingSecret);
    // hash_equals is constant-time.
    return hash_equals($expected, $header);
}`,
  },
];
</script>


Every outbound webhook Harmon POSTs to your endpoint carries three headers:

```
X-Harmon-Event:     order.confirmed
X-Harmon-Delivery:  <uuid>
X-Harmon-Signature: sha256=<hex hmac>
```

The signature is an **HMAC-SHA256 of the exact request-body bytes**, keyed by the
`signing_secret` Harmon returned when you created the subscription (revealed
once). Verify it over the **raw bytes you received** - don't re-serialize the
JSON first, or the bytes (and the HMAC) won't match.

::: warning Verify before you parse
Compute the expected signature and reject the delivery on a mismatch **before**
you `json.loads` the body. A request that fails verification is not from Harmon.
:::

## Try it

Paste a signing secret and a body to see the signature Harmon would send, then
verify a signature against them. Everything runs locally - your secret never
leaves the browser.

<WebhookPlayground />

Tamper with a single character of the body (or the secret) after computing, then
re-verify: the result flips to **Invalid**. That's exactly the check your
receiver must perform.

## Verify in your stack

<CodeTabs :tabs="verify" />

## Next steps

- **[Errors](/guides/errors)** - status codes and how reads degrade.
- **[Quickstart](/quickstart)** - your first authenticated call.
- **[API Reference](/reference)** - the webhook subscription operations.

---

# API Reference

Source: https://developers.harmoncommerce.com/reference

The complete, interactive contract for the Harmon Storefront API - every
operation, parameter, and schema, with a built-in **Try it** console. It is
generated from the published OpenAPI document (the single source of truth), so
it never drifts from what the API actually serves.

New here? Start with the **[Quickstart](/quickstart)** for your first call in
five minutes, then the **[Guides](/guides/)** for auth, sandbox vs live, errors,
rate limits, caching, and availability.

The **Try it** console below is pre-loaded with a **sandbox** key (`hk_test_…`),
so you can fire `GET /v1/products` right now without setup - it can never touch
live data. Ready to use your own key? Paste it in:

<GetKeysButton label="Get your API keys" />

## Download & integrate

Prefer to work from the raw contract or generate a client? Everything is
downloadable - the spec is the single source of truth, so these never drift from
what the API serves:

- **OpenAPI** - [`openapi.json`](/openapi.json) · [`openapi.yaml`](/openapi.yaml)
- **Postman** - [`postman.json`](/postman.json) (import straight into Postman)

Building with an AI assistant? The whole portal is LLM-native: point it at
[`llms.txt`](/llms.txt) (an index of every page) or
[`llms-full.txt`](/llms-full.txt) (the entire docs as one Markdown file), and use
the **Copy page as Markdown** button on any page.

<ApiReference />

---

# Recipes

Source: https://developers.harmoncommerce.com/recipes/

<script setup>
// Phase 7.2 - the recipes index. Copyable "starter" snippets (the fastest path
// to a first 200) + the AI-prompt artifacts (a ready-to-paste prompt that points
// an assistant at llms-full.txt + the OpenAPI). The OpenAPI URL is imported from
// the shared config so it can't drift (single source of truth, Invariant 1).
// The API host and docs host come from the same one place.
import { OPENAPI_URL, API_HOST as HOST, SITE_URL } from '../.vitepress/theme/config';

const starter = [
  {
    label: 'cURL',
    lang: 'bash',
    code: `# Your first call: confirm the key, then read the catalog.
curl -s ${HOST}/v1/ping \\
  -H "Authorization: Bearer hk_test_pub_your_key_here"

curl -s "${HOST}/v1/products?limit=5" \\
  -H "Authorization: Bearer hk_test_pub_your_key_here"`,
  },
  {
    label: 'JavaScript',
    lang: 'js',
    code: `const auth = { Authorization: "Bearer hk_test_pub_your_key_here" };

await fetch("${HOST}/v1/ping", { headers: auth }).then((r) => r.json());

const { items } = await fetch(
  "${HOST}/v1/products?limit=5",
  { headers: auth },
).then((r) => r.json());
console.log(items);`,
  },
  {
    label: 'Python',
    lang: 'python',
    code: `import requests

auth = {"Authorization": "Bearer hk_test_pub_your_key_here"}

print(requests.get("${HOST}/v1/ping", headers=auth).json())

items = requests.get(
    "${HOST}/v1/products",
    params={"limit": 5},
    headers=auth,
).json()["items"]`,
  },
  {
    label: 'PHP / Laravel',
    lang: 'php',
    code: `<?php
use Illuminate\\Support\\Facades\\Http;

$client = Http::withToken('hk_test_pub_your_key_here');

$client->get('${HOST}/v1/ping')->json();
$items = $client->get('${HOST}/v1/products', ['limit' => 5])
    ->json('items');`,
  },
];

// The ready-to-paste AI prompt. Pointing an assistant at these two artifacts is
// enough for it to write a correct, current integration.
const aiPrompt = `You are helping me build an ecommerce storefront on the Harmon Storefront API.

Authoritative references (read these first):
- Full docs as one Markdown file: ${SITE_URL}/llms-full.txt
- Machine-readable contract (OpenAPI): ${OPENAPI_URL}

Rules to follow:
- Auth is a bearer API key. Publishable keys (hk_*_pub_) are browser-safe and do
  anonymous catalog reads only. Secret keys (hk_*_sec_) are server-side ONLY and
  unlock customer-scoped reads, cart/checkout, and webhooks.
- Customer-scoped calls also send X-Storefront-Shopper-Token.
- Never send a tenant_id or customer_id - they're resolved from the key/token.
- Use a sandbox key (hk_test_) while developing.
- Availability is a coarse band (IN_STOCK / LOW / OUT), never a raw count.

Task: <describe what you want to build>`;
</script>


Copy-paste cookbook for the most common storefront integrations. Each recipe is a
runnable, end-to-end walkthrough in every language we support (cURL · JavaScript ·
Python · PHP/Laravel), with deep-links into the interactive
[API Reference](/reference).

New here? Start with the **[Quickstart](/quickstart)** for your first call in five
minutes, then pick a recipe.

## The cookbook

- **[Render a product grid](/recipes/product-grid)** - list the catalog with a
  publishable key and show coarse availability badges.
- **[Cart → COD checkout](/recipes/cart-cod-checkout)** - the full commerce path:
  create a cart, add lines, price it, and place an order with cash on delivery or
  credit terms.
- **[Verify a webhook](/recipes/verify-webhook)** - subscribe, then verify the
  HMAC signature over the raw bytes before parsing.
- **[Keep a local catalog fresh with `updated_since`](/recipes/local-catalog-updated-since)** -
  seed a mirror once, then sync only what changed with `ETag` revalidation.
- **[Customer-priced catalog with a shopper token](/recipes/customer-priced-catalog)** -
  show contract pricing and credit standing once a shopper signs in.

## Starter snippet

The fastest path to a first `200` - confirm your key, then read the catalog.
Paste your key once and it rewrites below:

<GetKeysButton label="Get your API keys" />

<ApiKeyField />

<CodeTabs :tabs="starter" />

## Building with an AI assistant?

The whole portal is **LLM-native**. Point an assistant at the full docs and the
OpenAPI contract and it can write a correct, current integration for you:

- [`llms-full.txt`](/llms-full.txt) - the entire docs as one Markdown file
- [`llms.txt`](/llms.txt) - an index of every page
- [`openapi.json`](/openapi.json) · [`openapi.yaml`](/openapi.yaml) - the contract
- Every page has a **Copy page as Markdown** button for pasting a single page

### Ready-to-paste prompt

Drop this into your assistant, fill in the task, and go:

<CodeTabs :tabs="[{ label: 'AI prompt', lang: 'text', code: aiPrompt }]" />

## Next steps

- **[Guides](/guides/)** - auth, sandbox vs live, errors, rate limits, caching,
  availability - the building blocks every recipe draws on.
- **[Generate an SDK](/guides/sdk-generation)** - a typed client from the live
  spec, no hand-written code.
- **[API Reference](/reference)** - every operation with a live Try-it console.

---

# Cart → COD checkout

Source: https://developers.harmoncommerce.com/recipes/cart-cod-checkout

<script setup>
// Recipe 7.1 - "Cart → COD checkout." The full commerce path: create a cart,
// add lines, price it, then check out on the existing COD / credit-terms rails
// (no online card payment in v1). This path is customer-scoped, so it needs a
// SECRET key + a shopper token (server-side only - never ship a secret key to a
// browser). Placeholders are obvious (hk_test_…, Invariant 4/5).
// Host = single source of truth (theme/config.ts → page-source.mjs).
import { API_HOST as HOST } from '../.vitepress/theme/config';

const createCart = [
  {
    label: 'cURL',
    lang: 'bash',
    code: `curl -s -X POST "${HOST}/v1/carts" \\
  -H "Authorization: Bearer hk_test_sec_your_key_here" \\
  -H "X-Storefront-Shopper-Token: <shopper jwt>"`,
  },
  {
    label: 'JavaScript',
    lang: 'js',
    code: `// Secret key + shopper token - SERVER-SIDE ONLY. Never expose hk_*_sec_ in a browser.
const headers = {
  Authorization: "Bearer hk_test_sec_your_key_here",
  "X-Storefront-Shopper-Token": shopperToken,
  "Content-Type": "application/json",
};

const cart = await (
  await fetch("${HOST}/v1/carts", { method: "POST", headers })
).json();
console.log("cart", cart.cart_id);`,
  },
  {
    label: 'Python',
    lang: 'python',
    code: `import requests

headers = {
    "Authorization": "Bearer hk_test_sec_your_key_here",
    "X-Storefront-Shopper-Token": shopper_token,  # server-side only
}

cart = requests.post("${HOST}/v1/carts", headers=headers).json()
cart_id = cart["cart_id"]`,
  },
  {
    label: 'PHP / Laravel',
    lang: 'php',
    code: `<?php
use Illuminate\\Support\\Facades\\Http;

$client = Http::withToken('hk_test_sec_your_key_here')   // server-side only
    ->withHeaders(['X-Storefront-Shopper-Token' => $shopperToken]);

$cart = $client->post('${HOST}/v1/carts')->json();
$cartId = $cart['cart_id'];`,
  },
];

const addLines = [
  {
    label: 'cURL',
    lang: 'bash',
    code: `curl -s -X POST "${HOST}/v1/carts/$CART_ID/lines" \\
  -H "Authorization: Bearer hk_test_sec_your_key_here" \\
  -H "X-Storefront-Shopper-Token: <shopper jwt>" \\
  -H "Content-Type: application/json" \\
  -d '{"sku":"SKU-123","quantity":2}'`,
  },
  {
    label: 'JavaScript',
    lang: 'js',
    code: `await fetch(\`${HOST}/v1/carts/\${cart.cart_id}/lines\`, {
  method: "POST",
  headers,
  body: JSON.stringify({ sku: "SKU-123", quantity: 2 }),
});`,
  },
  {
    label: 'Python',
    lang: 'python',
    code: `requests.post(
    f"${HOST}/v1/carts/{cart_id}/lines",
    headers=headers,
    json={"sku": "SKU-123", "quantity": 2},
)`,
  },
  {
    label: 'PHP / Laravel',
    lang: 'php',
    code: `<?php
$client->post("${HOST}/v1/carts/{$cartId}/lines", [
    'sku' => 'SKU-123',
    'quantity' => 2,
]);`,
  },
];

const price = [
  {
    label: 'cURL',
    lang: 'bash',
    code: `curl -s -X POST "${HOST}/v1/carts/$CART_ID/price" \\
  -H "Authorization: Bearer hk_test_sec_your_key_here" \\
  -H "X-Storefront-Shopper-Token: <shopper jwt>"`,
  },
  {
    label: 'JavaScript',
    lang: 'js',
    code: `// Re-price the cart: customer-specific prices, tax/GCT, and the order total.
const priced = await (
  await fetch(\`${HOST}/v1/carts/\${cart.cart_id}/price\`, {
    method: "POST",
    headers,
  })
).json();
console.log(priced.estimated_subtotal, priced.estimated_tax, priced.estimated_total);`,
  },
  {
    label: 'Python',
    lang: 'python',
    code: `priced = requests.post(
    f"${HOST}/v1/carts/{cart_id}/price",
    headers=headers,
).json()
print(priced["estimated_subtotal"], priced["estimated_tax"], priced["estimated_total"])`,
  },
  {
    label: 'PHP / Laravel',
    lang: 'php',
    code: `<?php
$priced = $client->post("${HOST}/v1/carts/{$cartId}/price")->json();`,
  },
];

const checkout = [
  {
    label: 'cURL',
    lang: 'bash',
    code: `curl -s -X POST "${HOST}/v1/checkout" \\
  -H "Authorization: Bearer hk_test_sec_your_key_here" \\
  -H "X-Storefront-Shopper-Token: <shopper jwt>" \\
  -H "Content-Type: application/json" \\
  -d '{"cart_id":"'$CART_ID'","notes":"Leave at front desk"}'`,
  },
  {
    label: 'JavaScript',
    lang: 'js',
    code: `// Checkout is cash on delivery or credit terms; card payments aren't supported yet.
const res = await fetch("${HOST}/v1/checkout", {
  method: "POST",
  headers,
  body: JSON.stringify({ cart_id: cart.cart_id, notes: "Leave at front desk" }),
});

if (res.status === 422) {
  // A credit-limit block comes back as a STRUCTURED over_credit_limit state.
  const body = await res.json();
  if (body.state === "over_credit_limit") {
    showCreditBlock(body.credit.shortfall);
  }
} else {
  const order = await res.json();
  console.log("order placed:", order.order_id);
}`,
  },
  {
    label: 'Python',
    lang: 'python',
    code: `res = requests.post(
    "${HOST}/v1/checkout",
    headers=headers,
    json={"cart_id": cart_id, "notes": "Leave at front desk"},
)

body = res.json()
if body.get("state") == "over_credit_limit":
    handle_credit_block(body["credit"]["shortfall"])
else:
    print("order placed:", body["order_id"])`,
  },
  {
    label: 'PHP / Laravel',
    lang: 'php',
    code: `<?php
$res = $client->post("${HOST}/v1/checkout", [
    'cart_id' => $cartId,
    'notes' => 'Leave at front desk',
]);

$body = $res->json();
if (($body['state'] ?? null) === 'over_credit_limit') {
    return $this->showCreditBlock($body['credit']['shortfall']);
}
$orderId = $body['order_id'];`,
  },
];
</script>


Place a real order: create a cart, add lines, re-price it, then check out with
**cash on delivery or credit terms** (the only checkout path today - there are no
online card payments yet).

## What you need

- A **secret** key (`hk_test_sec_…`) - this path is customer-scoped, so a
  publishable key is rejected `403`.
- A **shopper token** for the signed-in customer (`X-Storefront-Shopper-Token`).
  The key authenticates your *integration*; the token authenticates the
  *customer*. See [Authentication & keys](/guides/authentication).

::: danger Secret keys are server-side only
`hk_*_sec_…` keys unlock checkout, customer reads, and webhooks. **Never** ship
one to a browser. Run every step on this page from your backend.
:::

## 1. Create a cart

A cart is scoped to the shopper carried by the token - you never pass a
`customer_id`.

<CodeTabs :tabs="createCart" />

## 2. Add lines

Add each item by `sku` + `quantity`. (Products sold in alternate units can pass
`order_uom` / `order_quantity`; everything settles in the product's base stock
unit.)

<CodeTabs :tabs="addLines" />

## 3. Re-price the cart

Pricing is computed server-side from the customer's contract prices plus tax/GCT.
Always re-price before showing a total or checking out.

<CodeTabs :tabs="price" />

## 4. Check out

Checkout converts the cart to an order on the COD / credit-terms rails. If the
order would exceed the customer's credit limit, the API returns a **structured**
`over_credit_limit` state (with the `shortfall`) - handle it, don't treat it as a
generic error.

<CodeTabs :tabs="checkout" />

Track the resulting order with `GET /v1/orders/{order_id}`, and reconcile against
`GET /v1/invoices` once an invoice is issued.

## Next steps

- **[Verify a webhook](/recipes/verify-webhook)** - react to `order.confirmed`
  and `invoice.issued` events instead of polling.
- **[Customer-priced catalog with a shopper token](/recipes/customer-priced-catalog)** -
  show the same contract pricing while the shopper browses.
- **[Errors](/guides/errors)** - the status table and the `over_credit_limit`
  state.

::: tip In the API Reference
Open these operations in the interactive reference (with a **Try it** console):

- [`POST /v1/carts`](/reference#tag/cart/POST/v1/carts) - create a cart
- [`POST /v1/carts/{cart_id}/lines`](/reference#tag/cart/POST/v1/carts/{cart_id}/lines) - add a line
- [`POST /v1/carts/{cart_id}/price`](/reference#tag/cart/POST/v1/carts/{cart_id}/price) - re-price
- [`POST /v1/checkout`](/reference#tag/checkout/POST/v1/checkout) - place the order
:::

---

# Customer-priced catalog with a shopper token

Source: https://developers.harmoncommerce.com/recipes/customer-priced-catalog

<script setup>
// Recipe 7.1 - "Customer-priced catalog with a shopper token." Once a shopper
// signs in, show their contract pricing + credit standing. Customer-scoped, so
// it needs a SECRET key + a shopper token (server-side only). Placeholders are
// obvious (hk_test_…, Invariant 4/5).
// Host = single source of truth (theme/config.ts → page-source.mjs).
import { API_HOST as HOST } from '../.vitepress/theme/config';

const whoami = [
  {
    label: 'cURL',
    lang: 'bash',
    code: `curl -s "${HOST}/v1/me" \\
  -H "Authorization: Bearer hk_test_sec_your_key_here" \\
  -H "X-Storefront-Shopper-Token: <shopper jwt>"`,
  },
  {
    label: 'JavaScript',
    lang: 'js',
    code: `// Secret key + shopper token - SERVER-SIDE ONLY.
const headers = {
  Authorization: "Bearer hk_test_sec_your_key_here",
  "X-Storefront-Shopper-Token": shopperToken,
};

// Confirm the signed-in customer. The token carries the customer_id -
// you never pass it yourself; Harmon scopes everything to it.
const me = await (await fetch("${HOST}/v1/me", { headers })).json();
console.log("customer:", me.customer_id, me.customer_name);`,
  },
  {
    label: 'Python',
    lang: 'python',
    code: `import requests

headers = {
    "Authorization": "Bearer hk_test_sec_your_key_here",
    "X-Storefront-Shopper-Token": shopper_token,  # server-side only
}

me = requests.get("${HOST}/v1/me", headers=headers).json()
print("customer:", me["customer_id"], me["customer_name"])`,
  },
  {
    label: 'PHP / Laravel',
    lang: 'php',
    code: `<?php
use Illuminate\\Support\\Facades\\Http;

$client = Http::withToken('hk_test_sec_your_key_here')   // server-side only
    ->withHeaders(['X-Storefront-Shopper-Token' => $shopperToken]);

$me = $client->get('${HOST}/v1/me')->json();`,
  },
];

const pricedCatalog = [
  {
    label: 'cURL',
    lang: 'bash',
    code: `# 1) Browse the catalog (anonymous fields).
curl -s "${HOST}/v1/products?limit=12" \\
  -H "Authorization: Bearer hk_test_sec_your_key_here" \\
  -H "X-Storefront-Shopper-Token: <shopper jwt>"

# 2) Price the selection FOR THIS CUSTOMER - contract prices + tax/GCT.
curl -s -X POST "${HOST}/v1/carts/$CART_ID/price" \\
  -H "Authorization: Bearer hk_test_sec_your_key_here" \\
  -H "X-Storefront-Shopper-Token: <shopper jwt>"`,
  },
  {
    label: 'JavaScript',
    lang: 'js',
    code: `// Catalog content is the same; the customer-specific PRICE comes from pricing
// a cart with the shopper token attached.
const { items: products } = await (
  await fetch(\`${HOST}/v1/products?limit=12\`, { headers })
).json();

// Build a cart of what they're viewing, then price it for this customer.
const priced = await (
  await fetch(\`${HOST}/v1/carts/\${cartId}/price\`, { method: "POST", headers })
).json();
renderGrid(products, priced.lines); // line.unit_price is the contract price`,
  },
  {
    label: 'Python',
    lang: 'python',
    code: `products = requests.get(
    "${HOST}/v1/products",
    params={"limit": 12},
    headers=headers,
).json()["items"]

priced = requests.post(
    f"${HOST}/v1/carts/{cart_id}/price",
    headers=headers,
).json()
# priced["lines"][i]["unit_price"] is the customer's contract price.`,
  },
  {
    label: 'PHP / Laravel',
    lang: 'php',
    code: `<?php
$products = $client->get('${HOST}/v1/products', ['limit' => 12])
    ->json('items');

$priced = $client->post("${HOST}/v1/carts/{$cartId}/price")->json();
// $priced['lines'][$i]['unit_price'] - the customer's contract price.`,
  },
];

const credit = [
  {
    label: 'cURL',
    lang: 'bash',
    code: `curl -s "${HOST}/v1/me/credit-status" \\
  -H "Authorization: Bearer hk_test_sec_your_key_here" \\
  -H "X-Storefront-Shopper-Token: <shopper jwt>"`,
  },
  {
    label: 'JavaScript',
    lang: 'js',
    code: `const credit = await (
  await fetch("${HOST}/v1/me/credit-status", { headers })
).json();
// Show available credit / terms before checkout so a block is no surprise.
console.log(credit.available_credit, credit.credit_limit);`,
  },
  {
    label: 'Python',
    lang: 'python',
    code: `credit = requests.get(
    "${HOST}/v1/me/credit-status",
    headers=headers,
).json()
print(credit["available_credit"], credit["credit_limit"])`,
  },
  {
    label: 'PHP / Laravel',
    lang: 'php',
    code: `<?php
$credit = $client->get('${HOST}/v1/me/credit-status')->json();`,
  },
];
</script>


Anonymous catalog reads show list content, but a B2B shopper expects **their**
contract pricing and credit standing. Once a shopper signs in, attach their
**shopper token** to a **secret**-key request and Harmon scopes everything -
pricing, orders, invoices, credit - to that customer automatically.

## What you need

- A **secret** key (`hk_test_sec_…`) - customer-scoped reads reject a publishable
  key with `403`.
- A **shopper token** (`X-Storefront-Shopper-Token`) from the auth login flow.
  The token carries the `customer_id`; you never send it yourself.

::: danger Secret keys are server-side only
Run every call here from your backend. A `hk_*_sec_…` key must never reach a
browser.
:::

## 1. Identify the signed-in shopper - `GET /v1/me`

Confirm the token resolves to the customer you expect before showing prices.

<CodeTabs :tabs="whoami" />

A shopper token that belongs to a different store than the key is rejected
`403`, even if the token itself is valid.

## 2. Show contract pricing

Catalog *content* is identical anonymous-or-not; the customer-specific **price**
comes from pricing a cart of what they're viewing with the shopper token
attached. Each priced line carries the customer's contract `unit_price` plus
tax/GCT.

<CodeTabs :tabs="pricedCatalog" />

## 3. Surface credit standing

Show available credit before checkout so an `over_credit_limit` block is never a
surprise.

<CodeTabs :tabs="credit" />

## Next steps

- **[Cart → COD checkout](/recipes/cart-cod-checkout)** - turn the priced cart
  into an order.
- **[Authentication & keys](/guides/authentication)** - how shopper tokens and
  secret keys work together.

::: tip In the API Reference
Open these operations in the interactive reference (with a **Try it** console):

- [`GET /v1/me`](/reference#tag/customer/GET/v1/me) - the signed-in customer
- [`GET /v1/me/credit-status`](/reference#tag/customer/GET/v1/me/credit-status) - credit standing
- [`POST /v1/carts/{cart_id}/price`](/reference#tag/cart/POST/v1/carts/{cart_id}/price) - customer-priced lines
:::

---

# Keep a local catalog fresh with `updated_since`

Source: https://developers.harmoncommerce.com/recipes/local-catalog-updated-since

<script setup>
// Recipe 7.1 - "Keep a local catalog fresh with updated_since." Seed a local
// mirror once, then poll for deltas with updated_since=<ISO-8601> and revalidate
// with ETag/If-None-Match. Anonymous catalog reads → a publishable key.
// Placeholders are obvious (hk_test_…, Invariant 4/5). Host = single source.
import { API_HOST as HOST } from '../.vitepress/theme/config';

const seed = [
  {
    label: 'cURL',
    lang: 'bash',
    code: `# Initial full sync - page through the whole catalog once.
curl -s "${HOST}/v1/products?limit=100&offset=0" \\
  -H "Authorization: Bearer hk_test_pub_your_key_here"`,
  },
  {
    label: 'JavaScript',
    lang: 'js',
    code: `// Page through the whole catalog once to seed your local store.
async function fullSync() {
  const limit = 100;
  let offset = 0;
  for (;;) {
    const res = await fetch(
      \`${HOST}/v1/products?limit=\${limit}&offset=\${offset}\`,
      { headers: { Authorization: "Bearer hk_test_pub_your_key_here" } },
    );
    const { items, total } = await res.json();
    await upsertProducts(items);
    offset += limit;
    if (offset >= total || items.length === 0) break;
  }
}`,
  },
  {
    label: 'Python',
    lang: 'python',
    code: `import requests

def full_sync():
    limit, offset = 100, 0
    while True:
        res = requests.get(
            "${HOST}/v1/products",
            params={"limit": limit, "offset": offset},
            headers={"Authorization": "Bearer hk_test_pub_your_key_here"},
        )
        payload = res.json()
        upsert_products(payload["items"])
        offset += limit
        if offset >= payload["total"] or not payload["items"]:
            break`,
  },
  {
    label: 'PHP / Laravel',
    lang: 'php',
    code: `<?php
use Illuminate\\Support\\Facades\\Http;

$limit = 100;
$offset = 0;
do {
    $payload = Http::withToken('hk_test_pub_your_key_here')
        ->get('${HOST}/v1/products', ['limit' => $limit, 'offset' => $offset])
        ->json();
    Product::upsertMany($payload['items']);
    $offset += $limit;
} while ($offset < $payload['total']);`,
  },
];

const delta = [
  {
    label: 'cURL',
    lang: 'bash',
    code: `# Only products changed since your last sync watermark.
curl -s "${HOST}/v1/products?updated_since=2026-06-01T00:00:00Z" \\
  -H "Authorization: Bearer hk_test_pub_your_key_here"`,
  },
  {
    label: 'JavaScript',
    lang: 'js',
    code: `// Poll for deltas between webhook deliveries. Persist the high-water mark.
async function syncDeltas(since) {
  // Capture the sync time BEFORE the request - that becomes the next watermark.
  const syncedAt = new Date().toISOString();
  const res = await fetch(
    \`${HOST}/v1/products?updated_since=\${encodeURIComponent(since)}\`,
    { headers: { Authorization: "Bearer hk_test_pub_your_key_here" } },
  );
  const { items } = await res.json();
  await upsertProducts(items);
  // Advance the watermark to the sync time; the next poll pulls only newer changes.
  return syncedAt;
}`,
  },
  {
    label: 'Python',
    lang: 'python',
    code: `import requests
from datetime import datetime, timezone

def sync_deltas(since: str) -> str:
    # Capture the sync time BEFORE the request - that becomes the next watermark.
    synced_at = datetime.now(timezone.utc).isoformat()
    res = requests.get(
        "${HOST}/v1/products",
        params={"updated_since": since},
        headers={"Authorization": "Bearer hk_test_pub_your_key_here"},
    )
    items = res.json()["items"]
    upsert_products(items)
    # Advance the watermark to the sync time; the next poll pulls only newer changes.
    return synced_at`,
  },
  {
    label: 'PHP / Laravel',
    lang: 'php',
    code: `<?php
use Illuminate\\Support\\Facades\\Http;

// Capture the sync time BEFORE the request - that becomes the next watermark.
$syncedAt = now()->toIso8601String();
$items = Http::withToken('hk_test_pub_your_key_here')
    ->get('${HOST}/v1/products', ['updated_since' => $since])
    ->json('items');

Product::upsertMany($items);
$watermark = $syncedAt; // the next poll pulls only changes newer than this`,
  },
];

const revalidate = [
  {
    label: 'cURL',
    lang: 'bash',
    code: `# Revalidate a cached page: a 304 means "nothing changed", no body, no cost.
curl -s -i "${HOST}/v1/products?limit=100" \\
  -H "Authorization: Bearer hk_test_pub_your_key_here" \\
  -H 'If-None-Match: "<etag-from-last-response>"'`,
  },
  {
    label: 'JavaScript',
    lang: 'js',
    code: `const res = await fetch(\`${HOST}/v1/products?limit=100\`, {
  headers: {
    Authorization: "Bearer hk_test_pub_your_key_here",
    "If-None-Match": lastEtag,
  },
});
if (res.status === 304) return; // unchanged - keep the local copy
const etag = res.headers.get("ETag");
await upsertProducts((await res.json()).items);`,
  },
  {
    label: 'Python',
    lang: 'python',
    code: `res = requests.get(
    "${HOST}/v1/products",
    params={"limit": 100},
    headers={
        "Authorization": "Bearer hk_test_pub_your_key_here",
        "If-None-Match": last_etag,
    },
)
if res.status_code == 304:
    return  # unchanged
etag = res.headers["ETag"]
upsert_products(res.json()["items"])`,
  },
  {
    label: 'PHP / Laravel',
    lang: 'php',
    code: `<?php
$res = Http::withToken('hk_test_pub_your_key_here')
    ->withHeaders(['If-None-Match' => $lastEtag])
    ->get('${HOST}/v1/products', ['limit' => 100]);

if ($res->status() === 304) {
    return; // unchanged
}
$etag = $res->header('ETag');`,
  },
];
</script>


A headless storefront or a search index wants a **local mirror** of the catalog,
not a live API call on every page view. Seed the mirror once, then keep it fresh
cheaply: pull only what changed with `updated_since`, and skip unchanged pages
with `ETag` revalidation. Pair it with [webhooks](/recipes/verify-webhook) for
near-real-time updates between polls.

## 1. Seed the mirror (one full sync)

Page through the whole catalog once and upsert into your local store.

<CodeTabs :tabs="seed" />

Record the time of this sync as your **watermark** - the next sync starts from
there.

## 2. Pull deltas with `updated_since`

`updated_since=<ISO-8601>` returns only products changed since that instant - the
efficient way to keep the mirror current between webhook deliveries. Advance your
watermark to the time of each sync (captured just before the request).

<CodeTabs :tabs="delta" />

::: tip Belt and braces
Subscribe to the `product.updated` and `stock.changed`
[webhooks](/recipes/verify-webhook) for push updates, and run an `updated_since`
poll on a timer as a backstop in case a delivery is ever missed.
:::

## 3. Revalidate with `ETag` / `If-None-Match`

Every list response carries a strong `ETag`. Send it back as `If-None-Match` and
an unchanged page returns `304 Not Modified` with no body - you keep your cached
copy at almost zero cost.

<CodeTabs :tabs="revalidate" />

## Next steps

- **[Pagination & caching](/guides/pagination-and-caching)** - the full
  `ETag` / `If-None-Match` / `updated_since` model.
- **[Verify a webhook](/recipes/verify-webhook)** - push updates to complement
  the poll.
- **[Render a product grid](/recipes/product-grid)** - serve the mirror you just
  built.

::: tip In the API Reference
Open this operation in the interactive reference (with a **Try it** console):

- [`GET /v1/products`](/reference#tag/catalog/GET/v1/products) - supports `updated_since`, `ETag`, and `If-None-Match`
:::

---

# Render a product grid

Source: https://developers.harmoncommerce.com/recipes/product-grid

<script setup>
// Recipe 7.1 - "Render a product grid." Anonymous catalog reads with a
// publishable key: list a page of products, read the coarse availability band,
// link each card to its detail. Keys are obvious sandbox placeholders
// (hk_test_…, Invariant 4/5) - the on-page key control rewrites them in place.
// Host = single source of truth (theme/config.ts → page-source.mjs).
import { API_HOST as HOST } from '../.vitepress/theme/config';

const list = [
  {
    label: 'cURL',
    lang: 'bash',
    code: `curl -s "${HOST}/v1/products?limit=12" \\
  -H "Authorization: Bearer hk_test_pub_your_key_here"`,
  },
  {
    label: 'JavaScript',
    lang: 'js',
    code: `// A publishable key is browser-safe - fetch a page of products and render.
async function loadGrid(offset = 0) {
  const res = await fetch(
    \`${HOST}/v1/products?limit=12&offset=\${offset}\`,
    { headers: { Authorization: "Bearer hk_test_pub_your_key_here" } },
  );
  const { items, total } = await res.json();
  return { products: items, total };
}

const { products } = await loadGrid();
document.querySelector("#grid").innerHTML = products
  .map(
    (p) => \`
    <a class="card" href="/products/\${p.sku}">
      <img src="\${p.cover?.thumb_url ?? ''}" alt="\${p.description ?? ''}" />
      <h3>\${p.description ?? ''}</h3>
      <p class="price">\${p.customer_unit_price ?? p.list_unit_price ?? ''}</p>
      <span class="badge badge--\${p.availability?.toLowerCase()}">
        \${p.availability ?? ''}
      </span>
    </a>\`,
  )
  .join("");`,
  },
  {
    label: 'Python',
    lang: 'python',
    code: `import requests

res = requests.get(
    "${HOST}/v1/products",
    params={"limit": 12},
    headers={"Authorization": "Bearer hk_test_pub_your_key_here"},
)
payload = res.json()
for product in payload["items"]:
    print(product["sku"], product["description"], product["availability"])`,
  },
  {
    label: 'PHP / Laravel',
    lang: 'php',
    code: `<?php
use Illuminate\\Support\\Facades\\Http;

$res = Http::withToken('hk_test_pub_your_key_here')
    ->get('${HOST}/v1/products', ['limit' => 12]);

return view('catalog.grid', [
    'products' => $res->json('items'),
    'total'    => $res->json('total'),
]);`,
  },
];

const detail = [
  {
    label: 'cURL',
    lang: 'bash',
    code: `curl -s "${HOST}/v1/products/SKU-123" \\
  -H "Authorization: Bearer hk_test_pub_your_key_here"`,
  },
  {
    label: 'JavaScript',
    lang: 'js',
    code: `const res = await fetch("${HOST}/v1/products/SKU-123", {
  headers: { Authorization: "Bearer hk_test_pub_your_key_here" },
});
const product = await res.json();
console.log(product.description, product.availability);`,
  },
  {
    label: 'Python',
    lang: 'python',
    code: `import requests

res = requests.get(
    "${HOST}/v1/products/SKU-123",
    headers={"Authorization": "Bearer hk_test_pub_your_key_here"},
)
print(res.json())`,
  },
  {
    label: 'PHP / Laravel',
    lang: 'php',
    code: `<?php
use Illuminate\\Support\\Facades\\Http;

$product = Http::withToken('hk_test_pub_your_key_here')
    ->get('${HOST}/v1/products/SKU-123')
    ->json();`,
  },
];
</script>


Build a browsable storefront grid from the public catalog - a page of products,
each with a name, price, image, and a coarse **availability band** - using only a
**publishable** key (browser-safe, anonymous catalog reads). No shopper login,
no secret key.

This is the most common first integration: a headless storefront's listing page.

## What you need

- A **publishable** sandbox key (`hk_test_pub_…`). Create one on the
  **API keys** screen.
- Nothing else - catalog reads are anonymous.

<GetKeysButton label="Get your API keys" />

Paste your key once and every snippet below rewrites to use it:

<ApiKeyField />

## 1. List a page of products

`GET /v1/products` returns a page of catalog items plus a `total` count.
Paginate with `limit` / `offset`; narrow with `q` or `category`.

<CodeTabs :tabs="list" />

Each item carries a **coarse availability band** (`IN_STOCK` / `LOW` / `OUT`),
never a raw on-hand count - render it as a badge, not a quantity. See
[Availability](/guides/availability).

::: tip Cache the grid
The list response carries a strong `ETag`. Send it back as `If-None-Match` on the
next load to get a `304 Not Modified` when nothing changed - see
[Pagination & caching](/guides/pagination-and-caching).
:::

## 2. Link each card to its detail page

The grid links each card to a product detail view backed by
`GET /v1/products/{sku}`:

<CodeTabs :tabs="detail" />

## Next steps

- **[Keep a local catalog fresh with `updated_since`](/recipes/local-catalog-updated-since)** -
  sync only what changed instead of refetching every page.
- **[Customer-priced catalog with a shopper token](/recipes/customer-priced-catalog)** -
  show contract pricing once a shopper signs in.
- **[Availability](/guides/availability)** - the coarse-band model in full.

::: tip In the API Reference
Open these operations in the interactive reference (with a **Try it** console):

- [`GET /v1/products`](/reference#tag/catalog/GET/v1/products) - list the catalog
- [`GET /v1/products/{sku}`](/reference#tag/catalog/GET/v1/products/{sku}) - a single product
:::

---

# Verify a webhook

Source: https://developers.harmoncommerce.com/recipes/verify-webhook

<script setup>
// Recipe 7.1 - "Verify a webhook." Subscribe, then verify the HMAC-SHA256
// signature over the EXACT request bytes before parsing. The signer matches the
// storefront-api delivery signer: sha256=<hex HMAC-SHA256(secret, raw body)>.
// Subscribe needs a SECRET key (storefront:webhooks scope); placeholders are
// obvious (hk_test_…, Invariant 4/5).
// Host = single source of truth (theme/config.ts → page-source.mjs).
import { API_HOST as HOST } from '../.vitepress/theme/config';

const subscribe = [
  {
    label: 'cURL',
    lang: 'bash',
    code: `curl -s -X POST "${HOST}/v1/webhooks" \\
  -H "Authorization: Bearer hk_test_sec_your_key_here" \\
  -H "Content-Type: application/json" \\
  -d '{
    "endpoint_url": "https://store.example.com/harmon/webhook",
    "event_types": ["order.confirmed", "invoice.issued", "stock.changed"]
  }'
# The response reveals "signing_secret" ONCE - store it now.`,
  },
  {
    label: 'JavaScript',
    lang: 'js',
    code: `const sub = await (
  await fetch("${HOST}/v1/webhooks", {
    method: "POST",
    headers: {
      Authorization: "Bearer hk_test_sec_your_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      endpoint_url: "https://store.example.com/harmon/webhook",
      event_types: ["order.confirmed", "invoice.issued", "stock.changed"],
    }),
  })
).json();

// signing_secret is revealed ONCE - persist it securely now.
await saveSigningSecret(sub.signing_secret);`,
  },
  {
    label: 'Python',
    lang: 'python',
    code: `import requests

sub = requests.post(
    "${HOST}/v1/webhooks",
    headers={"Authorization": "Bearer hk_test_sec_your_key_here"},
    json={
        "endpoint_url": "https://store.example.com/harmon/webhook",
        "event_types": ["order.confirmed", "invoice.issued", "stock.changed"],
    },
).json()

# signing_secret is revealed ONCE - store it now.
save_signing_secret(sub["signing_secret"])`,
  },
  {
    label: 'PHP / Laravel',
    lang: 'php',
    code: `<?php
use Illuminate\\Support\\Facades\\Http;

$sub = Http::withToken('hk_test_sec_your_key_here')
    ->post('${HOST}/v1/webhooks', [
        'endpoint_url' => 'https://store.example.com/harmon/webhook',
        'event_types' => ['order.confirmed', 'invoice.issued', 'stock.changed'],
    ])
    ->json();

// signing_secret is revealed ONCE - store it now.
SigningSecret::store($sub['signing_secret']);`,
  },
];

const receive = [
  {
    label: 'JavaScript',
    lang: 'js',
    code: `import crypto from "node:crypto";
import express from "express";

const app = express();

// Capture the RAW bytes - do NOT let a JSON parser run first.
app.post(
  "/harmon/webhook",
  express.raw({ type: "*/*" }),
  (req, res) => {
    const raw = req.body; // Buffer of the exact received bytes
    const expected =
      "sha256=" +
      crypto.createHmac("sha256", SIGNING_SECRET).update(raw).digest("hex");
    const got = req.get("X-Harmon-Signature") ?? "";

    const a = Buffer.from(expected);
    const b = Buffer.from(got);
    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
      return res.sendStatus(401); // not from Harmon - reject before parsing
    }

    const event = JSON.parse(raw.toString("utf8"));
    handle(req.get("X-Harmon-Event"), event);
    res.sendStatus(200);
  },
);`,
  },
  {
    label: 'Python',
    lang: 'python',
    code: `import hashlib
import hmac
from fastapi import FastAPI, Request, HTTPException

app = FastAPI()

@app.post("/harmon/webhook")
async def receive(request: Request):
    raw = await request.body()  # exact received bytes - verify BEFORE parsing
    expected = "sha256=" + hmac.new(
        SIGNING_SECRET.encode("utf-8"), raw, hashlib.sha256
    ).hexdigest()
    got = request.headers.get("X-Harmon-Signature", "")
    if not hmac.compare_digest(expected, got):
        raise HTTPException(status_code=401)  # not from Harmon

    event = json.loads(raw)
    handle(request.headers.get("X-Harmon-Event"), event)
    return {"ok": True}`,
  },
  {
    label: 'PHP / Laravel',
    lang: 'php',
    code: `<?php
// routes/web.php - Route::post('/harmon/webhook', WebhookController::class);
public function __invoke(Request $request)
{
    $raw = $request->getContent(); // exact received bytes
    $expected = 'sha256=' . hash_hmac('sha256', $raw, $this->signingSecret);

    // hash_equals is constant-time. Verify BEFORE decoding the JSON.
    if (! hash_equals($expected, $request->header('X-Harmon-Signature', ''))) {
        abort(401); // not from Harmon
    }

    $event = json_decode($raw, true);
    $this->handle($request->header('X-Harmon-Event'), $event);
    return response()->noContent();
}`,
  },
];
</script>


React to events - `order.confirmed`, `invoice.issued`, `stock.changed`,
`order.shipped`, `product.updated` - instead of polling. Every delivery is
**HMAC-signed**; verify the signature over the exact bytes you received **before**
you parse the body, so a forged request never reaches your handler.

## What you need

- A **secret** key with the `storefront:webhooks` scope (subscriptions are a
  privileged write).
- A public HTTPS endpoint Harmon can POST to.

## 1. Subscribe

Create a subscription with your endpoint and the events you care about. The
response reveals a `signing_secret` **once** - store it immediately; you can't
read it back.

<CodeTabs :tabs="subscribe" />

Test the wiring any time with `POST /v1/webhooks/{subscription_id}/ping` - it
sends a signed test delivery to your endpoint.

## 2. Verify on receipt

Each delivery carries three headers:

```
X-Harmon-Event:     order.confirmed
X-Harmon-Delivery:  <uuid>
X-Harmon-Signature: sha256=<hex hmac>
```

`X-Harmon-Signature` is an **HMAC-SHA256 of the exact request-body bytes**, keyed
by your `signing_secret`. Recompute it over the **raw bytes** - don't re-serialize
the JSON first, or the bytes (and the HMAC) won't match - and reject on a
mismatch before doing anything else.

<CodeTabs :tabs="receive" />

::: warning Verify before you parse
A request that fails verification is not from Harmon. Compute the expected
signature and reject the delivery **before** you decode the body. Use a
constant-time compare (`timingSafeEqual` / `hmac.compare_digest` / `hash_equals`)
so you leak no timing oracle on the secret.
:::

Want to experiment without writing a receiver? The
[Verify webhook signatures](/guides/webhook-signatures) guide has an interactive
**playground**: paste a secret and a body, compute the signature, then tamper a
byte and watch verification flip to **Invalid**.

## Next steps

- **[Verify webhook signatures](/guides/webhook-signatures)** - the playground +
  the canonical signer in every language.
- **[Cart → COD checkout](/recipes/cart-cod-checkout)** - produce the
  `order.confirmed` event this recipe consumes.

::: tip In the API Reference
Open these operations in the interactive reference (with a **Try it** console):

- [`POST /v1/webhooks`](/reference#tag/webhooks/POST/v1/webhooks) - create a subscription
- [`POST /v1/webhooks/{subscription_id}/ping`](/reference#tag/webhooks/POST/v1/webhooks/{subscription_id}/ping) - send a signed test delivery
:::

---

# Changelog

Source: https://developers.harmoncommerce.com/changelog

What's new in the Harmon Storefront API and this developer portal. The API is at
**v1** (`info.version 1.0.0`); the [API Reference](/reference) is generated from
the live contract, so it always reflects what the API serves today.

::: tip Subscribe to changes
Breaking changes ship under a new major API version (see [Versioning](#versioning)
below). To track catalog/stock/order changes programmatically, use
[webhooks](/recipes/verify-webhook) and the `updated_since`
[delta sync](/recipes/local-catalog-updated-since).
:::

## API - v1

### Removed - vehicle catalog & fitment

The vehicle catalog and fitment endpoints (`/v1/vehicles/years`,
`/v1/vehicles/makes`, `/v1/vehicles/models`,
`/v1/vehicles/{vehicle_id}/products`, and `/v1/products/{sku}/fitments`) have
been retired, along with the `vehicle_id` filter on `GET /v1/products` and the
`fitment_enabled` response flag. If you filtered your catalog by vehicle, list
products with `GET /v1/products` and filter on your own attributes instead.

### Additive - rich product detail

`GET /v1/products/{sku}` now returns the full authored product detail page: a
long-form `body` (CommonMark **Markdown** - render it client-side; `description`
stays the product's name/label), a plain-text `short_description` summary (handy
for cards and listings), and a
store-defined `specs` store
(`{ "groups": [ { "label", "rows": [ { "label", "value", "highlight" } ] } ] }` -
the `highlight` rows back a quick-glance grid). Both the list and detail also
carry derived marketing `badges` (`ON_SALE`, `LOW_STOCK`) and sale pricing -
`compare_at_unit_price` (the strike-through list price) plus a derived
`discount_percent`. The product gallery (`media[]`) now includes YouTube/Vimeo
video embeds: a `MediaRefOut` carries `kind` (`IMAGE` or `VIDEO`) and, for a
video, `provider` + `embed_url` + `poster_url` + `duration_seconds`. A product
hidden on the storefront is absent from the list and `404`s on detail. All of
this is additive (clients that ignore unknown fields are unaffected); authoring
any of it changes the product's `ETag`, so `If-None-Match` revalidation picks up
the change automatically.

### Additive - product media

`GET /v1/products` and `GET /v1/products/{sku}` now carry product imagery: a
single resolved `cover` (or `null`) plus a cover-first `media[]` gallery. Each
entry (`MediaRefOut`) carries the presentation metadata and the resolved public
WebP derivative URLs - `thumb_url` (small, for grids) and `large_url` (for
viewing) - so you render images without a second request. A product with no
imagery returns `cover: null` and `media: []`. This is an additive change
(clients that ignore unknown fields are unaffected); adding, removing, or
reordering a product's media changes its `ETag`, so `If-None-Match` revalidation
picks up the new gallery automatically.

### v1.0.0 - initial public release

The first public, machine-authenticated commerce API for building your own
storefront on Harmon.

- **Auth** - store-scoped API keys with a hard publishable/secret split, plus
  shopper tokens for customer-scoped reads and checkout. See
  [Authentication & keys](/guides/authentication).
- **Sandbox & live** - `hk_test_` keys run in sandbox; mode is echoed on every
  response. See [Sandbox vs live](/guides/sandbox-vs-live).
- **Catalog** - products, categories, coarse availability bands, and
  vehicle fitment, with `ETag`/`If-None-Match` revalidation and `updated_since`
  deltas. See [Pagination & caching](/guides/pagination-and-caching).
- **Commerce** - cart → cash-on-delivery / credit-terms checkout, customer-scoped
  orders, invoices, and credit status.
- **Webhooks** - HMAC-signed delivery of `order.confirmed`, `order.shipped`,
  `order.cancelled`, `invoice.issued`, `product.created`, `product.updated`, and
  `stock.changed` events. See [Verify webhook signatures](/guides/webhook-signatures).

## Portal

This branded developer portal ships alongside v1:

- Quickstart, guides, and a [recipes cookbook](/recipes/) with copy-paste,
  multi-language snippets (cURL · JavaScript · Python · PHP/Laravel).
- An embedded, OpenAPI-driven [API Reference](/reference) with a sandbox-default
  **Try it** console.
- LLM-native artifacts - [`llms.txt`](/llms.txt), [`llms-full.txt`](/llms-full.txt),
  per-page "copy as Markdown," and one-click [OpenAPI](/openapi.json) / Postman
  downloads.

## Versioning

The Storefront API is versioned in the **URL path** (`/v1/…`). The contract
follows these rules:

- **Additive changes are not breaking.** New endpoints, new optional request
  fields, and new response fields can appear within `v1` at any time - write
  clients that ignore unknown fields.
- **Breaking changes ship under a new major version** (`/v2/…`). The previous
  major stays available through its announced deprecation window.
- **`info.version`** (currently `1.0.0`) tracks the contract's semantic version;
  the [API Reference](/reference) and the downloadable
  [OpenAPI](/openapi.json) are always generated from the live spec, so they never
  drift from what the API serves.

When a `v2` contract exists, the **version switcher** in the top navigation will
let you read the `v1` and `v2` references side by side. Today only `v1` is
published.