Skip to main content
POST
/
marketplace
/
merchants
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
  }'

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

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

​
business_name
string
required
Sub-merchant’s business name.
​
business_email
string
required
Sub-merchant’s email address.
​
business_password
string
Password for the new account. If omitted, a temporary password is auto-generated and returned in the response.
​
business_phone
string
Sub-merchant’s phone number.
​
business_country
string
2-letter ISO country code (e.g., US, NG).
​
commission_rate
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.

​
Response

{
  "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"
  }
}
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.

​
Error Codes

StatusErrorFix
400business_name and business_email are requiredInclude both fields in the request body
400commission_rate must be between 0 and 1Use a decimal value (e.g., 0.10 for 10%)
403This endpoint is restricted to marketplace operatorsCall /marketplace/setup first to enable marketplace mode
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
  }'