Recipes

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.

New here? Start with the Quickstart for your first call in five minutes, then pick a recipe.

The cookbook

• Render a product grid - list the catalog with a publishable key and show coarse availability badges.
• Cart → COD checkout - the full commerce path: create a cart, add lines, price it, and place an order on the COD / credit-terms rails.
• Verify a webhook - subscribe, then verify the HMAC signature over the raw bytes before parsing.
• Keep a local catalog fresh with updated_since - seed a mirror once, then sync only what changed with ETag revalidation.
• Customer-priced catalog with a shopper token - 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:

→ Get your API keys

Paste your API key once

Stored only in this browser, never sent anywhere but the API. Every snippet on the page rewrites to use it.

# Your first call: confirm the key, then read the catalog.
curl -s https://api.harmon.example/v1/ping \
  -H "Authorization: Bearer hk_test_pub_your_key_here"

curl -s "https://api.harmon.example/v1/products?page=1&page_size=5" \
  -H "Authorization: Bearer hk_test_pub_your_key_here"

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 - the entire docs as one Markdown file
• llms.txt - an index of every page
• openapi.json · 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:

You are helping me build an ecommerce storefront on the Harmon Storefront API.

Authoritative references (read these first):
- Full docs as one Markdown file: https://developers.harmon.example/llms-full.txt
- Machine-readable contract (OpenAPI): https://api.harmon.example/openapi.json

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>

Next steps

• Guides - auth, sandbox vs live, errors, rate limits, caching, availability - the building blocks every recipe draws on.
• Generate an SDK - a typed client from the live spec, no hand-written code.
• API Reference - every operation with a live Try-it console.