Currencies

Access currency reference data: the currency code, its display name, and the number of decimal places used for amounts.

List Currencies

Get a paginated list of currencies.

Endpoint

GET /api/v1/currencies

Authentication: API Key + Secret required

Query Parameters

Parameter	Type	Required	Description
limit	number	No	Number of results per page (default: 50, min: 1, max: 10000). `page_size` is accepted as an alias.
page	number	No	Page number to retrieve (default: 1)
name	string	No	Partial, case-sensitive match on the currency `name`
currency	string	No	Exact match on the currency code, e.g. `USD`

Response

Response Headers

HTTP/1.1 200 OK
Content-Type: application/json
X-Page: 1
X-Per-Page: 50
X-Total-Count: 45
X-Total-Pages: 1
X-Page-Size: 45
X-Has-More: false

Response Body

[
  {
    "id": 1,
    "name": "US Dollar",
    "currency": "USD",
    "precision": 2
  },
  {
    "id": 2,
    "name": "Euro",
    "currency": "EUR",
    "precision": 2
  }
]

Currency Object

Field	Type	Description
id	number	Unique currency identifier
name	string	Currency display name
currency	string	Three-letter currency code, e.g. `USD`
precision	number	Number of decimal places used for amounts in this currency

Currency objects carry no exchange rate, symbol, or country link. The amount you are charged for a cross-currency order, including the rate applied, comes from the Charges API.

There is no single-currency endpoint: GET /api/v1/currencies/{id} is not routed. Use the list endpoint and filter by currency.

Examples

# Get all currencies
curl -sS "$HOST/api/v1/currencies" \
  -H "X-API-Key: $API_KEY" \
  -H "X-API-Secret: $API_SECRET"

# Look up one currency by code
curl -sS "$HOST/api/v1/currencies?currency=EUR" \
  -H "X-API-Key: $API_KEY" \
  -H "X-API-Secret: $API_SECRET"

Error Responses

Errors use the standard error envelope.

400 Bad Request

Returned when limit is not an integer between 1 and 10000:

{
  "error": {
    "name": "ValidationException",
    "code": "VALIDATION_FAILURE",
    "message": "Limit is out of valid range [1..10000]",
    "messages": {}
  }
}

Caching

Currency data is served with a 1-day Cache-Control max-age. Cache it on your side for the same period rather than fetching it per request.

Next Steps

Learn about Countries
Explore Products and their currency requirements
Understand Charges Calculation for cross-currency pricing

Currencies

On this page