Update Marketplace Settings

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

curl -X PATCH https://api.khaime.com/api/v1/marketplace/settings \
  -H "X-API-Key: pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "notification_config": {
      "send_sub_merchant_notifications": false
    }
  }'

curl -X PATCH https://api.khaime.com/api/v1/marketplace/settings \
  -H "X-API-Key: pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "business_description": "Curated fashion marketplace",
    "notification_config": {
      "send_sub_merchant_notifications": true,
      "send_buyer_notifications": true
    }
  }'

PATCH

marketplace

settings

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

curl -X PATCH https://api.khaime.com/api/v1/marketplace/settings \
  -H "X-API-Key: pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "notification_config": {
      "send_sub_merchant_notifications": false
    }
  }'

curl -X PATCH https://api.khaime.com/api/v1/marketplace/settings \
  -H "X-API-Key: pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "business_description": "Curated fashion marketplace",
    "notification_config": {
      "send_sub_merchant_notifications": true,
      "send_buyer_notifications": true
    }
  }'

Intro

Updates your own marketplace’s public business details, default commission rate, and payment-notification preferences — as opposed to any one sub-merchant’s data.

Context

This is the operator-level counterpart to Update Merchant: that endpoint changes a specific sub-merchant’s profile and commission override, this one changes your business profile and the default commission rate every merchant without an override inherits (see the inheritance behavior described in Link Merchant). Per-merchant overrides on top of this default are set via Update Commission.

Hows

Request Body

At least one field is required.

string

Marketplace business name.

string

Marketplace public email address. Must be unique across Khaime accounts.

string

Marketplace public phone number.

string

Marketplace country name.

string

2-letter ISO country code, for example NG, US, or GB.

string

Marketplace website URL. Must be a full absolute URL.

string

Public marketplace description.

number

Default commission rate for the marketplace, expressed as a decimal between 0 and 1. For example, send 0.08 for 8%.

object

Marketplace payment notification settings. When provided, include at least one setting.

Show notification_config fields

boolean

Whether to send payment receipt emails to sub-merchants after successful marketplace charges. Defaults to true when not set.

boolean

Whether to send payment confirmation emails to buyers after successful marketplace charges. Defaults to true when not set.

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 one specific sub-merchant, use Update Merchant or Update Commission.

Notification settings apply only to marketplace charges and affect all payment gateway webhook processing from the next successful payment event onward.

Error Codes

Requests that fail Khaime’s schema validation (no fields provided, invalid email format, commission_rate out of range, empty notification_config) return 422. business_email already in use is caught at the application level and returns 400.

Status	Error Code	Cause
`422`	`VALIDATION_FAILED`	No fields provided, `notification_config` given but empty, `business_email` isn’t a valid email, or `commission_rate` is outside `0`–`1`.
`400`	`VALIDATION_FAILED`	`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.

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

curl -X PATCH https://api.khaime.com/api/v1/marketplace/settings \
  -H "X-API-Key: pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "notification_config": {
      "send_sub_merchant_notifications": false
    }
  }'

curl -X PATCH https://api.khaime.com/api/v1/marketplace/settings \
  -H "X-API-Key: pk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "business_description": "Curated fashion marketplace",
    "notification_config": {
      "send_sub_merchant_notifications": true,
      "send_buyer_notifications": true
    }
  }'

Whys

Bundling profile, default commission, and notification preferences into one endpoint reflects that these are all “how my marketplace presents and behaves by default” settings, distinct from anything about a specific merchant. Merging notification_config instead of requiring both keys every time means you can flip one notification toggle without having to know or resend the current value of the other.

Why nots

This does not touch any individual sub-merchant’s profile or commission override — those go through Update Merchant and Update Commission. Notification changes are forward-only — they affect future webhook processing, not emails already sent or in flight. And this endpoint cannot be used to enable marketplace mode in the first place — that’s provisioned by Khaime, see Setup Marketplace.

API Reference

Account

Products & Pricing

Payments

Integration Guides

Commerce API

Subscriptions

Marketplace

Intro

Context

Hows

Request Body

Response

Behavior

Error Codes

Whys

Why nots

​Intro

​Context

​Hows

​Request Body

​Response

​Behavior

​Error Codes

​Whys

​Why nots

Intro

Context

Hows

Request Body

Response

Behavior

Error Codes

Whys

Why nots