> ## Documentation Index
> Fetch the complete documentation index at: https://docs.khaime.com/llms.txt
> Use this file to discover all available pages before exploring further.

# B2B Commerce Overview

> Quote-based commerce for enterprise and wholesale transactions.

# B2B Commerce

The B2B Commerce API enables quote-based workflows for enterprise customers, wholesalers, and any scenario requiring negotiated pricing before payment.

## How It Works

```mermaid theme={null}
sequenceDiagram
    participant Customer
    participant Your App
    participant Khaime API
    participant Merchant

    Customer->>Your App: Request quote for products
    Your App->>Khaime API: POST /rfq
    Khaime API-->>Merchant: Email: New RFQ received
    Khaime API-->>Customer: Email: RFQ confirmation
    Merchant->>Khaime API: POST /quote
    Khaime API->>Khaime API: POST /quote/:id/send
    Khaime API-->>Customer: Email: Quote ready
    Customer->>Your App: Accept quote
    Your App->>Khaime API: POST /quote/:id/accept
    Khaime API-->>Merchant: Email: Quote accepted + PO
    Khaime API-->>Customer: Email: PO confirmation
```

## Key Concepts

### RFQ (Request for Quote)

An RFQ is created when a customer requests pricing for one or more products. It contains:

* Customer information (name, email, company)
* Line items (products, quantities, variations)
* Optional shipping address
* Requested delivery date
* Notes

RFQs have these statuses:

| Status     | Description                    |
| ---------- | ------------------------------ |
| `pending`  | Awaiting quote from merchant   |
| `quoted`   | Quote(s) sent to customer      |
| `accepted` | Customer accepted a quote      |
| `rejected` | All quotes rejected            |
| `expired`  | RFQ expired without acceptance |

### Quote

A Quote is the merchant's response to an RFQ with specific pricing. It contains:

* Line items with unit prices
* Discounts (volume, promotional)
* Shipping and tax amounts
* Payment terms (NET30, upfront, etc.)
* Validity period

Quote statuses:

| Status       | Description                  |
| ------------ | ---------------------------- |
| `draft`      | Being prepared, not yet sent |
| `sent`       | Sent to customer             |
| `viewed`     | Customer opened the quote    |
| `accepted`   | Customer accepted            |
| `rejected`   | Customer rejected            |
| `expired`    | Validity period passed       |
| `superseded` | Replaced by a revision       |

### PO (Purchase Order)

When a quote is accepted, a PO number is generated. This serves as the formal agreement and can be used for invoicing and fulfillment.

## Quick Start

### 1. Submit an RFQ

```bash theme={null}
curl -X POST https://api.khaime.com/api/v1/partner/rfq \
  -H "X-API-Key: pk_sandbox_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_name": "John Smith",
    "customer_email": "john@acme.com",
    "company_name": "Acme Corporation",
    "items": [
      { "product_id": 123, "quantity": 100 },
      { "product_id": 456, "quantity": 50 }
    ],
    "notes": "Need bulk pricing for Q1 order"
  }'
```

### 2. Create a Quote (Merchant)

```bash theme={null}
curl -X POST https://api.khaime.com/api/v1/partner/quote \
  -H "X-API-Key: pk_sandbox_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": 789,
    "line_items": [
      { "product_id": 123, "product_title": "Widget Pro", "quantity": 100, "unit_price": 2500 },
      { "product_id": 456, "product_title": "Gadget Plus", "quantity": 50, "unit_price": 5000 }
    ],
    "discount_amount": 25000,
    "discount_reason": "Bulk order discount",
    "payment_terms": "NET30",
    "valid_until": "2024-02-28T23:59:59Z"
  }'
```

### 3. Send Quote to Customer

```bash theme={null}
curl -X POST https://api.khaime.com/api/v1/partner/quote/101/send \
  -H "X-API-Key: pk_sandbox_your_key"
```

### 4. Accept Quote

```bash theme={null}
curl -X POST https://api.khaime.com/api/v1/partner/quote/101/accept \
  -H "X-API-Key: pk_sandbox_your_key"
```

## Email Notifications

The B2B system automatically sends transactional emails at key points:

| Event          | Recipient | Email                  |
| -------------- | --------- | ---------------------- |
| RFQ submitted  | Merchant  | New RFQ notification   |
| RFQ submitted  | Customer  | RFQ confirmation       |
| Quote sent     | Customer  | Quote ready for review |
| Quote accepted | Merchant  | Quote accepted + PO    |
| Quote accepted | Customer  | PO confirmation        |
| Quote rejected | Merchant  | Quote rejected         |

Merchants can customize email templates via the Email Templates endpoints.

## Endpoints

| Method | Endpoint                         | Description                                                                 |
| ------ | -------------------------------- | --------------------------------------------------------------------------- |
| POST   | `/rfq`                           | [Submit RFQ](/api-reference/b2b/submit-rfq)                                 |
| GET    | `/rfq`                           | [List RFQs](/api-reference/b2b/list-rfqs)                                   |
| GET    | `/rfq/:id`                       | [Get RFQ](/api-reference/b2b/get-rfq)                                       |
| POST   | `/quote`                         | [Create Quote](/api-reference/b2b/create-quote)                             |
| GET    | `/quote`                         | [List Quotes](/api-reference/b2b/list-quotes)                               |
| GET    | `/quote/:id`                     | [Get Quote](/api-reference/b2b/get-quote)                                   |
| PATCH  | `/quote/:id`                     | [Update Quote](/api-reference/b2b/update-quote)                             |
| POST   | `/quote/:id/send`                | [Send Quote](/api-reference/b2b/send-quote)                                 |
| POST   | `/quote/:id/accept`              | [Accept Quote](/api-reference/b2b/accept-quote)                             |
| POST   | `/quote/:id/reject`              | [Reject Quote](/api-reference/b2b/reject-quote)                             |
| POST   | `/quote/:id/revise`              | [Revise Quote](/api-reference/b2b/revise-quote)                             |
| GET    | `/email-templates`               | [List Email Templates](/api-reference/b2b/list-email-templates)             |
| POST   | `/email-templates/preview`       | [Preview Email Template](/api-reference/b2b/preview-email-template)         |
| GET    | `/email-templates/default/:type` | [Get Default Email Template](/api-reference/b2b/get-default-email-template) |
| PUT    | `/email-templates/:type`         | [Upsert Email Template](/api-reference/b2b/upsert-email-template)           |
| GET    | `/email-templates/:id`           | [Get Email Template](/api-reference/b2b/get-email-template)                 |
| DELETE | `/email-templates/:id`           | [Delete Email Template](/api-reference/b2b/delete-email-template)           |