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 products:read, stock:read, orders:read, orders:write, plus checkout-sessions:read, checkout-sessions:write, customers:read, customers:write, and prescriptions:write when accounts and abandoned checkout are enabled. 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	`/products/{slug}/auto-refill`	Auto-Refill preview for one product
GET	`/product-search`	Fast product search
GET	`/product-filters`	Filter facets for listings
GET	`/brands`	Brand list
POST	`/notify-requests`	Notify-me when a product is back in stock

Cart and OMS orders

POST /orders is the call that creates the order in Order Management. It uses the store, warehouse, shipment, payments, and order source saved on the API key (Custom Storefront is source api).

Method	Path	Scope	Purpose
POST	`/cart/quote`	`stock:read`	Validate lines, stock, tax, shipping, and prescription policy
POST	`/orders`	`orders:write`	Create the OMS order. Response `data.order.order_number`
POST	`/orders/upload-url`	`orders:write`	Presigned prescription upload. Put `public_url` in `rx_document_urls`
GET	`/orders/confirmation`	—	Read confirmation state (`order_number` + `token`)
POST	`/orders/confirmation`	—	Confirm the order (magic link)
POST	`/checkout-sessions`	`checkout-sessions:write`	Save contact, cart, and checkout step
GET	`/checkout-sessions/resume`	`checkout-sessions:read`	Resume with query `session`
GET / POST	`/api/external/checkout-sessions`	`checkout-sessions:read`	Abandoned-session list and recovery mark

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`	OMS order history (`orders:read`)
GET	`/me/orders/{id}`	OMS order detail (`orders:read`)
GET / POST	`/me/prescriptions`	Prescription uploads
POST	`/me/prescriptions/upload-url`	Get upload URL for Rx file
GET / PATCH	`/me/notifications`	Email / WhatsApp preferences
GET / POST	`/me/auto-refill`	List or create Auto-Refill plans
GET / PATCH	`/me/auto-refill/{referenceCode}`	Plan detail and edits
POST	`/me/auto-refill/{referenceCode}/pause`	Pause a plan
POST	`/me/auto-refill/{referenceCode}/skip`	Skip the next cycle
POST	`/me/auto-refill/{referenceCode}/cancel`	Cancel a plan

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, payment methods, and routing.omsSource from the API key.
POST /cart/quote — send { slug, qty } lines; receive prices, stock, and prescription_policy.
If a prescription is required, POST /orders/upload-url, upload the file, and keep public_url.
POST /orders — customer name, phone, address, city, payment_kind (prepaid or cod), and optional rx_document_urls.

The response data.order.order_number is the OMS order. It appears in Order Management on the store and warehouse bound to the key, with the key’s order source (Custom Storefront / api).

While the customer is still in checkout, POST /checkout-sessions saves the cart. Placing the order with the same phone marks that session converted.

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 catalog, stock, order, checkout-session, and customer scopes, plus 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)