Tenant-facing API

Every route below is reached with a tenant credential (an fdk_-prefixed API key, Authorization: Bearer <key>), resolved to a tenant_ref per credential-carries-ownership — never a path or body parameter. This page describes the real route handlers as they exist in the modules today; it is not a hand-written OpenAPI spec, and it will grow as the headless SDK effort formalizes it.

This page is maintained by hand and can drift. The machine-generated, always-current contract for the public storefront and merchant fdk_ surface is the OpenAPI document the API serves directly: browse the interactive reference at https://api.ruo.pro/docs and fetch the raw spec at https://api.ruo.pro/openapi.json (ADR 0007). Internal operator routes are deliberately not part of that contract and are undocumented there.

Self-serve store management — stores module

/v1/my/* — store-owner routes, authenticated by verifyTenantAuth (the tenant credential, rate-limited on verification attempts before the DB lookup — an fdk_ key is online-guessable with no limiter otherwise).

The draft-to-publish-to-rollback lifecycle, the manifest shape, signed preview tokens, and the RUO claim-scan gate are covered in full on the Site builder page.

Merchant API — merchant-api module

/v1/merchant/* — owns no Postgres schema of its own; it is pure composition over several other modules’ published repo factories (createStoresRepo, createCommerceRepo, createOutboundWebhooksRepo, and the persons/merchant-billing repos), each scoped to the credential’s tenant_ref. Scopes are enforced per route via requireScope(...).

Merchant order actions — checkout module

/v1/merchant/orders/:id/* — the money-path inverse actions on the merchant’s OWN orders (scope manage:own_orders, distinct from read:own_orders so a read-only key can never move money). Both drive the same executors as the operator refund/cancel routes; the card charge is derived server-side from the order (no charge_id in the request) and the idempotency keys are deterministic per order, so a retried click replays instead of refunding twice.

Checkout — checkout module

/v1/tenants/:tenant/checkout* — an honesty note on tenancy: unlike the fdk_ routes above, the checkout placement route does not derive the tenant from the credential. The x-storefront-token accepted on the bare checkout path (requireCheckoutCaller) is a platform-wide but checkout-only credential — the tenant is taken from the :tenant path segment. Folding it into per-tenant fdk_ credentials with a narrow checkout scope is planned but not shipped. The order-action routes beneath it (/checkout/orders/*) are operator-token-gated today. All mutating routes require an Idempotency-Key header — a retried request with the same key replays the original outcome rather than double-charging (see Money invariants).

Public storefront catalog — commerce module

/v1/tenants/:tenant/catalog/* — no operator token, no tenant credential. This is the one deliberately public read surface: a storefront’s product catalog. A draft/archived product, or a draft/suspended tenant’s catalog, is unreachable here even by direct ID/slug guess — enforced at the query layer, not just the UI.

A note on throttling: these public catalog reads are currently unthrottled — there is no per-caller rate limit on them today. Some management and operator routes do return 429 with a retry-after header when a limiter is spent. Client code should handle 429 defensively (respect retry-after, back off) everywhere, rather than assuming any route’s current behavior is permanent.

This is the exact route the storefront fleet renderer’s manifest-source resolves against for host -> tenant lookups, and the route ADR 0003 commits to as contract identity for the future headless SDK: the renderer binds to the same types, same tenancy resolution, and same error surface a headless caller would use — it just invokes them in-process today instead of over the network.

The product shape

Each catalog product carries integer-cents prices and its variants. Media is returned in two forms so no consumer has to re-implement asset resolution:

Products that carry a gallery also return an images[] array; each entry has a raw asset_ref and, alongside it, the resolved url — the same two-form pattern as the top-level fields.

{
  "product": {
    "slug": "bpc-157",
    "name": "BPC-157",
    "status": "active",
    "image_asset_ref": "asset:ruo-demo/3f8a…e1.png",
    "image_url": "https://assets.ruo.pro/stores/ruo-demo/assets/3f8a…e1.png",
    "is_subscription": true,
    "subscription_interval": "month",
    "subscription_interval_count": 1,
    "subscription_price_cents": 4499,
    "variants": [
      { "id": "var_…", "sku": "NOVA-BPC-5MG", "label": "5mg vial", "price_cents": 4999, "currency": "USD" }
    ]
  }
}

How image resolution works

The platform resolves a <store> ref to a fetchable URL by rewrite, with no call into the media module (the module-boundary rule holds — see Media):

asset:<store>/<sha256>.<ext>  ->  <ASSET_BASE_URL>/stores/<store>/assets/<sha256>.<ext>

The rewrite is driven by the API’s ASSET_BASE_URL. It is honest about absence: when no image is set, the base is unconfigured, or the ref is malformed, image_url is null — never a broken or guessed URL. Clients should prefer image_url and fall back to resolving image_asset_ref themselves only if they have a reason to.

What’s not here yet

payments and inventory have no tenant-self-serve routes yet — every route in those modules today is operator-gated (x-operator-token), because no consuming module calls them on a tenant’s behalf yet. persons is the same: operator-gated, consumed by other modules and operator tooling, not directly by an end shopper with a tenant key.