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

# Commerce and Orders: Creating Orders and Managing Vendors

> Create inventory-checked orders for your customers, open disputes, submit reviews, and manage a multi-vendor marketplace on Pro plans.

Nyota Imara's commerce module is an order management system built for B2B tenants. You create orders on behalf of your customers, and the platform checks inventory levels before confirming — so you never oversell. The multi-vendor marketplace features are available on Pro plans and let you onboard third-party sellers who fulfil orders through your storefront.

All commerce endpoints require the `X-Organization-Id` header.

***

## Create an order

Send a `POST` request to `/v1/commerce/orders` with the customer, shipping destination, and line items. The server validates available stock for each item before the order is created.

```bash theme={null}
curl -X POST https://api.nyotaimara.com/v1/commerce/orders \
  -H "Authorization: Bearer <your_token>" \
  -H "X-Organization-Id: org_01j9kxp8a3bvc0nqrtzwmde4fy" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_01jb2kqp8a3bvc0nqrtzwmde9ab",
    "shippingAddress": "45 Ngong Road, Nairobi",
    "items": [
      {
        "productId": "prod_01jb3xyz",
        "locationId": "wh_01jb4abc",
        "quantity": 3,
        "unitPrice": 2500
      },
      {
        "productId": "prod_01jb3pqr",
        "locationId": "wh_01jb4abc",
        "quantity": 1,
        "unitPrice": 8000
      }
    ]
  }'
```

**Response (`201 Created`):**

```json theme={null}
{
  "success": true,
  "message": "Order created successfully.",
  "data": {
    "id": "ord_01jb5mnop",
    "orgId": "org_01j9kxp8a3bvc0nqrtzwmde4fy",
    "customerId": "cust_01jb2kqp8a3bvc0nqrtzwmde9ab",
    "shippingAddress": "45 Ngong Road, Nairobi",
    "totalAmount": 15500,
    "status": "pending_payment",
    "createdAt": "2025-11-04T10:30:00.000Z"
  }
}
```

<Note>
  Newly created orders always start with status `pending_payment`. Once payment is confirmed, stock is reserved and a Paystack payment link is generated automatically.
</Note>

### Inventory check

Before creating the order, the server checks available stock at the specified `locationId` (warehouse) for each `productId`. If any item has insufficient stock, the entire order is rejected with a descriptive `400` error:

```json theme={null}
{
  "success": false,
  "error": "Insufficient stock for product prod_01jb3xyz at warehouse wh_01jb4abc. Only 1 available."
}
```

### Order request body

| Field                | Type   | Required | Description                          |
| -------------------- | ------ | -------- | ------------------------------------ |
| `customerId`         | string | Yes      | ID of the customer placing the order |
| `shippingAddress`    | string | Yes      | Full delivery address                |
| `items`              | array  | Yes      | One or more line items (see below)   |
| `items[].productId`  | string | Yes      | Product to order                     |
| `items[].locationId` | string | Yes      | Warehouse or fulfilment location     |
| `items[].quantity`   | number | Yes      | Number of units                      |
| `items[].unitPrice`  | number | Yes      | Price per unit in KES                |

***

## Open a dispute

If an order has a problem — damaged goods, incorrect items, or a missing delivery — open a dispute:

```bash theme={null}
curl -X POST https://api.nyotaimara.com/v1/commerce/disputes \
  -H "Authorization: Bearer <your_token>" \
  -H "X-Organization-Id: org_01j9kxp8a3bvc0nqrtzwmde4fy" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "ord_01jb5mnop",
    "reason": "Items arrived damaged"
  }'
```

***

## Submit a review

After an order is fulfilled, submit a review for the vendor or product:

```bash theme={null}
curl -X POST https://api.nyotaimara.com/v1/commerce/reviews \
  -H "Authorization: Bearer <your_token>" \
  -H "X-Organization-Id: org_01j9kxp8a3bvc0nqrtzwmde4fy" \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "ord_01jb5mnop",
    "rating": 5,
    "comment": "Fast delivery and well-packaged."
  }'
```

***

## Multi-vendor marketplace

<Info>
  Multi-vendor marketplace features are available on the **Pro plan** only.
</Info>

The marketplace lets you add external vendors who can fulfil orders through your organization's storefront. You manage their onboarding and set their commission rate.

### List vendors

```bash theme={null}
curl https://api.nyotaimara.com/v1/commerce/marketplace/vendors \
  -H "Authorization: Bearer <your_token>" \
  -H "X-Organization-Id: org_01j9kxp8a3bvc0nqrtzwmde4fy"
```

### Add a vendor

The vendor's email must belong to an existing registered Nyota Imara user account.

```bash theme={null}
curl -X POST https://api.nyotaimara.com/v1/commerce/marketplace/vendors \
  -H "Authorization: Bearer <your_token>" \
  -H "X-Organization-Id: org_01j9kxp8a3bvc0nqrtzwmde4fy" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "vendor@kilimanjarogoods.co.ke",
    "brandName": "Kilimanjaro Goods",
    "commissionRate": 8.5
  }'
```

<Warning>
  The `email` provided must already have a Nyota Imara user account. Attempting to add an unregistered email returns a `404` or `400` error.
</Warning>

***

## Endpoint reference

| Method | Endpoint                           | Required policy    | Plan      |
| ------ | ---------------------------------- | ------------------ | --------- |
| `POST` | `/v1/commerce/orders`              | `oms:order:create` | All plans |
| `POST` | `/v1/commerce/disputes`            | Authenticated      | All plans |
| `POST` | `/v1/commerce/reviews`             | Authenticated      | All plans |
| `GET`  | `/v1/commerce/marketplace/vendors` | `oms:order:read`   | Pro       |
| `POST` | `/v1/commerce/marketplace/vendors` | `oms:order:update` | Pro       |