Skip to content

The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.

5.6 KB
Raw Blame
---
title: "API conventions"
description: "Authentication, seller scoping, pagination, field selection, and webhooks shared by every Mercur API surface."
---

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.

| Surface | Base path | Audience | Authentication |
| --- | --- | --- | --- |
| [Admin API](/rc/references/api/admin) | `/admin/*` | Marketplace operator | Medusa admin user (session or bearer) |
| [Vendor API](/rc/references/api/vendor) | `/vendor/*` | Sellers | Member auth + seller scoping (below) |
| [Store API](/rc/references/api/store) | `/store/*` | Storefront | Mostly public; customer auth where noted |

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`), and `GET /vendor/feature-flags`. `GET /vendor/stores` requires a session or bearer token, but works before the member belongs to a seller, so the onboarding wizard can reach it.

### 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.

### With the client

`@mercurjs/client` carries the credential for you. Pass `auth` once and every request resolves it fresh, so a token stored after login is picked up by the next call:

```typescript
import { createClient, adminAuth, vendorAuth, apiKeyAuth, publishableKeyAuth } from "@mercurjs/client"

// inside the admin or vendor panel, or a plugin's dashboard code
const admin = createClient({ baseUrl, auth: adminAuth() })
const vendor = createClient({ baseUrl, auth: vendorAuth() })

// a server-side integration with a secret API key
const integration = createClient({ baseUrl, auth: apiKeyAuth(() => process.env.MERCUR_API_KEY) })

// a storefront
const store = createClient({ baseUrl, auth: publishableKeyAuth(() => publishableKey) })
```

`adminAuth()` and `vendorAuth()` read the same token stores the panels write on login (`adminTokenStore`, `vendorTokenStore`, `vendorSellerStore`), so dashboard extensions share the user's session without knowing a storage key. `createTokenStore(key)` builds your own store, falling back to memory where `localStorage` is unavailable. A `401` clears the bearer store unless you pass `onUnauthorized`.

## Pagination

List endpoints use offset pagination with two query parameters:

```
GET /admin/sellers?limit=20&offset=40
```

| Parameter | Description | Default |
| --- | --- | --- |
| `limit` | Maximum number of records to return | 50 for most routes (some use 10, 20, or 200) |
| `offset` | Number of records to skip | 0 |

Every list response carries the paging envelope alongside the records:

```json
{
  "sellers": [ ... ],
  "count": 133,
  "offset": 40,
  "limit": 20
}
```

`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:

```
GET /vendor/products?fields=id,title,+variants.sku,-description
```

- `+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.

<Warning>
  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.
</Warning>

## 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:

```json
{
  "type": "invalid_data",
  "message": "Seller with handle already exists"
}
```

Common types: `invalid_data` (400), `unauthorized` (401), `not_allowed` (403), `not_found` (404). The typed client throws these as `ClientError`.

## Webhooks

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/hooks/payout` | Payout provider webhook receiver. The registered provider (e.g. Stripe Connect) verifies the signature and resolves the event into a payout action. |

## Next steps

<CardGroup cols={3}>
  <Card title="Admin API" href="/rc/references/api/admin" />
  <Card title="Vendor API" href="/rc/references/api/vendor" />
  <Card title="Store API" href="/rc/references/api/store" />
</CardGroup>