Skip to main content
PATCH
/
marketplace
/
settings
curl -X PATCH https://api.khaime.com/api/v1/partner/marketplace/settings \
  -H "X-API-Key: pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "business_name": "Northstar Goods Marketplace",
    "business_email": "hello@northstargoods.example",
    "business_phone": "+2348012345678",
    "business_country_code": "NG",
    "business_website": "https://northstargoods.example",
    "business_description": "Curated fashion marketplace",
    "commission_rate": 0.08
  }'

​
Update Marketplace Settings

Update your marketplace’s public business details, default commission rate, and marketplace-level notification preferences. Send only the fields you want to change.

​
Request Body

At least one field is required.
​
business_name
string
Marketplace business name.
​
business_email
string
Marketplace public email address. This must be unique across Khaime accounts.
​
business_phone
string
Marketplace public phone number.
​
business_country
string
Marketplace 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
Marketplace website URL.
​
business_description
string
Public marketplace description.
​
commission_rate
number
Default commission rate for the marketplace, expressed as a decimal between 0 and 1. For example, send 0.08 for 8%.
​
notification_config
object
Marketplace payment notification settings. When provided, include at least one setting.

​
Response

{
  "success": true,
  "message": "Marketplace settings updated successfully",
  "data": {
    "marketplace": {
      "business_name": "Northstar Goods Marketplace",
      "business_email": "hello@northstargoods.example",
      "business_phone": "+2348012345678",
      "business_country": "Nigeria",
      "business_country_code": "NG",
      "business_website": "https://northstargoods.example",
      "business_description": "Curated fashion marketplace",
      "commission_rate": 0.08
    },
    "notification_config": {
      "send_sub_merchant_notifications": true,
      "send_buyer_notifications": true
    }
  }
}

​
Behavior

Profile and commission fields are partial updates. Omitted fields are left unchanged. notification_config is merged with the existing config, so you can update one notification setting without affecting the other. Unset notification keys default to true at send time. commission_rate here updates the marketplace default commission rate. To override commission for a specific sub-merchant, use Update Merchant.
Notification settings apply only to marketplace charges and affect Stripe, Paystack, and StartButton webhook processing from the next successful payment event onward.

​
Error Codes

StatusErrorFix
400At least one marketplace setting must be providedInclude at least one supported field
400"notification_config" must contain at least one settingInclude at least one key in notification_config
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
curl -X PATCH https://api.khaime.com/api/v1/partner/marketplace/settings \
  -H "X-API-Key: pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "business_name": "Northstar Goods Marketplace",
    "business_email": "hello@northstargoods.example",
    "business_phone": "+2348012345678",
    "business_country_code": "NG",
    "business_website": "https://northstargoods.example",
    "business_description": "Curated fashion marketplace",
    "commission_rate": 0.08
  }'