> ## Documentation Index
> Fetch the complete documentation index at: https://handbook.nyotaimara.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-Vendor Marketplace API: List and Add Sellers

> List vendors in your multi-vendor marketplace or add a new seller by email. Pro plan required. Vendors must have an existing Nyota Imara user account.

The vendor endpoints let you manage sellers in your organization's multi-vendor marketplace. This feature is available on the **Pro plan only** — requests from organizations on lower-tier plans will receive a `403` response. Vendors are identified by their existing Nyota Imara user account; they must register on the platform before being added.

<Warning>
  Attempting to add a vendor when your organization is not on the Pro plan returns a `403 Forbidden` error.
</Warning>

***

## List vendors

```
GET /v1/commerce/marketplace/vendors
```

Returns all vendors registered under the active organization.

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token. Format: `Bearer <token>`
</ParamField>

<ParamField header="X-Organization-Id" type="string" required>
  The ID of the organization whose vendor list you want to retrieve.
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  `true` on a successful request.
</ResponseField>

<ResponseField name="data" type="object[]">
  Array of vendor objects.

  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique vendor ID.
    </ResponseField>

    <ResponseField name="orgId" type="string">
      ID of the organization the vendor belongs to.
    </ResponseField>

    <ResponseField name="userId" type="string">
      Nyota Imara user ID of the vendor.
    </ResponseField>

    <ResponseField name="brandName" type="string">
      Public-facing brand name of the vendor.
    </ResponseField>

    <ResponseField name="commissionRate" type="number">
      Commission percentage retained by the marketplace on each sale.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example

```bash theme={null}
curl --request GET \
  --url https://api.nyotaimara.com/v1/commerce/marketplace/vendors \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Organization-Id: <org-id>'
```

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "vnd_01j9...",
      "orgId": "org_01j9...",
      "userId": "usr_01j9...",
      "brandName": "Savanna Goods",
      "commissionRate": 10
    }
  ]
}
```

***

## Add a vendor

```
POST /v1/commerce/marketplace/vendors
```

Adds a new vendor to the organization's marketplace. The email address must belong to a registered Nyota Imara user. If `commissionRate` is not provided, it defaults to `10`%.

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token. Format: `Bearer <token>`
</ParamField>

<ParamField header="X-Organization-Id" type="string" required>
  The ID of the organization adding the vendor.
</ParamField>

### Request body

<ParamField body="email" type="string" required>
  Email address of the Nyota Imara user to register as a vendor. Returns `404` if no user with this email exists.
</ParamField>

<ParamField body="brandName" type="string" required>
  Public-facing brand name for the vendor storefront.
</ParamField>

<ParamField body="commissionRate" type="number">
  Commission percentage the marketplace retains on each sale. Defaults to `10`.
</ParamField>

### Response

Returns `201 Created` on success.

<ResponseField name="success" type="boolean">
  `true` on a successful request.
</ResponseField>

<ResponseField name="data" type="object">
  The newly created vendor record.

  <Expandable title="properties">
    <ResponseField name="id" type="string">
      Unique vendor ID.
    </ResponseField>

    <ResponseField name="orgId" type="string">
      ID of the organization.
    </ResponseField>

    <ResponseField name="userId" type="string">
      Nyota Imara user ID of the vendor.
    </ResponseField>

    <ResponseField name="brandName" type="string">
      Brand name of the vendor.
    </ResponseField>

    <ResponseField name="commissionRate" type="number">
      Applied commission rate.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example

```bash theme={null}
curl --request POST \
  --url https://api.nyotaimara.com/v1/commerce/marketplace/vendors \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Organization-Id: <org-id>' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "vendor@example.com",
    "brandName": "Savanna Goods",
    "commissionRate": 12
  }'
```

```json theme={null}
{
  "success": true,
  "data": {
    "id": "vnd_01j9...",
    "orgId": "org_01j9...",
    "userId": "usr_01j9...",
    "brandName": "Savanna Goods",
    "commissionRate": 12
  }
}
```