Integration guide
The full end-to-end walkthrough for building a storefront or custom client on Orchard. The Developer quickstart is the five-minute version; this is the complete picture.
The live API surface
The spec is generated from the deployed route handlers, so it is exactly what
/api/v1/* exposes today — 45 routes across these areas:
| Area | What’s there |
|---|---|
products | list, detail (by slug), images, reviews |
cart | create, items, apply promo / gift card, save / restore, unsubscribe |
checkout | create Stripe Checkout Session, poll order status |
orders | order lookup (for confirmation / account pages) |
content | published articles / recipes / announcements |
search | semantic search (Postgres FTS fallback) |
inventory | batch stock-status lookup |
customer | magic-link request/consume, session (me), refresh, sign-out |
customer-portal | self-service: orders, subscriptions, cancel, returns |
subscriptions | gift checkout, reactivate, manage |
leads / returns / wholesale | email capture, RMA, B2B inquiry |
billing-portal / storefront/config / shipping/rates / partners / analytics | misc storefront support |
Two routes are internal (not part of your contract): POST /search/embed and
POST /integrations/helpscout/customer-sidebar.
Browse the full schema in the API Reference.
Environments
- Live API:
https://api.theorchard.dev/api/v1 - Test API:
https://api-test.theorchard.dev/api/v1(separate Supabase project — use test-mode keys here) - Admin:
https://admin.theorchard.dev/t/{slug}
Set NEXT_PUBLIC_ORCHARD_API to the appropriate base per environment. Public reads
are rate-limited per-key (Bearer) or per-tenant+IP (anonymous); honor the
Retry-After header on a 429.
The build order
- Skim the API Reference.
- Generate types and build the read path (products → content → inventory) against your test tenant.
- Wire customer auth
and checkout (
POST /checkout/sessions) once you have test keys. - Subscribe to webhooks for order and subscription events.
- Scope your custom modules as one-pagers and send them to the operator.
Provisioning ask — what you need from the operator
Before you start, the operator provisions your tenant and gives you:
- A tenant slug
- Test-mode keys (
sk_test_…,pk_test_…) with the scopes you need - Confirmation of which modules are enabled for your tenant
Getting help
Questions or spec-shape feedback: amir@dallal.me, or open a
NEEDS_INPUT/external-tenant-<topic>.md in the repo.