@adocommercekit/admin-api publishes 84 host-owned endpoints under /api/commerce/admin, plus the admin service layer both admin surfaces share. A headless host can stop here: everything the Inertia panel does is reachable through this contract.
pnpm add @adocommercekit/admin-api @adonisjs/bouncer
node ace configure @adocommercekit/admin-api
node ace migration:run
node ace commerce:doctorconfigure() requires config/commerce.ts and the core foundation, catalog, customers, orders/inventory, payments, admin-seams, returns and operational-depth migration publications. It does not require @adocommercekit/storefront-api. It publishes controllers, validators, middleware, policies, routes and the audit migration into your application and records publication baselines; shared services remain package imports.
WARNING — Every ability denies by default
The published policy stubs grant nothing. Implement
commerceAdminRoles()inapp/policies/commerce/main.tsbefore an operator can do anything; until you do, every endpoint answers403.commerce:doctorreports the unmapped state as a failure. See Abilities and policies.
Conventions
- Every request is authenticated. There is no anonymous admin route, metrics included; an unauthenticated request answers
401 E_UNAUTHORIZED. - Every route names an ability or a documented any-of set from the catalog and checks it before the controller body runs. A denial is
403 E_COMMERCE_FORBIDDENwith an ability indetails.ability— ability names are vocabulary, not secrets. - Shield/CSRF stays on. No admin route is exempt.
- Responses are JSON. Money renders as
{ amount, currency, formatted, amountMinor };amountMinoris the stringified integer minor-unit value, so charts and exports never parse a formatted string. - Everything serialized here goes through a transformer’s
forAdminvariant. Provider credentials, encrypted columns, raw provider payloads, and customer cart tokens never appear. - Rate limits are per resolved actor: mutations 60/min, metrics 120/min, other reads 240/min. Every response carries
X-RateLimit-*. - Validation failures answer
422with the commerce envelope anddetails.messages, never a redirect. - Channel restrictions come from the host’s
commerceAdminScope(actor, scope)hook, not clientchannelIdquery input.scope.channelIdderives from persisted membership; lists intersect trusted channel allowlists, bulk actions must satisfy every resource, and constrained access fails closed for unresolved/global membership.
{
"error": {
"code": "E_COMMERCE_FORBIDDEN",
"message": "Missing ability commerce.payments.refund",
"details": { "ability": "commerce.payments.refund" }
}
}Branch on error.code. Codes specific to this surface:
| Code | Status | Meaning |
|---|---|---|
E_UNAUTHORIZED |
401 | No authenticated actor. |
E_COMMERCE_FORBIDDEN |
403 | The actor lacks the endpoint’s ability. |
E_COMMERCE_INVALID_TRANSITION |
409 | The state machine refused; details.currentState carries the state the surface observed. |
E_IDEMPOTENCY_CONFLICT |
409 | An Idempotency-Key was reused with a different payload. |
E_VALIDATION_ERROR |
422 | The payload, or a value a service rejected, is invalid. |
E_INVALID_INPUT |
422 | A service rejected domain input. |
E_COMMERCE_NOT_FOUND |
404 | A domain resource does not exist. |
E_RESOURCE_CONFLICT |
409 | A resource conflicts with the requested operation. |
E_INVALID_CURSOR |
400 | A cursor is malformed or incompatible with its list context. |
E_RATE_LIMITED |
429 | The pre-authentication or actor rate budget was exhausted. |
Lists
Operational list endpoints use keyset pagination with the shape below. Small configuration collections (such as channels and webhook destinations) return arrays instead; consult each resource rather than requiring a cursor on every GET.
| Query | Default | Constraint |
|---|---|---|
limit |
25 |
Integer from 1 through 100 |
cursor |
none | Opaque cursor from a previous meta.nextCursor; malformed or sort/direction-mismatched cursors produce 400 E_INVALID_CURSOR, never a silent reset |
direction |
desc |
asc or desc |
sort |
per resource | See the resource’s filters |
{
"data": [],
"meta": { "nextCursor": "eyJ...", "total": 42 }
}meta.total is null when the filtered count is not obtainable cheaply; render that as “1–25 of many” rather than guessing.
Idempotency
Money-moving mutations accept an Idempotency-Key header of at most 128 characters. A replay returns the first response with Idempotent-Replay: true; reusing a key with a different payload is 409 E_IDEMPOTENCY_CONFLICT. Transfer completion/cancellation, return actions, reconciliation resolution, and delivery/dead-letter replay also use the persisted replay boundary. Keep the key for retries after a lost response; use a new key for a new logical operation.
The base REST controllers apply that boundary to order transition/cancel/adjustment, payment capture/refund/void, payment-operation resolution, shipment create/transition/cancel, inventory adjustment/receipt/cycle-count/transfer create/complete/cancel, every return mutation, webhook ping, delivery replay and dead-letter replay. Without the header, work runs without a persisted HTTP replay claim. Other mutations do not acquire this claim merely because they accept an HTTP request.
Audit trail
Every mutation writes one append-only entry in the same database transaction as its effect, so the record and the change commit or roll back together. Entries carry the actor id and label, the ability, the subject, a scalar-only before/after summary, the idempotency key, and the request id. Summaries are PII-free by construction: the service rejects a summary carrying a name, address, email, phone, or credential-shaped field.
Provider calls for capture/refund and return refund/exchange are not wrapped in an outer database transaction. Durable operation claims survive a caller rollback. The services’ onCommitted(result, trx) callback places the final ledger mutation and its audit record in the same transaction without holding a database transaction across a remote call. Bulk summaries record bounded counts and samples rather than every resource or any PII.
Read the trail through GET /api/commerce/admin/audit-entries, filterable by actorId, ability[], subjectType, subjectId, createdAfter, and createdBefore.
Endpoints
Catalog
| Method | Path | Route name | Ability |
|---|---|---|---|
GET |
/api/commerce/admin/products |
commerce.admin.products.index |
commerce.products.view |
POST |
/api/commerce/admin/products |
commerce.admin.products.store |
commerce.products.manage |
GET |
/api/commerce/admin/products/:id |
commerce.admin.products.show |
commerce.products.view |
PATCH |
/api/commerce/admin/products/:id |
commerce.admin.products.update |
commerce.products.manage |
DELETE |
/api/commerce/admin/products/:id |
commerce.admin.products.destroy |
commerce.products.manage |
POST |
/api/commerce/admin/products/:id/archive |
commerce.admin.products.archive |
commerce.products.manage |
POST |
/api/commerce/admin/products/bulk/status |
commerce.admin.products.bulk.status |
commerce.products.manage |
POST |
/api/commerce/admin/products/:id/options |
commerce.admin.products.options.store |
commerce.products.manage |
POST |
/api/commerce/admin/products/:id/variants/generate |
commerce.admin.products.variants.generate |
commerce.products.manage |
PUT |
/api/commerce/admin/products/:id/categories |
commerce.admin.products.categories |
commerce.products.manage |
POST |
/api/commerce/admin/products/:id/images |
commerce.admin.products.images.store |
commerce.products.manage |
PATCH |
/api/commerce/admin/products/:id/images/:imageId |
commerce.admin.products.images.update |
commerce.products.manage |
PUT |
/api/commerce/admin/products/:id/images/order |
commerce.admin.products.images.order |
commerce.products.manage |
DELETE |
/api/commerce/admin/products/:id/images/:imageId |
commerce.admin.products.images.destroy |
commerce.products.manage |
GET |
/api/commerce/admin/categories |
commerce.admin.categories.index |
commerce.products.view |
POST |
/api/commerce/admin/categories |
commerce.admin.categories.store |
commerce.categories.manage |
PATCH |
/api/commerce/admin/categories/:id |
commerce.admin.categories.update |
commerce.categories.manage |
DELETE |
/api/commerce/admin/categories/:id |
commerce.admin.categories.destroy |
commerce.categories.manage |
Image upload uses multipart/form-data with one through four images file fields. Each file may be
JPEG, PNG, or WebP and at most 4 MiB; the service verifies the actual bytes. Update accepts
{ altText?: string | null, variantIds?: string[] }. Reorder accepts every current image exactly once
as { imageIds: string[] }; omissions, duplicates, and foreign image ids are rejected. Upload and
delete audit entries are committed with their database changes, and managed objects are cleaned up on
rollback or after committed deletion.
Orders
| Method | Path | Route name | Ability |
|---|---|---|---|
GET |
/api/commerce/admin/orders |
commerce.admin.orders.index |
commerce.orders.view |
GET |
/api/commerce/admin/orders/:id |
commerce.admin.orders.show |
commerce.orders.view |
POST |
/api/commerce/admin/orders/:id/transition |
commerce.admin.orders.transition |
commerce.orders.transition |
POST |
/api/commerce/admin/orders/:id/cancel |
commerce.admin.orders.cancel |
commerce.orders.cancel |
POST |
/api/commerce/admin/orders/:id/adjustments |
commerce.admin.orders.adjustments.store |
commerce.orders.adjust |
GET |
/api/commerce/admin/orders/:id/payments |
commerce.admin.orders.payments.index |
commerce.payments.view |
Payments
| Method | Path | Route name | Ability |
|---|---|---|---|
POST |
/api/commerce/admin/payments/:id/capture |
commerce.admin.payments.capture |
commerce.payments.capture |
POST |
/api/commerce/admin/payments/:id/refund |
commerce.admin.payments.refund |
commerce.payments.refund |
GET |
/api/commerce/admin/payments/:id/captures |
commerce.admin.payments.captures.index |
commerce.payments.view |
POST |
/api/commerce/admin/payment-intents/:id/void |
commerce.admin.paymentIntents.void |
commerce.payments.void |
GET |
/api/commerce/admin/payment-operations |
commerce.admin.payments.operations.index |
commerce.payments.reconcile |
POST |
/api/commerce/admin/payment-operations/:id/resolve |
commerce.admin.payments.operations.resolve |
commerce.payments.reconcile |
Shipments
| Method | Path | Route name | Ability |
|---|---|---|---|
POST |
/api/commerce/admin/orders/:id/shipments |
commerce.admin.shipments.store |
commerce.shipments.manage |
POST |
/api/commerce/admin/shipments/:id/transition |
commerce.admin.shipments.transition |
commerce.shipments.manage |
POST |
/api/commerce/admin/shipments/:id/cancel |
commerce.admin.shipments.cancel |
commerce.shipments.manage |
Returns
| Method | Path | Route name | Ability |
|---|---|---|---|
GET |
/api/commerce/admin/returns |
commerce.admin.returns.index |
commerce.returns.view |
GET |
/api/commerce/admin/returns/:id |
commerce.admin.returns.show |
commerce.returns.view |
POST |
/api/commerce/admin/orders/:id/returns |
commerce.admin.returns.store |
commerce.returns.manage |
POST |
/api/commerce/admin/returns/:id/authorize |
commerce.admin.returns.authorize |
commerce.returns.manage |
POST |
/api/commerce/admin/returns/:id/cancel |
commerce.admin.returns.cancel |
commerce.returns.manage |
POST |
/api/commerce/admin/returns/:id/receive |
commerce.admin.returns.receive |
commerce.returns.manage |
POST |
/api/commerce/admin/returns/:id/inspect |
commerce.admin.returns.inspect |
commerce.returns.manage |
POST |
/api/commerce/admin/returns/:id/approve |
commerce.admin.returns.approve |
commerce.returns.manage |
POST |
/api/commerce/admin/returns/:id/reject |
commerce.admin.returns.reject |
commerce.returns.manage |
POST |
/api/commerce/admin/returns/:id/refund |
commerce.admin.returns.refund |
commerce.returns.manage |
POST |
/api/commerce/admin/returns/:id/exchange |
commerce.admin.returns.exchange |
commerce.returns.manage |
POST |
/api/commerce/admin/returns/:id/close |
commerce.admin.returns.close |
commerce.returns.manage |
Inventory
| Method | Path | Route name | Ability |
|---|---|---|---|
GET |
/api/commerce/admin/inventory/levels |
commerce.admin.inventory.index |
commerce.inventory.view |
POST |
/api/commerce/admin/inventory/adjustments |
commerce.admin.inventory.adjust |
commerce.inventory.adjust |
GET |
/api/commerce/admin/inventory/movements |
commerce.admin.inventory.movements.index |
commerce.inventory.view |
POST |
/api/commerce/admin/inventory/receipts |
commerce.admin.inventory.receipts.store |
commerce.inventory.adjust |
POST |
/api/commerce/admin/inventory/cycle-counts |
commerce.admin.inventory.cycleCounts.store |
commerce.inventory.adjust |
POST |
/api/commerce/admin/inventory/transfers |
commerce.admin.inventory.transfers.store |
commerce.inventory.adjust |
POST |
/api/commerce/admin/inventory/transfers/:id/complete |
commerce.admin.inventory.transfers.complete |
commerce.inventory.adjust |
POST |
/api/commerce/admin/inventory/transfers/:id/cancel |
commerce.admin.inventory.transfers.cancel |
commerce.inventory.adjust |
Customers
| Method | Path | Route name | Ability |
|---|---|---|---|
GET |
/api/commerce/admin/customers |
commerce.admin.customers.index |
commerce.customers.view |
GET |
/api/commerce/admin/customers/:id |
commerce.admin.customers.show |
commerce.customers.view |
POST |
/api/commerce/admin/customers/:id/anonymize |
commerce.admin.customers.anonymize |
commerce.customers.anonymize |
Channels and metrics
| Method | Path | Route name | Ability |
|---|---|---|---|
GET |
/api/commerce/admin/channels |
commerce.admin.channels.index |
commerce.products.view OR commerce.orders.view OR commerce.payments.view OR commerce.returns.view OR commerce.inventory.view OR commerce.customers.view OR commerce.metrics.view OR commerce.audit.view OR commerce.webhooks.view OR commerce.media.view OR commerce.promotions.view OR commerce.gift_cards.view |
GET |
/api/commerce/admin/price-lists |
commerce.admin.priceLists.index |
commerce.products.view |
GET |
/api/commerce/admin/shipping-methods |
commerce.admin.shippingMethods.index |
commerce.shipments.manage |
GET |
/api/commerce/admin/stock-locations |
commerce.admin.stockLocations.index |
commerce.inventory.view |
GET |
/api/commerce/admin/tax-zones |
commerce.admin.taxZones.index |
commerce.products.view |
GET |
/api/commerce/admin/tax-rates |
commerce.admin.taxRates.index |
commerce.products.view |
GET |
/api/commerce/admin/metrics/summary |
commerce.admin.metrics.summary |
commerce.metrics.view |
GET |
/api/commerce/admin/metrics/revenue |
commerce.admin.metrics.revenue |
commerce.metrics.view |
GET |
/api/commerce/admin/metrics/orders-by-status |
commerce.admin.metrics.ordersByStatus |
commerce.metrics.view |
GET |
/api/commerce/admin/metrics/top-products |
commerce.admin.metrics.topProducts |
commerce.metrics.view |
GET |
/api/commerce/admin/metrics/payment-mix |
commerce.admin.metrics.paymentMix |
commerce.metrics.view |
GET |
/api/commerce/admin/metrics/checkout-funnel |
commerce.admin.metrics.checkoutFunnel |
commerce.metrics.view |
GET |
/api/commerce/admin/metrics/low-stock |
commerce.admin.metrics.lowStock |
commerce.metrics.view |
Audit
| Method | Path | Route name | Ability |
|---|---|---|---|
GET |
/api/commerce/admin/audit-entries |
commerce.admin.audit.index |
commerce.audit.view |
Outbound webhooks and media
| Method | Path | Route name | Ability |
|---|---|---|---|
GET |
/api/commerce/admin/webhook-destinations |
commerce.admin.webhooks.destinations.index |
commerce.webhooks.view |
POST |
/api/commerce/admin/webhook-destinations |
commerce.admin.webhooks.destinations.store |
commerce.webhooks.manage |
PATCH |
/api/commerce/admin/webhook-destinations/:id |
commerce.admin.webhooks.destinations.update |
commerce.webhooks.manage |
DELETE |
/api/commerce/admin/webhook-destinations/:id |
commerce.admin.webhooks.destinations.destroy |
commerce.webhooks.manage |
POST |
/api/commerce/admin/webhook-destinations/:id/rotate-secret |
commerce.admin.webhooks.destinations.rotateSecret |
commerce.webhooks.manage |
POST |
/api/commerce/admin/webhook-destinations/:id/ping |
commerce.admin.webhooks.destinations.ping |
commerce.webhooks.manage |
GET |
/api/commerce/admin/webhook-deliveries |
commerce.admin.webhooks.deliveries.index |
commerce.webhooks.view |
POST |
/api/commerce/admin/webhook-deliveries/:id/replay |
commerce.admin.webhooks.deliveries.replay |
commerce.webhooks.replay |
GET |
/api/commerce/admin/dead-letters |
commerce.admin.webhooks.deadLetters.index |
commerce.webhooks.view |
POST |
/api/commerce/admin/dead-letters/:id/replay |
commerce.admin.webhooks.deadLetters.replay |
commerce.webhooks.replay |
GET |
/api/commerce/admin/media |
commerce.admin.media.index |
commerce.media.view |
POST |
/api/commerce/admin/media |
commerce.admin.media.store |
commerce.media.manage |
DELETE |
/api/commerce/admin/media/:id |
commerce.admin.media.destroy |
commerce.media.manage |
POST |
/api/commerce/admin/media/:id/products/:productId |
commerce.admin.media.attachProduct |
commerce.media.manage |
Optional package endpoints
These 28 routes are published by extensions and are not included in the 84-route admin-api contract. They use the same pre-authentication, authentication, ability and read/mutation rate-limit middleware.
| Package | Method | Path | Route name | Ability |
|---|---|---|---|---|
| Promotions | GET |
/api/commerce/admin/promotions |
commerce.admin.promotions.index |
commerce.promotions.view |
| Promotions | GET |
/api/commerce/admin/promotions/:id |
commerce.admin.promotions.show |
commerce.promotions.view |
| Promotions | GET |
/api/commerce/admin/promotions/:id/rules |
commerce.admin.promotions.rules |
commerce.promotions.view |
| Promotions | GET |
/api/commerce/admin/promotions/:id/codes |
commerce.admin.promotions.codes |
commerce.promotions.view |
| Promotions | POST |
/api/commerce/admin/promotions |
commerce.admin.promotions.store |
commerce.promotions.manage |
| Promotions | PATCH |
/api/commerce/admin/promotions/:id |
commerce.admin.promotions.update |
commerce.promotions.manage |
| Promotions | POST |
/api/commerce/admin/promotions/:id/end |
commerce.admin.promotions.end |
commerce.promotions.manage |
| Promotions | POST |
/api/commerce/admin/promotions/:id/rules |
commerce.admin.promotions.rules.store |
commerce.promotions.manage |
| Promotions | DELETE |
/api/commerce/admin/promotions/:id/rules/:ruleId |
commerce.admin.promotions.rules.destroy |
commerce.promotions.manage |
| Promotions | POST |
/api/commerce/admin/promotions/:id/codes |
commerce.admin.promotions.codes.store |
commerce.promotions.manage |
| Promotions | POST |
/api/commerce/admin/promotion-codes/:codeId/revoke |
commerce.admin.promotions.codes.revoke |
commerce.promotions.manage |
| Store credit | GET |
/api/commerce/admin/gift-cards |
commerce.admin.giftCards.index |
commerce.gift_cards.view |
| Store credit | GET |
/api/commerce/admin/gift-cards/:id/ledger |
commerce.admin.giftCards.ledger |
commerce.gift_cards.view |
| Store credit | POST |
/api/commerce/admin/gift-cards |
commerce.admin.giftCards.issue |
commerce.gift_cards.manage |
| Store credit | POST |
/api/commerce/admin/gift-cards/:id/disable |
commerce.admin.giftCards.disable |
commerce.gift_cards.manage |
| Store credit | POST |
/api/commerce/admin/gift-cards/:id/adjust |
commerce.admin.giftCards.adjust |
commerce.gift_cards.manage |
| Engagement | GET |
/api/commerce/admin/reviews |
Unnamed | commerce.reviews.moderate |
| Engagement | PATCH |
/api/commerce/admin/reviews/:id |
Unnamed | commerce.reviews.moderate |
| Preorders | GET |
/api/commerce/admin/preorders |
commerce.admin.preorders.index |
commerce.products.view |
| Preorders | POST |
/api/commerce/admin/preorders |
commerce.admin.preorders.store |
commerce.products.manage |
| Preorders | PATCH |
/api/commerce/admin/preorders/:id |
commerce.admin.preorders.update |
commerce.products.manage |
| Preorders | POST |
/api/commerce/admin/preorders/:id/activate |
commerce.admin.preorders.activate |
commerce.products.manage |
| Preorders | POST |
/api/commerce/admin/preorders/:id/pause |
commerce.admin.preorders.pause |
commerce.products.manage |
| Preorders | POST |
/api/commerce/admin/preorders/:id/release |
commerce.admin.preorders.release |
commerce.products.manage |
| Preorders | POST |
/api/commerce/admin/preorders/:id/cancel |
commerce.admin.preorders.cancel |
commerce.products.manage |
| Preorders | GET |
/api/commerce/admin/preorders/:id/allocations |
commerce.admin.preorders.allocations |
commerce.products.view |
| Preorders | POST |
/api/commerce/admin/preorder-allocations/:allocationId/fulfill |
commerce.admin.preorder-allocations.fulfill |
commerce.products.manage |
| Preorders | POST |
/api/commerce/admin/preorder-allocations/:allocationId/cancel |
commerce.admin.preorder-allocations.cancel |
commerce.products.manage |
Promotion mutations, store-credit issue/disable/adjust, and preorder create/update/lifecycle actions accept the persisted Idempotency-Key replay boundary. Store-credit issuance returns the plaintext code only on the initial response; a replay returns code: null. Review moderation accepts a state change and records an audit entry. See Promotions, Store credit, Engagement, and Preorders.
Metrics
Every metrics endpoint takes currency (required), from, and to as ISO 8601 instants, plus an optional channelId. metrics/revenue also takes interval (day, week, or month); metrics/top-products and metrics/low-stock take limit.
Amounts are stringified minor units. Revenue is derived from the payment ledger — captures minus refunds — not from order totals, so the dashboard reconciles with the PPN and ledger exports to the cent. There is no cross-currency aggregation: one currency per request, mirroring the ledger’s integrity rule.
Metrics receive trusted channelIds from the authorization hook; client query parameters cannot broaden them. An empty allowlist produces no rows, and channelId intersects the allowlist. Low-stock queries also accept locationId and include only tracked, channel-visible levels whose configured reorderPoint is crossed. Revenue uses successful capture timestamps (with legacy-payment fallback), UTC buckets and succeeded refunds; average value and top products use captured orders. Cart status is excluded from order-status counts.
Operational inputs and safety
- Inventory level search is literal SKU/variant-title matching; levels and movements obey channel constraints and context-bound cursors. Invalid quantities and missing inventory resources raise typed commerce 4xx errors.
- Order
placedBefore=YYYY-MM-DDincludes the complete UTC day, not only midnight. - Anonymization requires the exact confirmation string
ANONYMIZE <customer id>. It setsanonymizedAtand clears core customer/address PII, order/cart snapshots, local payment customer/method records, instruction details, intent secrets/metadata, raw ledger payloads and associated outbox/delivery bodies. The latter retain customer-ID-only tombstones. Financial facts and audit entries remain; provider-vault erasure is a separate host/provider duty.CustomerAnonymizedlets extensions scrub their own PII. CustomerService.lastActivityAt(ids)returns the greatest customerupdatedAt, orderplacedAt, or cartupdatedAtper customer (ornull), not merely the last order date.- Media listing uses
listPage({ query, cursor, limit })and the standard list envelope. Search treats wildcard characters literally. Client filenames are limited to 255 characters; product attachment locks the product before enforcing its image cap. Admin DTOs omit storage keys, disks and private metadata.
Webhook and outbox administration
Enable the transactional outbox before creating or activating a destination. Destination DTOs mask custom header values and omit both plaintext and encrypted signing secrets. Custom headers are stored encrypted; on update, omitted headers preserves the set, null removes it, and an object replaces it. rotateSecret(id) returns the new plaintext secret once; protect that response. ping(id) sends a test delivery.
Destination URLs require HTTPS without embedded credentials; localhost HTTP requires explicit allowLocalhost development opt-in. Before delivery, the service resolves DNS and rejects private/reserved addresses, disables redirects, bounds request time and response-body reads, and filters reserved custom headers. allowedHosts is an explicit exact-host bypass of the address check, not a requirement that every destination match an allowlist; restrict it to trusted endpoints.
Delivery DTOs include identifiers, event name, status/attempts, response status and scheduling timestamps, not request/response bodies or last-error payloads. Delivery lists return items and nextCursor at the service layer; controllers expose data and meta.nextCursor. Failed deliveries cannot be replayed while their destination is inactive.
EventOutboxService.deadLetters({ cursor, limit }) and replay(id, options) expose dead-letter inspection and transaction-aware replay. These operational lists use opaque UUID-descending cursors, not offsets. Replaying an outbox event and replaying a destination delivery are distinct operations.
Distributed rate limits
The independent container bindings AdminRateLimitStore and AdminPreAuthRateLimitStore isolate authenticated actor budgets from unauthenticated IP churn (600 requests/minute before authentication). Their bounded-memory defaults are process-local and may evict old counters under pressure; do not rely on them for strict multi-instance enforcement.
Bind each token to a singleton RedisAdminRateLimitStore in a host provider, using distinct key prefixes. Its host-supplied adapter exposes eval(script, keys: string[], arguments_: string[]); increment and expiry are atomic, and the package imposes no Redis client dependency. This signature differs from the storefront Redis adapter’s positional EVAL interface.
Customizing and upgrading
The generated files are yours. Add authentication strategies, response fields, observability, or extra guards directly in the application; keep the service-layer rule intact — controllers validate, authorize, and transform, and everything else belongs in a service so both admin surfaces and your jobs share it.
Run commerce:upgrade after upgrading the package. Files you changed are never overwritten; incoming versions are staged under .commercekit/incoming for review.