Skip to main content
PATCH
/
marketplace
/
merchants
/
{merchantId}
curl -X PATCH https://api.khaime.com/api/v1/partner/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
  }'

​
Update Merchant

Update basic information for a sub-merchant linked to your marketplace. You can also update this marketplace’s commission rate for that specific merchant.

​
Path Parameters

​
merchantId
string
required
The business ID of the sub-merchant to update.

​
Request Body

At least one field is required.
​
business_name
string
Sub-merchant business name.
​
business_email
string
Sub-merchant email address. This must be unique across Khaime accounts.
​
business_phone
string
Sub-merchant public phone number.
​
business_country
string
Sub-merchant country name or country value stored on the business account.
​
business_country_code
string
2-letter ISO country code, for example NG, US, or GB.
​
business_website
string
Sub-merchant website URL.
​
business_description
string
Public sub-merchant description.
​
commission_rate
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. 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.
Use Update Marketplace Settings when you want to update the marketplace’s own profile or default commission rate. Use this endpoint when the change belongs to one sub-merchant.

​
Error Codes

StatusErrorFix
400At least one merchant setting must be providedInclude at least one supported field
400merchantId must be a valid sub-merchant business idUse the sub-merchant business ID
400commission_rate must be between 0 and 1Use a decimal value, for example 0.10 for 10%
400business_email must be a valid emailSend a valid email address
400business_email is already in useUse an email address that is not already tied to another Khaime account
401UnauthorizedProvide a valid X-API-Key header
403This endpoint is restricted to marketplace operatorsYour account must have marketplace mode enabled
404Active merchant relationship not foundThe merchant is not actively linked to your marketplace
404Sub-merchant account not foundThe merchant account or portfolio could not be found
curl -X PATCH https://api.khaime.com/api/v1/partner/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
  }'