> ## 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 Holding Currencies

> Set which currencies a sub-merchant holds in its wallet.

## Intro

Sets the currencies a sub-merchant holds. When a customer pays in a currency the sub-merchant holds, their share is credited in that currency. Otherwise it is credited in their settlement currency. Payouts are always made in the settlement currency. See [Holding currencies](/payments/multicurrency.md#holding-currencies).

## Context

[Get Merchant Details](/api-reference/marketplace/get-merchant.md) returns the current list as `payout.enabled_currencies`, and `payout.settlement_currency` is the currency the list must include.

## Hows

### Path Parameters

**merchantId** `integer` *required*

The sub-merchant's business ID (`merchant_id` from [List Merchants](/api-reference/marketplace/list-merchants.md)).

### Request Body

**enabled\_holding\_currencies** `string[]` *required*

The full list of currencies to hold, as three-letter ISO 4217 codes, for example `["NGN", "USD"]`. It replaces the current list.

* It must include the sub-merchant's settlement currency, if they have one.
* Each currency must be one a business can hold: a currency returned by [Get Currencies](/api-reference/products/get-currencies.md) with `can_business_collect=true`. A currency the sub-merchant already holds stays accepted.

### Response

```json theme={null}
{
  "message": "Holding currencies updated",
  "success": true,
  "status": true,
  "data": {
    "settlement_currency": "NGN",
    "enabled_holding_currencies": ["NGN", "USD"]
  }
}
```

`settlement_currency` is `null` if the sub-merchant has not submitted KYC yet.

### Error Codes

| Status | Error Code | Cause |
| - | - | - |
| `400` | `VALIDATION_FAILED` | `enabled_holding_currencies` is missing or empty, contains a code that is not three letters, contains a currency a business cannot hold, or does not include the settlement currency. The message says which. |
| `401` | — | Missing or invalid `X-API-Key` header. |
| `403` | `AUTH_PERMISSION_DENIED` | Your business isn't set up as a marketplace operator. |
| `404` | `BUSINESS_NOT_FOUND` | No **active** merchant relationship exists for `merchantId` under your marketplace. |
| `500` | `INTERNAL_ERROR` | Unexpected server error. |

```bash cURL theme={null}
curl -X PATCH https://api.khaime.com/api/v1/merchants/892/holding-currencies \
  -H "X-API-Key: pk_sandbox_your_key" \
  -H "Content-Type: application/json" \
  -d '{"enabled_holding_currencies": ["NGN", "USD"]}'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.