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

# Create Merchant

> Add a new sub-merchant to your marketplace.

# Create Merchant

Register a new sub-merchant under your marketplace. If a Khaime account with the given email already exists, it will be linked automatically. Otherwise, a new account is created.

## Request Body

<ParamField body="business_name" type="string" required>
  Sub-merchant's business name.
</ParamField>

<ParamField body="business_email" type="string" required>
  Sub-merchant's email address.
</ParamField>

<ParamField body="business_password" type="string">
  Password for the new account. If omitted, a temporary password is auto-generated and returned in the response.
</ParamField>

<ParamField body="business_phone" type="string">
  Sub-merchant's phone number.
</ParamField>

<ParamField body="business_country" type="string">
  2-letter ISO country code (e.g., `US`, `NG`).
</ParamField>

<ParamField body="commission_rate" type="number">
  Override the default marketplace commission for this merchant. Value between `0` and `1` (e.g., `0.08` for 8%). If omitted, uses the marketplace default.
</ParamField>

## Response

```json theme={null}
{
  "success": true,
  "message": "Merchant created and linked to marketplace successfully",
  "data": {
    "id": 1676,
    "business_name": "Sub Store",
    "business_email": "merchant@example.com",
    "subdomain": null,
    "commission_rate": 0.08,
    "marketplace_id": 1042,
    "status": "active",
    "temporary_password": "auto_generated_pw"
  }
}
```

<Note>
  The `temporary_password` field is only returned when the system auto-generates a password (i.e., when `business_password` is not provided and a new account is created). Share this with the merchant so they can log in and change it.
</Note>

## Error Codes

| Status | Error                                                  | Fix                                                        |
| ------ | ------------------------------------------------------ | ---------------------------------------------------------- |
| `400`  | `business_name and business_email are required`        | Include both fields in the request body                    |
| `400`  | `commission_rate must be between 0 and 1`              | Use a decimal value (e.g., `0.10` for 10%)                 |
| `403`  | `This endpoint is restricted to marketplace operators` | Call `/marketplace/setup` first to enable marketplace mode |

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.khaime.com/api/v1/partner/marketplace/merchants \
    -H "X-API-Key: pk_sandbox_your_key" \
    -H "Content-Type: application/json" \
    -d '{
      "business_name": "Sub Store",
      "business_email": "merchant@example.com",
      "commission_rate": 0.08
    }'
  ```
</RequestExample>