Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.stella-commerce.com/llms.txt

Use this file to discover all available pages before exploring further.

A Customer Access Token (cust_…) represents a logged-in shopper. It’s scoped to one customer within one merchant; you cannot use a customer token across merchants.

​
Get one

curl -X POST \
     -H "X-Site-ID: kasa" \
     -H "X-Stella-Token: stk_live_..." \
     -H "Content-Type: application/json" \
     -d '{"email": "shopper@example.com", "password": "..."}' \
     https://api-dev-app.stella-commerce.com/api/storefront/customer/login

{
  "access_token": "cust_01HXYZ...",
  "expires_at": "2026-05-08T13:00:00Z",
  "customer": { "id": "...", "email": "shopper@example.com" }
}
The same shape is returned by POST /api/storefront/customer/register.

​
Use it

Customer tokens go in the Authorization header alongside the storefront token. The merchant-tier token identifies the tenant; the customer token identifies the shopper within that tenant. 
curl -H "X-Site-ID: kasa" \
     -H "X-Stella-Token: stk_live_..." \
     -H "Authorization: Bearer cust_01HXYZ..." \
     https://api-dev-app.stella-commerce.com/api/storefront/customer/me

​
What it permits

Endpoint familyVerbs
/customer/meGET, PATCH
/customer/me/ordersGET (list, detail)
/customer/me/addressesGET, POST, PATCH, DELETE, set-default
/customer/me/agent-consentGET, POST (approve/deny)
/customer/me/agentsGET (list), DELETE (revoke), audit

​
Lifetime

Customer tokens are short-lived (default: 24 hours) and renewable via POST /api/storefront/customer/token/renew. Renewal rotates the value and extends the expiry; the old value is revoked immediately.

​
Revocation

Three paths:
  • Customer logs out — POST /customer/logout revokes the current token.
  • Customer revokes a session — from the dashboard’s “Active sessions” panel (Phase 3-A).
  • Merchant revokes a session — same panel, merchant-side.
Revocation takes effect on the next request.

​
Account lockout

After repeated failed login attempts the account locks. The dashboard’s customer detail page shows lockout state; the Reset failures button clears it.

​
Recovery flow

# Step 1 — request a reset email
curl -X POST -H "X-Site-ID: kasa" -H "X-Stella-Token: stk_live_..." \
  -d '{"email": "shopper@example.com"}' \
  https://api-dev-app.stella-commerce.com/api/storefront/customer/recover

# Step 2 — consume the reset token from the email
curl -X POST -H "X-Site-ID: kasa" -H "X-Stella-Token: stk_live_..." \
  -d '{"reset_token": "...", "new_password": "..."}' \
  https://api-dev-app.stella-commerce.com/api/storefront/customer/reset
The recover endpoint returns 202 whether or not the email exists — ghost-account probing is not possible.