Skip to main content
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.
Attempting to add a vendor when your organization is not on the Pro plan returns a 403 Forbidden error.

​
List vendors

GET /v1/commerce/marketplace/vendors
Returns all vendors registered under the active organization.

​
Headers

​
Authorization
string
required
Bearer token. Format: Bearer <token>
​
X-Organization-Id
string
required
The ID of the organization whose vendor list you want to retrieve.

​
Response

​
success
boolean
true on a successful request.
​
data
object[]
Array of vendor objects.

​
Example

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

{
  "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

​
Authorization
string
required
Bearer token. Format: Bearer <token>
​
X-Organization-Id
string
required
The ID of the organization adding the vendor.

​
Request body

​
email
string
required
Email address of the Nyota Imara user to register as a vendor. Returns 404 if no user with this email exists.
​
brandName
string
required
Public-facing brand name for the vendor storefront.
​
commissionRate
number
Commission percentage the marketplace retains on each sale. Defaults to 10.

​
Response

Returns 201 Created on success.
​
success
boolean
true on a successful request.
​
data
object
The newly created vendor record.

​
Example

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
  }'

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