For AI agents: markdown of this page — /docs-content-en/entities/currencies/update.md documentation index — /llms.txt

Update currency

PATCH /v1/currencies/:id

Updates currency fields by code. Use it to update the exchange rate.

base and BASE are read-only. Including either in an update returns 400 READONLY_FIELD before calling Bitrix24. Changing the base currency through the API is not supported. Use the Bitrix24 interface.

Path parameters

Parameter Type Required Description
Parameterid (path) Typestring Requiredyes DescriptionCurrency code, for example USD, EUR. List: GET /v1/currencies

Request body parameters

Parameter Type Required Description
Parameteramount Typenumber Requiredno DescriptionExchange rate
ParameteramountCnt Typenumber Requiredno DescriptionNumber of units for the rate
Parametersort Typenumber Requiredno DescriptionSort order
ParameterfullName Typestring Requiredno DescriptionCurrency name
ParameterformatString Typestring Requiredno DescriptionDisplay template, e.g. # $
Parameterdecimals Typenumber Requiredno DescriptionNumber of decimal places
ParameterdecPoint Typestring Requiredno DescriptionDecimal separator
ParameterthousandsSep Typestring Requiredno DescriptionThousands separator

Localizable fields can be sent flat. The API packs fullName, formatString, decimals, decPoint, thousandsSep into your language's localization (the API key's language), so a flat update persists and reads back. A raw LANG object in the body is not accepted — the field is read-only and returns 400 READONLY_FIELD. Setting different values for several languages at once via the API is not yet supported.

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/currencies/USD" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 94.2}'

curl — OAuth application

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/currencies/USD" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"amount": 94.2}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/currencies/USD', {
  method: 'PATCH',
  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ amount: 94.2 }),
})
const { success, data } = await res.json()

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/currencies/USD', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ amount: 94.2 }),
})
const { success, data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionThe currency with all fields after the write
Fielddata.id Typestring DescriptionCurrency code (USD, EUR, …)
Fielddata.amountCnt Typenumber DescriptionNumber of units for the rate
Fielddata.amount Typenumber DescriptionExchange rate
Fielddata.sort Typenumber DescriptionSort order
Fielddata.base Typeboolean DescriptionBase currency
Fielddata.fullName Typestring DescriptionName (US Dollar, $)
Fielddata.lid Typestring DescriptionID of the site the currency is bound to
Fielddata.formatString Typestring DescriptionDisplay format
Fielddata.decPoint Typestring DescriptionDecimal separator
Fielddata.thousandsSep Typestring DescriptionThousands separator
Fielddata.decimals Typenumber DescriptionDecimal places
Fielddata.dateUpdate Typedatetime DescriptionDate of the last update
Fielddata.lang Typeobject DescriptionPer-language display settings — format, name, separators. The object key is the language ID, e.g. en

Response example

The lang object is trimmed to one language.

JSON 
{
  "success": true,
  "data": {
    "id": "USD",
    "fullName": "US Dollar",
    "amount": 94.2,
    "amountCnt": 1,
    "base": false,
    "sort": 200,
    "lid": "en",
    "formatString": "$#",
    "decimals": 2,
    "decPoint": ".",
    "thousandsSep": ",",
    "dateUpdate": "2024-11-12T07:20:08.000Z",
    "lang": {
      "en": {
        "FORMAT_STRING": "$#",
        "FULL_NAME": "US Dollar",
        "DEC_POINT": ".",
        "THOUSANDS_SEP": ",",
        "DECIMALS": "2",
        "THOUSANDS_VARIANT": "C",
        "HIDE_ZERO": "Y"
      }
    }
  }
}

Error response example

404 — no currency with this code:

JSON 
{
  "success": false,
  "error": { "code": "ENTITY_NOT_FOUND", "message": "Currency is not found" }
}

Errors

HTTP Code Description
HTTP404 CodeENTITY_NOT_FOUND DescriptionCurrency not found
HTTP400 CodeREADONLY_FIELD DescriptionThe body contains a read-only field, such as LANG or dateUpdate. The field name is given in message
HTTP403 CodeSCOPE_DENIED DescriptionAPI key does not have the crm scope
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing

Full list of errors — Errors.

See also