curl -X PATCH https://api.khaime.com/api/v1/marketplace/merchants/1676 \
-H "X-API-Key: pk_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"business_name": "Sub Store",
"business_email": "merchant@example.com",
"business_phone": "+2348012345678",
"business_country_code": "NG",
"business_website": "https://substore.example.com",
"business_description": "Premium local fashion merchant",
"commission_rate": 0.12
}'
Marketplace
Update Merchant
Update a sub-merchant’s basic profile details and marketplace-specific commission rate.
PATCH
/
marketplace
/
merchants
/
{merchantId}
curl -X PATCH https://api.khaime.com/api/v1/marketplace/merchants/1676 \
-H "X-API-Key: pk_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"business_name": "Sub Store",
"business_email": "merchant@example.com",
"business_phone": "+2348012345678",
"business_country_code": "NG",
"business_website": "https://substore.example.com",
"business_description": "Premium local fashion merchant",
"commission_rate": 0.12
}'
Intro
Updates a sub-merchant’s profile fields and/or this marketplace’s commission rate for that merchant, in a single partial update.Context
Sits between Get Merchant Details (read) and Remove Merchant (suspend) in the merchant lifecycle. This endpoint changes the merchant’s own Khaime profile and this marketplace’s commission override for them specifically — for your own marketplace’s profile or default commission rate, use Update Marketplace Settings instead. For a one-off commission-only change, Update Commission does the same commission update without touching profile fields.Hows
Path Parameters
string
required
The business ID of the sub-merchant to update.
Request Body
At least one field is required.string
Sub-merchant business name.
string
Sub-merchant email address. Must be unique across Khaime accounts.
string
Sub-merchant public phone number.
string
Sub-merchant country name.
string
2-letter ISO country code, for example
NG, US, or GB.string
Sub-merchant website URL. Must be a full absolute URL.
string
Public sub-merchant description.
number
Commission rate for this marketplace-merchant relationship, expressed as a decimal between
0 and 1. For example, send 0.12 for 12%.Response
{
"success": true,
"message": "Merchant updated successfully",
"data": {
"merchant": {
"id": 1676,
"business_name": "Sub Store",
"business_email": "merchant@example.com",
"business_phone": "+2348012345678",
"business_country": "Nigeria",
"business_country_code": "NG",
"business_website": "https://substore.example.com",
"business_description": "Premium local fashion merchant",
"commission_rate": 0.12
}
}
}
Behavior
This endpoint only updates merchants that are actively linked to your marketplace — a suspended relationship must be reactivated first (see Link Merchant). Profile fields update the sub-merchant’s Khaime business profile and public portfolio fields.commission_rate updates the commission override for this specific marketplace-merchant relationship only; it does not touch your marketplace’s default rate.
Error Codes
Requests that fail Khaime’s schema validation (missing all fields, invalid email format,commission_rate out of range) return 422. Requests that fail an application-level check (merchant ID shape, email already taken) return 400.
| Status | Error Code | Cause |
|---|---|---|
422 | VALIDATION_FAILED | No fields provided, business_email isn’t a valid email, or commission_rate is outside 0–1. |
400 | VALIDATION_FAILED | merchantId isn’t a valid sub-merchant business ID, or business_email already belongs to another Khaime account. |
401 | — | Missing or invalid X-API-Key header. |
403 | AUTH_PERMISSION_DENIED | Your business isn’t set up as a marketplace operator. |
404 | BUSINESS_NOT_FOUND | No active merchant relationship exists for this merchantId, or the sub-merchant account/portfolio couldn’t be found. |
curl -X PATCH https://api.khaime.com/api/v1/marketplace/merchants/1676 \
-H "X-API-Key: pk_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"business_name": "Sub Store",
"business_email": "merchant@example.com",
"business_phone": "+2348012345678",
"business_country_code": "NG",
"business_website": "https://substore.example.com",
"business_description": "Premium local fashion merchant",
"commission_rate": 0.12
}'