Skip to main content
The commerce endpoints cover the full post-purchase lifecycle: creating orders, raising disputes, and submitting reviews. Orders are validated against live inventory before being created — if any line item is understocked, the entire request is rejected.

​
Create an order

POST /v1/commerce/orders
Creates a new order for a customer. The server checks available inventory at each specified warehouse location before accepting the order. On success, stock is reserved and a payment link is generated automatically.

​
Headers

​
Authorization
string
required
Bearer token. Format: Bearer <token>
​
X-Organization-Id
string
required
The ID of the organization (tenant) creating the order.

​
Request body

​
customerId
string
required
ID of the customer placing the order.
​
shippingAddress
string
required
Delivery address for the order.
​
items
object[]
required
One or more line items. The request is rejected if any item has insufficient stock.

​
Response

Returns 201 Created on success.
​
success
boolean
true on a successful request.
​
message
string
Confirmation message.
​
data
object
The created order record.

​
Example

curl --request POST \
  --url https://api.nyotaimara.com/v1/commerce/orders \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Organization-Id: <org-id>' \
  --header 'Content-Type: application/json' \
  --data '{
    "customerId": "usr_01j9...",
    "shippingAddress": "123 Ngong Road, Nairobi",
    "items": [
      {
        "productId": "prod_01j9...",
        "locationId": "loc_01j9...",
        "quantity": 2,
        "unitPrice": 2500
      }
    ]
  }'

{
  "success": true,
  "message": "Order created successfully.",
  "data": {
    "id": "ord_01j9...",
    "orgId": "org_01j9...",
    "customerId": "usr_01j9...",
    "shippingAddress": "123 Ngong Road, Nairobi",
    "totalAmount": 5000,
    "status": "pending_payment"
  }
}

​
Open a dispute

POST /v1/commerce/disputes
Opens a dispute against a delivered or fulfilled order. This immediately locks the associated vendor payout in escrow pending review.

​
Request body

​
orderId
string
required
ID of the order being disputed.
​
reason
string
required
Short reason for the dispute (e.g. "Item not received").
​
description
string
required
Full description of the issue.
Returns 201 Created with { "success": true, "message": "Dispute opened. Our team will review the case." }.

​
Submit a review

POST /v1/commerce/reviews
Allows a customer to rate and review a product they purchased.

​
Request body

​
orderId
string
required
ID of the completed order.
​
rating
number
required
Numeric rating for the product.
​
comment
string
Optional written review.
Returns 201 Created with { "success": true, "message": "Review submitted." }.