POST
Add an exchange rate
Organization space Accounting module For: Accountant · Permission: exchange_rates.create Conditions
  • The accounting module must be included in the plan of the organization.
  • Exchange rates belong to the organization, not to a book.
  • The caller needs an accounting access grant on the organization’s own book (a grant on a company book is not enough). This is checked before validation.
  • target_currency_code must differ from source_currency_code; both codes must be three upper-case letters.
  • rate must be a decimal string with up to 20 digits before the point and 18 after, and greater than zero.
  • Exponents must be integers from 0 to 18.
  • The new rate must not overlap an existing one: it is refused when a rate for the same source, target and direction is still open (no end date) or ends on or after the new valid_from. The previous rate must be closed first, and the new one must start after its end date.
  • At most one rate exists for a given pair, direction and start date (a deleted rate leaves no trace).
  • Two concurrent creations for the organization are serialised.
What else happens
  • Stores an open-ended rate (valid_to empty) and records the creating member or agent account in created_by and created_by_type (both null when the actor cannot be identified). Later conversions of payments and refunds between the two currencies use it from valid_from.
Part of Set up the books.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

response
enum<string>
default:none

Response mode. Default none; none answers 204 No Content.

Available options:
none,
resource
fields
string

Comma-separated JSON keys of the root resource (id is always rendered). Available: id, source_currency_code, source_currency_exponent, target_currency_code, target_currency_exponent, direction, rate, valid_from, valid_to, created_by, created_by_type, created_at.

include
string

Comma-separated include paths, each optionally followed by its fields in parentheses: units(id,sku),units.uomUnit(id,name). Max depth 6, max 40 paths. Available: .

Body

application/json
source_currency_code
string
required

Three-letter upper-case code of the currency converted from, for example XOF.

source_currency_exponent
integer
required

Number of decimal places of the source currency, from 0 to 18.

Required range: 0 <= x <= 18
target_currency_code
string
required

Three-letter upper-case code of the currency converted to. It must differ from the source currency.

target_currency_exponent
integer
required

Number of decimal places of the target currency, from 0 to 18.

Required range: 0 <= x <= 18
rate
string
required

Exchange rate: how many units of the target currency one unit of the source currency is worth, as a decimal string with a dot. Required; up to 20 digits before the dot and up to 18 after.

direction
enum<string> | null

Money flow the rate applies to: incoming or outgoing. Defaults to incoming when omitted.

Available options:
incoming,
outgoing
valid_from
string<date-time> | null

First day the rate applies (ISO 8601 date); only the date part is used. Defaults to today. It must come after the end of any existing rate for the same pair and direction, and open rates must be closed first.

Response

Resource (only with response=resource).

id

Identifier of the exchange rate (27-character KSUID).

source_currency_code

Three-letter code of the currency converted from.

source_currency_exponent
integer

Number of decimal places of the source currency (divide an amount in minor units by 10 to this power).

target_currency_code

Three-letter code of the currency converted to.

target_currency_exponent
integer

Number of decimal places of the target currency.

direction

Money flow the rate applies to: incoming (money received) or outgoing (money paid out, such as refunds).

rate

Exchange rate: how many units of the target currency one unit of the source currency is worth, as an exact decimal string with no trailing zeros.

valid_from

First day the rate applies (YYYY-MM-DD).

valid_to

Last day the rate applies (YYYY-MM-DD); null while the rate is open-ended.

created_by

Identifier of the member or agent account that created the rate; null when it could not be identified.

created_by_type

Type of the creator (member or agent account); null when unknown.

created_at

Date and time the record was created (ISO 8601, UTC).