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

# Create B2B Commerce Orders, Disputes, and Product Reviews

> Place a new customer order with automatic inventory validation, open a dispute against a fulfilled order, or submit a product review for a completed purchase.

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

<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 (tenant) creating the order.
</ParamField>

### Request body

<ParamField body="customerId" type="string" required>
  ID of the customer placing the order.
</ParamField>

<ParamField body="shippingAddress" type="string" required>
  Delivery address for the order.
</ParamField>

<ParamField body="items" type="object[]" required>
  One or more line items. The request is rejected if any item has insufficient stock.

  <Expandable title="properties">
    <ResponseField name="productId" type="string">
      ID of the product to order.
    </ResponseField>

    <ResponseField name="locationId" type="string">
      Warehouse location ID to fulfil the item from.
    </ResponseField>

    <ResponseField name="quantity" type="number">
      Number of units to order.
    </ResponseField>

    <ResponseField name="unitPrice" type="number">
      Price per unit in KES.
    </ResponseField>
  </Expandable>
</ParamField>

### Response

Returns `201 Created` on success.

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

<ResponseField name="message" type="string">
  Confirmation message.
</ResponseField>

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

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

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

    <ResponseField name="customerId" type="string">
      ID of the customer.
    </ResponseField>

    <ResponseField name="shippingAddress" type="string">
      Delivery address.
    </ResponseField>

    <ResponseField name="totalAmount" type="number">
      Calculated total in KES (sum of `quantity × unitPrice` for all items).
    </ResponseField>

    <ResponseField name="status" type="string">
      Initial order status. Always `pending_payment` on creation.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example

```bash theme={null}
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
      }
    ]
  }'
```

```json theme={null}
{
  "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

<ParamField body="orderId" type="string" required>
  ID of the order being disputed.
</ParamField>

<ParamField body="reason" type="string" required>
  Short reason for the dispute (e.g. `"Item not received"`).
</ParamField>

<ParamField body="description" type="string" required>
  Full description of the issue.
</ParamField>

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

<ParamField body="orderId" type="string" required>
  ID of the completed order.
</ParamField>

<ParamField body="rating" type="number" required>
  Numeric rating for the product.
</ParamField>

<ParamField body="comment" type="string">
  Optional written review.
</ParamField>

Returns `201 Created` with `{ "success": true, "message": "Review submitted." }`.