Skip to main content
Every Mercur API surface follows the same rules for authentication, pagination, and field selection. Mercur exposes three HTTP surfaces on the Medusa server. They share the conventions below, so once you learn one surface the others behave the same way. All requests and responses are JSON. Call these APIs with the typed @mercurjs/client. Every route below maps 1:1 to a client call.

​
Authentication

​
Admin

Admin routes use standard Medusa admin authentication. Log in via /auth/user/emailpass, then send the session cookie or an Authorization: Bearer <token> header.

​
Vendor

Vendor routes authenticate the member actor (/auth/member/emailpass to obtain a token) and are additionally scoped to a single seller:
  1. The request must carry an x-seller-id header, or a seller selected in the session via POST /vendor/sellers/select.
  2. Middleware verifies the authenticated member belongs to that seller and populates the request’s seller context. Every query and mutation on the surface is then filtered to that seller automatically.
  3. The member’s RBAC roles are resolved for the selected seller.
A handful of vendor routes are public by design: seller registration (POST /vendor/sellers), invite acceptance (POST /vendor/members/invites/accept), GET /vendor/stores, and GET /vendor/feature-flags.

​
Store

Store routes are public. Customer authentication (session or bearer) is required for /store/order-groups and optional for /store/offers and /store/products, where it enriches the pricing context when present. Public seller routes only return sellers whose status is open and who are not inside a scheduled closure window.

​
Pagination

List endpoints use offset pagination with two query parameters:
Every list response carries the paging envelope alongside the records:
count is the total number of records matching the filters, so offset + limit < count means more pages exist.

​
Field selection

List and detail endpoints accept a fields query parameter to control which fields and relations are returned:
  • +field adds a field or relation on top of the route’s defaults.
  • -field removes one from the defaults.
  • A bare field (no prefix) replaces the default set entirely.
Mixing one unprefixed field into an otherwise-prefixed list switches the whole parameter to replace mode and silently drops the route defaults. Prefix every entry with + or - when you mean to merge.

​
Filtering and ordering

List endpoints accept entity-specific filter parameters (documented per route group), a free-text q search parameter where the entity has searchable fields, and order for sorting (order=-created_at for descending).

​
Errors

Errors follow Medusa’s format:
Common types: invalid_data (400), unauthorized (401), not_allowed (403), not_found (404). The typed client throws these as ClientError.

​
Webhooks

​
Next steps

Admin API

Vendor API

Store API