CommunitySupport PortalYouTubeFree trialSign Up!

Currencies

Retrieving all currencies

get

Retrieves all currencies. You can filter and sort the results by the base currency parameters, for example code and name.

  • If the Accept-Language is set to *, each internationalized field will be returned as a map that contains all translations in a format of key:value pairs, where key is the language code, and value is the translation.

  • If the Accept-Language contains a single language, the translation will be returned as a string value.

  • If the Accept-Language header is empty, the translation will be returned in the language defined in the Configuration service as default.

Authorizations
Path parameters
tenantstring · min: 3 · max: 16Required

The tenant that the caller is acting upon.

Note: This value must always be provided in lowercase.

Pattern: ^[a-z][a-z0-9]+$
Query parameters
pageNumberinteger · min: 1Optional

The page number to be retrieved where the size of the pages is specified by the pageSize parameter. The number of the first page is 1.

Default: 1
pageSizeinteger · min: 1Optional

The number of documents being retrieved on one page.

Default: 60
sortstringOptional

Fields to sort the response data by following order of the parameters from left to right. Can contain multiple fields in the following format: field name:sort direction separated by a comma. The colon with sort direction parameter is redundant and descending order is taken only if it is equal to desc or DESC. Ascending order is considered in any other case. Sorting by name parameter works properly only if the Accept-Language header is set to a specific language or is empty with default language specified in the configuration service.

Example: name,code:desc
codestringOptional

Returns all currencies which contain the value. For example, for filter value: code=BD the following currencies might be returned: BBD, BDT, SBD, XBD

Example: BD
namestringOptional

Filtering by localized fields without language key is possible only when Accept-Language header with correct language is provided or when it is not set at all (in that case default language is taken). For example, when Accept-Language is set to en and the name parameter is equal to name=Doll, then Dollar should be returned. When Accept-Language header is set to * filtering by localized fields is possible only when the fields contain a language key. For example, when Accept-Language is set to * and name parameter is equal to name.en=Doll then Dollar should be returned.

Header parameters
Accept-LanguagestringOptional

The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. If the header value is empty, the language defined in Configuration service is returned. It can be a priority list working as a fallback mechanism.

Example: fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7
X-Total-CountbooleanOptional

The flag indicates if the total count of items should be returned. The total count will be returned as a value of the X-Total-Count header.

Default: false
Responses
200

OK

application/json
get
/currency/{tenant}/currencies
GET /currency/{tenant}/currencies HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "code": "USD",
    "name": "Dollar"
  },
  {
    "code": "EUR",
    "name": "Euro"
  }
]

Creating a new currency

post

Creates a new currency.

The currency consists of a code compliant with the ISO-4217 standard (https://www.iso.org/iso-4217-currency-codes.html) and a currency name. The name field is localized.

If the Content-Language is set to *, the request body payload should contain localized fields as a map in the key:value pairs format, where key is the language code, and value is the translation.

Required scopes

  • currency.currency_manage

Authorizations
Path parameters
tenantstring · min: 3 · max: 16Required

The tenant that the caller is acting upon.

Note: This value must always be provided in lowercase.

Pattern: ^[a-z][a-z0-9]+$
Header parameters
Content-LanguagestringOptional

The Content-Language request HTTP header defines language(s) of the payload.

Example: de
Body

Represents a single currency creation. The currency consists of a code compliant with the ISO-4217 standard (https://www.iso.org/iso-4217-currency-codes.html) and a currency name. The name field is localized.

codestringRequired

Currency code. The currency symbol must consist of three capital letters and must be a valid ISO-4217 code (https://www.iso.org/iso-4217-currency-codes.html).

nameone ofRequired

Currency name. If the Content-Language is set to *, the field should be provided as a map that contains all translations in the key:value pairs format, where key is the language code and value is the translation. If the Content-Language contains a single language, the translation should be passed as a string value. If the Accept-Language header is empty, the translation will be returned in the language defined in the Configuration service as default.

Note: Only the languages defined in the system are allowed to be used here. If a language code not defined in the system is provided, the request will be rejected.

stringOptional

Currency name in the specified language.

Example: Euro
or
Responses
201

Created

application/json
post
/currency/{tenant}/currencies
POST /currency/{tenant}/currencies HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 30

{
  "code": "USD",
  "name": "Dollar"
}
{
  "code": "text"
}

Retrieving a currency by code

get

Retrieves a currency by the currency code.

  • If the Accept-Language is set to *, each internationalized field will be returned as a map that contains all translations in a format of key:value pairs, where key is the language code and value is the translation.

  • If the Accept-Language header contains a single language, the translation will be returned as a string value.

  • If the Accept-Language header is empty, the translation will be returned in the language defined in the Configuration service as default.

Authorizations
Path parameters
currencyCodestringRequired

Three letter currency code, compliant with the ISO 4217 standard.

tenantstring · min: 3 · max: 16Required

The tenant that the caller is acting upon.

Note: This value must always be provided in lowercase.

Pattern: ^[a-z][a-z0-9]+$
Header parameters
Accept-LanguagestringOptional

The Accept-Language request HTTP header defines which languages the client is able to understand, and which locale variant is preferred. If the header value is empty, the language defined in Configuration service is returned. It can be a priority list working as a fallback mechanism.

Example: fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7
Responses
200

The currency has been retrieved successfully

application/json
get
/currency/{tenant}/currencies/{currencyCode}
GET /currency/{tenant}/currencies/{currencyCode} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "code": "USD",
  "name": "Dollar"
}

Updating a currency by code

put

Updates an existing currency.

The currency code is immutable, so it cannot be changed in this request. For the name field, the following rules are applicable:

  • If the Content-Language is set to *, the name field should be represented as a map in thekey:value format, where key is the language code, and value is the translation.

  • If the Content-Language is set to a specific language, the name parameter should be passed as a string.

Required scopes

  • currency.currency_manage

Authorizations
Path parameters
currencyCodestringRequired

Three letter currency code, compliant with the ISO 4217 standard.

tenantstring · min: 3 · max: 16Required

The tenant that the caller is acting upon.

Note: This value must always be provided in lowercase.

Pattern: ^[a-z][a-z0-9]+$
Header parameters
Content-LanguagestringOptional

The Content-Language request HTTP header defines language(s) of the payload.

Example: de
Body

Represents a single currency update.

nameone ofRequired

The currency name. If the Content-Language is set to *, the field should be provided as a map that contains all translations in the format of key:value pairs, where key is the language code and value is the translation. If the Content-Language contains a single language, the translation should be passed as a string value. If the Content-Language header is empty, the default language defined in the Configuration service is taken.

Only the languages defined in the system are allowed to be used here. If a language code not defined in the system is provided, the request will be rejected.

stringOptional

Currency name in the specified language.

Example: Euro
or
Responses
204

Currency updated

No content
put
/currency/{tenant}/currencies/{currencyCode}
PUT /currency/{tenant}/currencies/{currencyCode} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 42

{
  "name": "Dollar",
  "metadata": {
    "version": 1
  }
}
No content

Deleting a currency

delete

Deletes the currency by provided code. If given currency does not exist in the system, the http code 204 will be returned.

Warning
Deleting a currency removes all exchange rates and prices related to the currency. Price removal is an asynchronous operation.

Required scopes

  • currency.currency_manage

Authorizations
Path parameters
currencyCodestringRequired

Three letter currency code, compliant with the ISO 4217 standard.

tenantstring · min: 3 · max: 16Required

The tenant that the caller is acting upon.

Note: This value must always be provided in lowercase.

Pattern: ^[a-z][a-z0-9]+$
Query parameters
forceDeletebooleanOptionalDefault: falseExample: true
Responses
204

Currency deleted

No content
delete
/currency/{tenant}/currencies/{currencyCode}
DELETE /currency/{tenant}/currencies/{currencyCode} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content
PreviousCurrencyNextCurrency exchange

Was this helpful?