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

Create currency

POST /v1/currencies

Creates a new currency in CRM. The currency code is set in the id field (three-letter ISO 4217 code).

Request body parameters

Parameter Type Required Description
id string yes Currency code (USD, EUR, …)
amount number yes Exchange rate relative to the base currency
amountCnt number yes Denomination — 1 for most currencies, 100 for JPY
sort number Sort order
fullName string Currency name. When omitted, the currency code is used as the name
formatString string yes Display template, e.g. # $. The # character is the placeholder for the amount
decimals number Number of decimal places
decPoint string Decimal separator
thousandsSep string Thousands separator

Localizable fields can be sent flat. fullName, formatString, decimals, decPoint, thousandsSep are stored per-language in Bitrix24. The API packs them into your language's localization (the API key's language), so a flat write now persists and reads back. A raw LANG object in the body is not accepted — the field is read-only and the request 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 POST "https://vibecode.bitrix24.com/v1/currencies" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "CNY", "amount": 12.7, "amountCnt": 1, "sort": 300, "fullName": "Chinese yuan", "formatString": "# ¥"}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/currencies" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "CNY", "amount": 12.7, "amountCnt": 1, "sort": 300, "fullName": "Chinese yuan", "formatString": "# ¥"}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/currencies', {
  method: 'POST',
  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ id: 'CNY', amount: 12.7, amountCnt: 1, sort: 300, fullName: 'Chinese yuan', formatString: '# ¥' }),
})
const { success, data } = await res.json()

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/currencies', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ id: 'CNY', amount: 12.7, amountCnt: 1, sort: 300, fullName: 'Chinese yuan', formatString: '# ¥' }),
})
const { success, data } = await res.json()

Response fields

Field Type Description
id string Currency code (USD, EUR, …)
amountCnt number Number of units for the rate
amount number Exchange rate
sort number Sort order
base boolean Base currency
fullName string Name (e.g. $, €)
lid string ID of the site the currency is bound to
formatString string Display format
decPoint string Decimal separator
thousandsSep string Thousands separator
decimals number Decimal places
dateUpdate datetime Date of the last update
lang object Per-language display settings — format, name, separators, keyed by language id. Filled from the flat request fields for your API key's language

Response example

A successful request returns the full created currency object with status 201.

JSON 
{
  "success": true,
  "data": {
    "id": "CNY",
    "fullName": "Chinese yuan",
    "amount": 12.7,
    "amountCnt": 1,
    "base": false,
    "sort": 300,
    "lid": "en",
    "formatString": "# ¥",
    "decimals": 2,
    "decPoint": ".",
    "thousandsSep": " ",
    "dateUpdate": "2024-11-12T07:20:08.000Z",
    "lang": {
      "en": {
        "FORMAT_STRING": "# ¥",
        "FULL_NAME": "Chinese yuan",
        "DEC_POINT": ".",
        "THOUSANDS_SEP": " ",
        "DECIMALS": "2",
        "THOUSANDS_VARIANT": "S",
        "HIDE_ZERO": "N"
      }
    }
  }
}

Error response example

422 — a currency with this id already exists. The message below is an English rendering of the text the API returns:

JSON 
{
  "success": false,
  "error": { "code": "BITRIX_ERROR", "message": "A currency with this identifier already exists" }
}

Errors

HTTP Code Description
400 READONLY_FIELD The body contains a read-only field, such as LANG or dateUpdate. The field name is given in message
422 BITRIX_ERROR formatString is missing — the message states that the format field is not filled in for your language
422 BITRIX_ERROR A currency with this id already exists
422 BITRIX_ERROR id is not three Latin letters — the message states that the currency identifier must be 3 Latin characters
422 BITRIX_ERROR amount is zero — the message reports an invalid default rate
422 BITRIX_ERROR Any other Bitrix24 validation failure — the exact reason is in message
403 SCOPE_DENIED The API key does not have the crm scope
401 TOKEN_MISSING No API key provided

Full list of errors — Errors.

See also