Skip to content

Storefront REST API

@adocommercekit/storefront-api publishes 27 host-owned endpoints under /api/commerce.

@adocommercekit/storefront-api publishes 27 host-owned endpoints under /api/commerce. The package is optional: install it when its REST contract is a useful starting point, then change the generated controllers, validators, middleware, and routes in the host application.

pnpm add @adocommercekit/storefront-api
node ace configure @adocommercekit/storefront-api

Conventions

  • Request and response bodies are JSON.
  • Money is serialized as an object containing integer minor-unit amount, currency, and a display-oriented formatted value.
  • Product and cart transformers include only relationships preloaded by the controller.
  • Validation failures return 422 E_VALIDATION_ERROR with details.messages.
  • Core and extension commerce failures use the stable envelope below; unique-record conflicts return 409 E_RESOURCE_CONFLICT without SQL details.
  • Route paths in this page include the /api/commerce prefix.
{
  "error": {
    "code": "E_INSUFFICIENT_STOCK",
    "message": "Insufficient stock",
    "details": {
      "available": 1
    }
  }
}

Branch on error.code, not the human-readable message. See Troubleshooting for common codes.

Services also return typed 422 E_INVALID_INPUT, 404 E_COMMERCE_NOT_FOUND, and 409 E_RESOURCE_CONFLICT errors for invalid domain input, missing resources, and conflicts respectively. These are distinct from request-validator failures.

Endpoint summary

Method Path Route name Input
GET /api/commerce/products commerce.products.index Query filters
GET /api/commerce/products/:slug commerce.products.show Product slug
GET /api/commerce/customer commerce.customer.show Authenticated user
PATCH /api/commerce/customer commerce.customer.update Authenticated user + profile
GET /api/commerce/customer/export commerce.customer.export Authenticated user
POST /api/commerce/customer/addresses commerce.customer.addresses.store Authenticated user + address
PATCH /api/commerce/customer/addresses/:id commerce.customer.addresses.update Owned address + partial address
DELETE /api/commerce/customer/addresses/:id commerce.customer.addresses.destroy Owned address
GET /api/commerce/cart commerce.cart.show Cart credential
POST /api/commerce/cart/lines commerce.cart.lines.store { variantId, quantity }
PATCH /api/commerce/cart/lines/:id commerce.cart.lines.update { quantity }
DELETE /api/commerce/cart/lines/:id commerce.cart.lines.destroy Line ID
PUT /api/commerce/cart/email commerce.cart.email { email }
PUT /api/commerce/cart/addresses commerce.cart.addresses { shipping?, billing? }
GET /api/commerce/cart/shipping-methods commerce.cart.shippingMethods Cart credential
PUT /api/commerce/cart/shipping-method commerce.cart.shippingMethod { methodId }
POST /api/commerce/cart/shipping-quotes commerce.cart.shippingQuotes { provider }
PUT /api/commerce/cart/shipping-quote commerce.cart.shippingQuote { token }
POST /api/commerce/checkout commerce.checkout.place Payment selection
GET /api/commerce/orders commerce.orders.index Authenticated user
GET /api/commerce/orders/:number commerce.orders.show Guest token or authenticated user
GET /api/commerce/orders/:number/payment-instructions commerce.orders.paymentInstructions Same order authorization
GET /api/commerce/returns/reasons commerce.returns.reasons Authenticated user
GET /api/commerce/returns commerce.returns.index Authenticated user + cursor
GET /api/commerce/returns/:id commerce.returns.show Owned return request
POST /api/commerce/returns commerce.returns.store Owned order lines + reasons
POST /api/commerce/webhooks/payments/:provider commerce.webhooks.payments Raw provider body

Optional package endpoints

These 15 routes are separate publications, not part of the 27-route storefront contract. All paths retain the /api/commerce prefix.

Package Method Path Route name
Promotions POST /api/commerce/cart/coupons commerce.cart.coupons.apply
Promotions DELETE /api/commerce/cart/coupons/:code commerce.cart.coupons.remove
Store credit POST /api/commerce/cart/gift-card commerce.giftCards.apply
Store credit DELETE /api/commerce/cart/gift-card commerce.giftCards.remove
Store credit POST /api/commerce/gift-cards/balance commerce.giftCards.balance
Engagement GET /api/commerce/wishlists Unnamed
Engagement POST /api/commerce/wishlists Unnamed
Engagement GET /api/commerce/wishlists/:listId/items Unnamed
Engagement POST /api/commerce/wishlists/:listId/items Unnamed
Engagement DELETE /api/commerce/wishlists/:listId/items/:itemId Unnamed
Engagement POST /api/commerce/wishlists/:listId/items/:itemId/cart Unnamed
Engagement GET /api/commerce/products/:productId/reviews Unnamed
Engagement GET /api/commerce/products/:productId/rating Unnamed
Engagement PUT /api/commerce/products/:productId/reviews Unnamed
Preorders GET /api/commerce/variants/:variantId/preorder commerce.preorders.show

See Promotions, Store credit, Engagement, and Preorders for their inputs and ownership rules. The store-credit package intentionally retains gift-card route and service names. Balance lookup uses POST so secret codes do not appear in URL logs.

Products

List products

GET /api/commerce/products?page=1&perPage=24&categorySlug=apparel&q=shirt&sort=name
Query Default Constraint
page 1 Integer from 1 through 50; use cursors for deeper navigation
cursor none Opaque keyset/search-driver cursor
perPage 24 Integer from 1 through 100
categorySlug none Maximum 255 characters
q none Name, slug, or variant-SKU search; maximum 255 chars
sort name name or newest

Only active products assigned to the selected channel are returned. Without a configured search driver, the service uses an escaped database LIKE fallback; Meilisearch and Typesense adapters provide external indexing. Responses include nextCursor alongside page metadata. meta.total and meta.lastPage are omitted when the driver cannot estimate a total; do not invent a page count. SQL search totals are exact through 1,000 matches and omitted above that bound.

Meilisearch/Typesense bootstrap failures clear the cached initialization promise so later calls can retry; they do not permanently poison the process. New Typesense collections mark name and createdAt as sortable. For a host-owned preexisting collection, review its sorting schema during upgrade before expecting name/newest queries to work.

Show a product

GET /api/commerce/products/:slug

Returns one active product for the default channel. A missing, inactive, or inaccessible product returns:

{
  "error": {
    "code": "E_PRODUCT_NOT_FOUND",
    "message": "Product not found"
  }
}

Cart credentials

Cart endpoints can be anonymous. With the generated sessionCartToken() configuration, GET /cart creates or resolves an opaque token in the Adonis session. Browsers must send credentials; command-line clients must reuse a cookie jar:

curl -c .cart-cookie -b .cart-cookie \
  http://localhost:3333/api/commerce/cart

For a stateless client, configure headerCartToken(). Read the opaque token returned by the cart transformer and send it in the configured header. A cart database ID is not a valid credential.

Every cart mutation returns the refreshed cart, including recalculated lines, adjustments, totals, and currently preloaded relationships.

With @adocommercekit/promotions, the core cart transformer also exposes a promotions feedback array. Render its eligibility feedback rather than assuming an entered coupon produced an adjustment.

Cart lines

Add a line:

{
  "variantId": "5fca3a83-9235-4779-b862-0fd59d450503",
  "quantity": 2
}

variantId must be a UUID. quantity must be an integer from 1 through 999.

Update a line:

{
  "quantity": 3
}

An update quantity may be 0 through 999; zero removes the line through the service contract. DELETE /cart/lines/:id removes it explicitly.

The service locks and recalculates the cart for each mutation. Price and availability can therefore change between requests.

Email and addresses

Set email:

{
  "email": "buyer@example.com"
}

Set one or both addresses:

{
  "shipping": {
    "firstName": "Ari",
    "lastName": "Stone",
    "company": "Example Co",
    "line1": "18 Market Street",
    "line2": "Suite 4",
    "city": "Portland",
    "region": "OR",
    "postalCode": "97205",
    "countryCode": "US",
    "phone": "+1 555 0100"
  },
  "billing": {
    "firstName": "Ari",
    "lastName": "Stone",
    "line1": "18 Market Street",
    "city": "Portland",
    "region": "OR",
    "postalCode": "97205",
    "countryCode": "US"
  }
}

firstName, lastName, line1, city, and a two-letter countryCode are required on each supplied address. postalCode is required for countries listed by the published validator. The validator is host-owned; change it if the application’s address contract differs.

Authenticated customers can read and update their commerce profile, create/update/delete only their own saved addresses, and download the minimized core portability document from GET /customer/export. Every operation derives ownership from auth.user.id; unauthenticated requests receive 401, while address IDs owned by another customer are not exposed.

Customer identity is linked exclusively by userId, never by a matching email. The helper checks lazy session authentication before resolving the customer. A new user-linked customer can initially have no email; it does not claim an existing customer row using the cart’s email. An authenticated attempt to use another customer’s cart or checkout returns 409 E_RESOURCE_CONFLICT.

Customer and cart addresses share postal-code validation. Profile email collisions are conflicts (409), not internal errors. A customer may have at most 50 saved addresses; partial address updates validate the resulting country/postal-code combination.

Shipping

GET /cart/shipping-methods evaluates eligibility and calculates a storefront price for every returned method using the current cart.

Select one with:

{
  "methodId": "f8398380-d6a0-4b6a-bf06-4f36c34a3150"
}

The ID must be a UUID. Selection recalculates the cart. A method can become ineligible when the address or cart contents change; list methods again after either change.

Dynamic providers use POST /cart/shipping-quotes with { "provider": "<code>" }, then PUT /cart/shipping-quote with the returned signed { "token": "..." }. Selection verifies the token against the current cart and recalculates shipping before checkout.

Checkout

POST /api/commerce/checkout
Content-Type: application/json
Idempotency-Key: checkout-01J...
{
  "payment": {
    "method": "manual"
  }
}

Payment input:

Field Required Meaning
payment.method Yes Key registered in config/commerce.ts
payment.token No Provider token, such as a Stripe PaymentMethod ID; maximum 2,000 characters
payment.intentId No Existing Adocommerce Kit payment-intent UUID for a host-defined resumed flow
shippingQuoteToken No Signed token previously selected through a dynamic shipping integration; maximum 8,000 characters

Send a unique Idempotency-Key for every logical checkout attempt. Repeating the same key and payload returns the same completed result. Reusing a key with a different payload returns E_IDEMPOTENCY_CONFLICT.

Success sets status 201 and returns the storefront order with a seven-day accessToken for guest retrieval. Checkout can reject stale prices, stock changes, shipping ineligibility, payment failures, or a non-active cart. Refresh the cart and show the specific error rather than blindly retrying.

Synchronous providers preserve the original authorize/capture checkout. Deferred providers return an order in pending_payment; COD returns pending_cod. Payment instructions and their expiry are included in the order response. Read the Stripe SCA limitation before using it for cards that may require additional customer action.

An order with zero grand total completes as paid without creating a payment intent or calling an external payment provider. Inventory, transactional checkout hooks, order events, and configured automatic confirmation still run.

Authenticated customers can list their own paginated history with GET /orders?page=1&perPage=20. Guest access remains restricted to the signed-token detail route.

Read an order

Guest order:

GET /api/commerce/orders/:number?token=<access-token>

The signed token must identify the same internal order ID and public number. The generated checkout token expires after seven days.

An authenticated user is also authorized when the order customer has a userId equal to String(auth.user.id). Adapt the host-owned controller when the application uses another ownership model.

Missing and unauthorized orders both return 404 E_ORDER_NOT_FOUND; the endpoint does not reveal whether an order number exists.

Read payment instructions

GET /api/commerce/orders/:number/payment-instructions?token=<access-token>

This endpoint repeats the exact same guest-token or authenticated-customer ownership check as the order endpoint. Cross-order tokens and unauthorized customers receive 404 E_ORDER_NOT_FOUND.

The response is a discriminated array whose type is virtual_account, qr_code, redirect, retail_outlet, or bank_transfer. Every instruction includes id and expiresAt; variant fields contain only displayable payment data. Provider raw payloads and encrypted client secrets are never transformed.

Returns

Authenticated customers can list return reasons, request a return against their own delivered order lines, and read only their own return requests. POST /returns accepts an order ID and unique line entries containing orderLineId, positive quantity, reasonId, and an optional note. Core locks the order and lines and rejects aggregate quantities above the delivered, unrefunded amount.

Operational workflows use ReturnService to authorize receipt, record inspection quantities and disposition, approve or reject, issue a line-aware refund, create an exchange order, and close the request. Refund usage and order-line refunded quantities are committed idempotently.

Webhooks

POST /api/commerce/webhooks/payments/:provider

commerceRawBody converts Adonis’s preserved request.raw() value to UTF-8 bytes. Signature verification occurs before normalization. Verified duplicates and unhandled events return 200; signature failures return 400.

If Shield is enabled, exempt /api/commerce/webhooks/payments/* from CSRF. Do not exempt authenticated browser routes without choosing another CSRF defense. See Stripe payments and operations.

Rate limits

Generated routes apply fixed-window limits. Cart and checkout scopes use the configured cart-token strategy, falling back to client IP when no token is available; order reads are IP-scoped.

Scope Limit Routes
product-read 240/min Product list/detail
cart-mutation 120/min Cart mutations (including shipping quotes) and customer profile/address mutations
checkout 10/min Checkout
order-read 60/min Order list/detail and payment instructions
customer-export 5/hour Customer export
return-read 60/min Return reasons/list/detail
return-mutation 10/min Return requests
payment-webhook 240/min Payment webhooks
coupon-mutation 30/min Optional promotion coupon apply/remove
gift-card 10/min Optional store-credit apply/remove/balance
engagement 120/min All optional wishlist/review/rating routes
preorder-availability 120/min Optional preorder availability

Cart reads, shipping-method reads, and customer profile reads have no generated rate limit. Only scopes beginning with cart and the checkout scope use cart-token keys; all other scopes use client IP. Responses passing through the limiter include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset; a rejection is 429 E_RATE_LIMITED with details.retryAfter and a Retry-After header.

The default MemoryRateLimitStore is process-local and bounded to 10,000 keys. It evicts least-recently-used counters when full, which can reset a client’s window; it is not a distributed security boundary. For multiple instances, bind STOREFRONT_RATE_LIMIT_STORE to a singleton RedisRateLimitStore in a host provider, retaining route policies and correct proxy trust:

import {
  RedisRateLimitStore,
  STOREFRONT_RATE_LIMIT_STORE,
} from '@adocommercekit/storefront-api'

// redis is the host's Redis client.
app.container.singleton(STOREFRONT_RATE_LIMIT_STORE, () => new RedisRateLimitStore(redis))

The adapter requires eval(script, numberOfKeys, ...args) and atomically increments/sets expiry. The package imposes no Redis dependency.

CSRF, CORS, and ownership

The configurator only excludes external payment webhooks from standard Shield CSRF checks. Browser cart and checkout requests remain subject to the host application’s CSRF and CORS policy.

The generated files are a starting contract with customer ownership checks and bounded rate limits enabled. Add authentication, cache headers, locale selection, observability, and response extensions directly in the application. Run commerce:upgrade after package changes; conflicts are staged under .commercekit/incoming, never overwritten.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close