curl -X PATCH https://api.khaime.com/api/v1/merchants/892/commission \
-H "X-API-Key: pk_sandbox_your_key" \
-H "Content-Type: application/json" \
-d '{"commission_rate": 0.08}'
Marketplace
Update Commission
Set the commission rate for a specific sub-merchant.
PATCH
/
merchants
/
{merchantId}
/
commission
curl -X PATCH https://api.khaime.com/api/v1/merchants/892/commission \
-H "X-API-Key: pk_sandbox_your_key" \
-H "Content-Type: application/json" \
-d '{"commission_rate": 0.08}'
Intro
Sets a per-merchant commission rate that overrides your marketplace’s default rate for one sub-merchant only.Context
This is the focused, commission-only sibling of Update Merchant (which can also change commission alongside profile fields). The rate set here is what Create Charge reads at the moment a marketplace charge is split — it’s the second link in the resolution chain described below, after which your marketplace’s own default (set via Update Marketplace Settings) applies if no override exists.Commission resolution order at charge time: this per-merchant rate → your marketplace’s default rate →
0 if neither is set.Hows
Path Parameters
integer
required
The sub-merchant’s business ID (
merchant_id from List Merchants).Request Body
number
required
Decimal commission rate between
0 and 1 (e.g. 0.08 = 8%). Not a percentage — 8 is invalid, 0.08 is correct.Response
{
"success": true,
"message": "Commission rate updated successfully",
"data": {
"commission_rate": 0.08
}
}
Error Codes
| Status | Error Code | Cause |
|---|---|---|
403 | AUTH_PERMISSION_DENIED | Your business isn’t set up as a marketplace operator. Run Setup Marketplace first. |
400 | VALIDATION_FAILED | commission_rate is missing, or outside the 0–1 range. |
404 | BUSINESS_NOT_FOUND | No active merchant relationship exists for merchantId under your marketplace. Pending or suspended relationships return this same error — reactivate via Link Merchant first. |
400 | INTERNAL_ERROR | Unexpected server error. |
curl -X PATCH https://api.khaime.com/api/v1/merchants/892/commission \
-H "X-API-Key: pk_sandbox_your_key" \
-H "Content-Type: application/json" \
-d '{"commission_rate": 0.08}'
Whys
This exists as a narrower alternative to Update Merchant for the common case of “I just need to change this one merchant’s rate” — a single required field, no risk of accidentally touching profile data in the same call. Requiring the relationship to be active (not just existing) prevents renegotiating commission on a merchant who’s currently suspended from the marketplace, which wouldn’t affect any real charges anyway.Why nots
This does not change your marketplace’s default rate for merchants without an override — that’s Update Marketplace Settings. It does not retroactively recalculate commission on transactions that already settled; it only affects charges processed after the update. And it only works on merchants with an active relationship — a suspended or never-linkedmerchantId returns BUSINESS_NOT_FOUND rather than creating or resurrecting a relationship implicitly.