Custom Storefront Integration Guide

Audience: Tenant admins, engineers, and DevOps building a custom customer website on your own domain.

Purpose: Public Storefront API reference — authentication, endpoints, checkout flow, prescriptions, and product detail fields.

Setup first: Connect your storefront — API key, scopes, routing, and screenshots.

This guide covers public integration only — HTTP endpoints, headers, and response shapes your website calls.

Role	Use this guide to…
Tenant admin	Understand what your shop needs from Ailaaj One before go-live
Engineer / agency	Integrate catalog, cart, checkout, login, and prescriptions
DevOps	Configure environment variables on your hosting platform

1. How it fits together

Your customer website has no product or order database of its own. It calls Ailaaj One for everything:

https://{your-ailaaj-one-host}/api/storefront?tenant_id=<your-tenant-uuid>

flowchart LR
  subgraph shop ["Your customer website"]
    UI["Shop UI"]
    SERVER["Your server / SSR layer"]
  end

  subgraph ailaaj ["Ailaaj One — Storefront API"]
    API["/api/storefront"]
  end

  UI --> SERVER
  SERVER -->|"API key + tenant_id"| API
  API -->|"JSON success / error envelope"| SERVER
  SERVER --> UI

Every response uses the same envelope:

{ "success": true, "data": { ... } }

{ "success": false, "error": { "code": "...", "message": "..." } }

Keep your API key on the server. Catalog reads may be proxied through your backend; cart, checkout, and account writes should never expose the key in the browser.

2. Authentication

Every Storefront API call requires:

Item	Where	Example
Tenant	Query string	`?tenant_id=<your-tenant-uuid>`
API key	Header	`X-API-Key: <your-storefront-api-key>` or `Authorization: Bearer <key>`

Logged-in customer routes also require:

Item	Where	When
Session token	Header `X-Storefront-Session: <token>`	After `POST /auth/login` or `/auth/register`

Scopes on your API key control what the key can do. A full shop needs all four: products:read, stock:read, orders:read, orders:write. See Connect your storefront for how to create the key and bind checkout routing.

3. Public API overview

All paths are relative to /api/storefront. Full method list and curl examples: Connect your storefront.

Catalog and search (`products:read`)

Method	Path	Purpose
GET	`/config`	Checkout defaults (store, warehouse, shipment, payments) bound to your API key
GET	`/categories`	Top navigation and collection tree
GET	`/categories/{slug}`	One storefront category
GET	`/products`	Product listing — filters, search, pagination
GET	`/products/{slug}`	Product detail page (PDP)
GET	`/products/{slug}/alternates`	Ingredient-matched alternates
GET	`/products/{slug}/reviews`	Product reviews
GET	`/product-search`	Fast product search
GET	`/product-filters`	Filter facets for listings
GET	`/brands`	Brand list

Cart and orders

Method	Path	Scope	Purpose
POST	`/cart/quote`	`stock:read`	Validate cart lines, stock, and price before checkout
POST	`/orders`	`orders:write`	Place an order
POST	`/orders/track`	`orders:read`	Track order by number (guest)
GET	`/orders/confirmation`	—	Read confirmation state (magic link)
POST	`/orders/confirmation`	—	Confirm order (magic link)

Customer account

Method	Path	Purpose
POST	`/auth/register`	Create account
POST	`/auth/login`	Sign in
POST	`/auth/logout`	Sign out
GET	`/auth/me`	Current customer
POST	`/auth/password-reset/request`	Request reset OTP by email
POST	`/auth/password-reset/confirm`	Set new password with OTP
GET	`/me`	Account summary
PATCH	`/me/profile`	Update name, email, phone
PATCH	`/me/password`	Change password
GET / POST / PATCH / DELETE	`/me/addresses`	Saved addresses
GET	`/me/orders`	Order history
GET	`/me/orders/{id}`	Order detail
GET / POST	`/me/prescriptions`	Prescription uploads
POST	`/me/prescriptions/upload-url`	Get upload URL for Rx file
GET / PATCH	`/me/notifications`	Email / WhatsApp preferences

4. Typical checkout flow

sequenceDiagram
  participant Shop as Your website
  participant API as Storefront API

  Shop->>API: GET /config
  API-->>Shop: Shipment + payment options

  Shop->>API: POST /cart/quote
  API-->>Shop: Priced lines, Rx policy

  Note over Shop: Collect address, payment, Rx if required

  Shop->>API: POST /orders
  API-->>Shop: order_number, status

Suggested call order

GET /config — load shipment and payment methods from your API key routing.
POST /cart/quote — send line items; receive prices, stock errors, and whether a prescription is required.
POST /orders — submit customer details, address, payment choice, and optional prescription document URLs.

Orders created through this API appear in Ailaaj One Order Management with source API / custom storefront.

5. Prescription handling

POST /cart/quote returns a prescription_policy per line. Your checkout UI should react as follows:

Policy	Meaning	Your checkout
`none`	Regular product	No Rx step
`relaxed`	Relaxed OTC	Optional prescriber name / PMDC
`narcotic` or `rx_required`	Controlled / Rx	Prescription upload required

Upload options

Attach rx_document_urls on POST /orders during checkout, or
After login: POST /me/prescriptions/upload-url → upload file → POST /me/prescriptions

6. Product detail (PDP) fields

GET /products/{slug} returns data.product.pdp. Useful fields for your product page:

JSON field	Content
`overview.productOverview`	Product overview text
`overview.uses`	Uses / indications
`overview.warningsAndInteractions`	Warnings and interactions
`overview.dosage`	Dosage guidance
`sideEffects`	Common side effects
`storage`	Storage instructions
`faq`	FAQ entries

Configure this content in Ailaaj One PIMS (product descriptions and storefront content). Your website only reads it through the API.

7. Environment variables

Set on your customer website host (not in this guide’s Ailaaj One admin steps — those are in Connect your storefront).

Required

Variable	Purpose
`VITE_STOREFRONT_API_BASE_URL`	`https://{your-ailaaj-one-host}/api/storefront`
`VITE_STOREFRONT_TENANT_ID`	Your tenant UUID
`STOREFRONT_SERVER_API_TOKEN`	Your Storefront API key (server-side only)
`VITE_STOREFRONT_SITE_URL`	Public shop URL

Optional

Variable	Purpose
`VITE_STOREFRONT_API_KEY`	Only if catalog is proxied from the client build — prefer server-side
`HUB_INTERNAL_BASE_URL`	Alternate internal API origin for SSR

8. Go-live checklist

In Ailaaj One

Storefront API key with all four scopes and routing defaults (setup guide)
Storefront domain registered for confirmation links
Storefront Categories and products visible online in PIMS

On your website

API base URL, tenant ID, and server API token configured
Public shop URL matches your live domain
DNS / hosting points your domain at the shop

9. Troubleshooting

Symptom	What to check
`401` / `403`	API key, tenant ID, and scopes on the key
Empty category	Storefront Categories and product visibility in Ailaaj One
Quote fails on stock	Routing on the API key — warehouse must match available stock
Login OK, account routes fail	Send `X-Storefront-Session` on `/me/*` and `/auth/me`
Confirmation link broken	Public shop URL and storefront domain in Ailaaj One
No email / WhatsApp	Customer notification preferences; hub notification setup

Guide	Contents
Connect your storefront	API key, scopes, routing, screenshots, `curl` verification
Release notes v1.1.0	Recent storefront changes
Cloudflare routing	Custom domain routing (if you use Cloudflare)