> ## Documentation Index
> Fetch the complete documentation index at: https://docs.khaime.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Marketplace Settings

> Update marketplace profile details, default commission rate, and marketplace notification settings.

# 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.

<ParamField body="business_name" type="string">
  Marketplace business name.
</ParamField>

<ParamField body="business_email" type="string">
  Marketplace public email address. This must be unique across Khaime accounts.
</ParamField>

<ParamField body="business_phone" type="string">
  Marketplace public phone number.
</ParamField>

<ParamField body="business_country" type="string">
  Marketplace country name or country value stored on the business account.
</ParamField>

<ParamField body="business_country_code" type="string">
  2-letter ISO country code, for example `NG`, `US`, or `GB`.
</ParamField>

<ParamField body="business_website" type="string">
  Marketplace website URL.
</ParamField>

<ParamField body="business_description" type="string">
  Public marketplace description.
</ParamField>

<ParamField body="commission_rate" type="number">
  Default commission rate for the marketplace, expressed as a decimal between `0` and `1`.
  For example, send `0.08` for 8%.
</ParamField>

<ParamField body="notification_config" type="object">
  Marketplace payment notification settings. When provided, include at least one setting.

  <Expandable title="notification_config fields">
    <ParamField body="send_sub_merchant_notifications" type="boolean">
      Whether to send payment receipt emails to sub-merchants after successful marketplace charges. Defaults to `true` when not set.
    </ParamField>

    <ParamField body="send_buyer_notifications" type="boolean">
      Whether to send payment confirmation emails to buyers after successful marketplace charges. Defaults to `true` when not set.
    </ParamField>
  </Expandable>
</ParamField>

## Response

```json theme={null}
{
  "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](/api-reference/marketplace/update-merchant).

<Note>
  Notification settings apply only to marketplace charges and affect Stripe, Paystack, and StartButton webhook processing from the next successful payment event onward.
</Note>

## Error Codes

| Status | Error                                                     | Fix                                                                     |
| ------ | --------------------------------------------------------- | ----------------------------------------------------------------------- |
| `400`  | `At least one marketplace setting must be provided`       | Include at least one supported field                                    |
| `400`  | `"notification_config" must contain at least one setting` | Include at least one key in `notification_config`                       |
| `400`  | `commission_rate must be between 0 and 1`                 | Use a decimal value, for example `0.10` for 10%                         |
| `400`  | `business_email must be a valid email`                    | Send a valid email address                                              |
| `400`  | `business_email is already in use`                        | Use an email address that is not already tied to another Khaime account |
| `401`  | `Unauthorized`                                            | Provide a valid `X-API-Key` header                                      |
| `403`  | `This endpoint is restricted to marketplace operators`    | Your account must have marketplace mode enabled                         |

<RequestExample>
  ```bash Update profile and default commission theme={null}
  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
    }'
  ```

  ```bash Disable sub-merchant notifications only theme={null}
  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 '{
      "notification_config": {
        "send_sub_merchant_notifications": false
      }
    }'
  ```

  ```bash Update profile and notifications together theme={null}
  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_description": "Curated fashion marketplace",
      "notification_config": {
        "send_sub_merchant_notifications": true,
        "send_buyer_notifications": true
      }
    }'
  ```
</RequestExample>