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

> Update a sub-merchant's basic profile details and marketplace-specific commission rate.

# 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

<ParamField path="merchantId" type="string" required>
  The business ID of the sub-merchant to update.
</ParamField>

## Request Body

At least one field is required.

<ParamField body="business_name" type="string">
  Sub-merchant business name.
</ParamField>

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

<ParamField body="business_phone" type="string">
  Sub-merchant public phone number.
</ParamField>

<ParamField body="business_country" type="string">
  Sub-merchant 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">
  Sub-merchant website URL.
</ParamField>

<ParamField body="business_description" type="string">
  Public sub-merchant description.
</ParamField>

<ParamField body="commission_rate" type="number">
  Commission rate for this marketplace-merchant relationship, expressed as a decimal between `0` and `1`.
  For example, send `0.12` for 12%.
</ParamField>

## Response

```json theme={null}
{
  "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.

<Note>
  Use [Update Marketplace Settings](/api-reference/marketplace/update-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.
</Note>

## Error Codes

| Status | Error                                                  | Fix                                                                     |
| ------ | ------------------------------------------------------ | ----------------------------------------------------------------------- |
| `400`  | `At least one merchant setting must be provided`       | Include at least one supported field                                    |
| `400`  | `merchantId must be a valid sub-merchant business id`  | Use the sub-merchant business ID                                        |
| `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                         |
| `404`  | `Active merchant relationship not found`               | The merchant is not actively linked to your marketplace                 |
| `404`  | `Sub-merchant account not found`                       | The merchant account or portfolio could not be found                    |

<RequestExample>
  ```bash cURL theme={null}
  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
    }'
  ```
</RequestExample>