Guides

The Harmon Storefront API is a public, machine-authenticated read + commerce API for building your own ecommerce site on Harmon. It is served on its own host (https://api.harmon.example) and is the only externally consumed Harmon surface. Its machine-readable contract is the published OpenAPI document; these guides are the human companion to it.

Start here

• Quickstart - your first API call in five minutes: get a key, ping, list products.
• Authentication & keys - publishable vs secret keys, the capability split, and shopper tokens.
• Sandbox vs live - build against a sandbox key, then flip to live.

Core concepts

• Errors - section-by-section degradation (errors[]) and the hard-failure status table.
• Rate limits - per-key limits and Retry-After.
• Pagination & caching - page/page_size, ETag / If-None-Match, and updated_since deltas.
• Availability - coarse stock bands, never raw counts.

What this API does not do (v1)

• No merchant-authored writes to catalog, pricing, or stock - those stay admin-authored (the deliberate read-only boundary). The only writes are shopper account create/login and cart/checkout.
• No online card payments - checkout reuses the existing COD / credit-terms path. A payment-gateway step is a planned follow-up.
• No OAuth2/OIDC, no guest checkout, no GraphQL, and no multi-currency presentment beyond the merchant's default currency.