---
title: "Update balance currency settings"
method: PATCH
path: "/settings/balance-currency"
tags: ["Settings"]
---

# Update balance currency settings

`PATCH /settings/balance-currency`

## Request

- Base URL: `https://sandbox-api.paddle.com`
- URL: `https://sandbox-api.paddle.com/settings/balance-currency`
- Auth: HTTP bearer

Updates the balance currency settings for your account.

You can only change `preferred`. Paddle then updates `primary` to match, but when depends on your account.

If more than one currency is in `enabled`, Paddle updates `primary` immediately. `preferred` must be one of the currencies in `enabled`, otherwise the request returns an `invalid_field` error.

Otherwise, Paddle updates `primary` when your balance is zero. That's immediately if it's already zero, or after your next payout if it isn't. Until then, `primary` and `preferred` are different.

If successful, your response includes a copy of the updated balance currency settings entity.

## Request body

- BalanceCurrencyUpdate: Represents the balance currency settings for your account when updating them.
  - `preferred` 'AUD' | 'CAD' | 'EUR' | 'GBP' | 'USD': Supported three-letter ISO 4217 currency code for balance currencies.

## Response `200`

The request has succeeded.

- object
  - `data` BalanceCurrency, required: Represents the balance currency settings for your account.
    - `primary` 'AUD' | 'CAD' | 'EUR' | 'GBP' | 'USD', required: Supported three-letter ISO 4217 currency code for balance currencies.
    - `preferred` 'AUD' | 'CAD' | 'EUR' | 'GBP' | 'USD', required: Supported three-letter ISO 4217 currency code for balance currencies.
    - `enabled` BalanceCurrencyCode[], required: Currencies that are enabled to hold a balance for this account. Set by Paddle.
  - `meta` Meta, required: Information about this response.
    - `request_id` string, required: Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.

## Other responses

- `default`: An unexpected error response.

## Changes

- **2026-10-19** (v1) `4f35a8c6ea4d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/paddlehq/apis/paddle-api/changes/settings/balance-currency/patch.md)

---

[API](https://skmtc.dev/paddlehq/apis/paddle-api.md) - [All operations](https://skmtc.dev/paddlehq/apis/paddle-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paddlehq/apis/paddle-api/revisions/bbc0c72039c8?raw)