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
  }'

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
  }'

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

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

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
  }'

Setup Marketplace Link Merchant

API Reference

Account

Products & Pricing

Payments

Subscriptions

Marketplace

B2B Commerce

Create Merchant

Create Merchant

Request Body

Response

Error Codes

​Create Merchant

​Request Body

​Response

​Error Codes

Create Merchant

Request Body

Response

Error Codes