@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-apiConventions
- Request and response bodies are JSON.
- Money is serialized as an object containing integer minor-unit
amount,currency, and a display-orientedformattedvalue. - Product and cart transformers include only relationships preloaded by the controller.
- Validation failures return
422 E_VALIDATION_ERRORwithdetails.messages. - Core and extension commerce failures use the stable envelope below; unique-record conflicts return
409 E_RESOURCE_CONFLICTwithout SQL details. - Route paths in this page include the
/api/commerceprefix.
{
"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/:slugReturns 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/cartFor 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/:providercommerceRawBody 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.