Update Commission

curl -X PATCH https://api.khaime.com/api/v1/marketplace/merchants/892/commission \
  -H "X-API-Key: pk_sandbox_your_key" \
  -H "Content-Type: application/json" \
  -d '{"commission_rate": 0.08}'

PATCH

marketplace

merchants

{merchantId}

commission

curl -X PATCH https://api.khaime.com/api/v1/marketplace/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
  }
}

Updates both the marketplace-merchant relationship’s rate and the sub-merchant’s own commission field on their account — the latter is what Create Charge actually reads at split time.

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/marketplace/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-linked merchantId returns BUSINESS_NOT_FOUND rather than creating or resurrecting a relationship implicitly.

API Reference

Account

Products & Pricing

Payments

Integration Guides

Commerce API

Subscriptions

Marketplace

Intro

Context

Hows

Path Parameters

Request Body

Response

Error Codes

Whys

Why nots

​Intro

​Context

​Hows

​Path Parameters

​Request Body

​Response

​Error Codes

​Whys

​Why nots

Intro

Context

Hows

Path Parameters

Request Body

Response

Error Codes

Whys

Why nots