Skip to main content
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. 
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): 
{
  "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"
  }
}
Newly created orders always start with status pending_payment. Once payment is confirmed, stock is reserved and a Paystack payment link is generated automatically.

​
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: 
{
  "success": false,
  "error": "Insufficient stock for product prod_01jb3xyz at warehouse wh_01jb4abc. Only 1 available."
}

​
Order request body

FieldTypeRequiredDescription
customerIdstringYesID of the customer placing the order
shippingAddressstringYesFull delivery address
itemsarrayYesOne or more line items (see below)
items[].productIdstringYesProduct to order
items[].locationIdstringYesWarehouse or fulfilment location
items[].quantitynumberYesNumber of units
items[].unitPricenumberYesPrice per unit in KES

​
Open a dispute

If an order has a problem — damaged goods, incorrect items, or a missing delivery — open a dispute: 
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: 
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

Multi-vendor marketplace features are available on the Pro plan only.
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

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. 
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
  }'
The email provided must already have a Nyota Imara user account. Attempting to add an unregistered email returns a 404 or 400 error.

​
Endpoint reference

MethodEndpointRequired policyPlan
POST/v1/commerce/ordersoms:order:createAll plans
POST/v1/commerce/disputesAuthenticatedAll plans
POST/v1/commerce/reviewsAuthenticatedAll plans
GET/v1/commerce/marketplace/vendorsoms:order:readPro
POST/v1/commerce/marketplace/vendorsoms:order:updatePro