Skip to content

Admin REST API

@adocommercekit/admin-api publishes 84 host-owned endpoints under /api/commerce/admin, plus the admin service layer both admin surfaces share.

@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:doctor

configure() 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() in app/policies/commerce/main.ts before an operator can do anything; until you do, every endpoint answers 403. commerce:doctor reports 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_FORBIDDEN with an ability in details.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 }; amountMinor is the stringified integer minor-unit value, so charts and exports never parse a formatted string.
  • Everything serialized here goes through a transformer’s forAdmin variant. 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 422 with the commerce envelope and details.messages, never a redirect.
  • Channel restrictions come from the host’s commerceAdminScope(actor, scope) hook, not client channelId query input. scope.channelId derives 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-DD includes the complete UTC day, not only midnight.
  • Anonymization requires the exact confirmation string ANONYMIZE <customer id>. It sets anonymizedAt and 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. CustomerAnonymized lets extensions scrub their own PII.
  • CustomerService.lastActivityAt(ids) returns the greatest customer updatedAt, order placedAt, or cart updatedAt per customer (or null), 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.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close