Zonos logo
DOCS

Retrieve an exchange rate

/

Retrieve currency exchange rates 

Zonos supports fetching up-to-date exchange rates between two currencies through our GraphQL API. We guarantee the exchange rates we calculate between currencies. Although we update our rates every 10 minutes, we guarantee the rate from the time it was fetched for 90 days.

Zonos only guarantees exchange rates for instances where we handle international payments, such as through Zonos Checkout or custom integrations with our Zonos Payments API. For full specifics on how we guarantee exchange rates, consult our Terms of Service.

Create a new exchange rate object 

To fetch a fresh exchange rate between two currencies, you can use the createExchangeRate mutation via our GraphQL API. createExchangeRate supports a source and target currency code, as well as a rate type. Full documentation around the createExchangeRate mutation can be found on our GraphQL API reference. Exchange rates fetched with our API are organization specific.

MUTATION

1
2
3
4
5
6
7
8
9
10
11
12
13
mutation {
 createExchangeRate(
  input: {
   sourceCurrencyCode: CAD
   targetCurrencyCode: GBP
   type: GUARANTEED
  }
 ) {
  id
  rate
  sourceCurrencyCode
  targetCurrencyCode
  targetFormat {
   decimalDelimiter
   symbol
   thousandsDelimiter
  }
 }
}

RESPONSE

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
 "data": {
  "createExchangeRate": {
   "id": "exchange_rate_1a021f23-8a63-4811-a8a3-6cce69f3a616",
   "rate": 0.6391,
   "sourceCurrencyCode": "CAD",
   "targetCurrencyCode": "GBP",
   "targetFormat": {
    "decimalDelimiter": ".",
    "symbol": "£",
    "thousandsDelimiter": ","
   }
  }
 }
}

Retrieve an existing exchange rate 

You can use the exchangeRate query with a provided ID to retrieve previously fetched exchange rate details. This is useful if you want to see historical exchange rate details, use them for reports, UIs, etc. You can see a full list of available fields on the GraphQL API reference.

Previously created rates are not refreshed when you retrieve them, they are pinned in time to when they were originally fetched.

MUTATION

1
2
3
4
5
query {
  exchangeRate(id: "exchange_rate_1a021f23-8a63-4811-a8a3-6cce69f3a616") {
    // Field names here...
  }
}

RESPONSE

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
 "data": {
  "exchangeRate": {
   "id": "exchange_rate_1a021f23-8a63-4811-a8a3-6cce69f3a616",
   "rate": 0.6391,
   "sourceCurrencyCode": "CAD",
   "targetCurrencyCode": "GBP",
   "targetFormat": {
    "decimalDelimiter": ".",
    "symbol": "£",
    "thousandsDelimiter": ","
   }
  }
 }
}

Google exchange rates vs Zonos exchange rates 

When you use Google for exchange rates, you will get a different value than what our API provides. The exchange rate your customer is looking at online is not a consumer rate. If you Google the current USD to GBP conversion rate, what you will see is the “benchmark” foreign exchange rate. This is the rate at which large international banks exchange hundreds of millions of dollars, but no one can buy at this rate. A consumer will see this benchmark rate plus fees charged by the foreign exchange company when Zonos exchange rates are not used.

The other sites you see most likely display the exchange rate for the sake of convenience, but they are not actually charging the customer in their foreign currency. Credit card companies and banks issuing the card will charge foreign exchange and foreign transaction fees to customers who buy from sites that charge in USD. Even though they display the currency in GBP (or any other currency), the amount displayed to them at checkout is not the amount the customer will ultimately pay.

As mentioned before, we offer a guaranteed exchange rate. The additional fees we charge account for the constantly fluctuating exchange market. Variations are likely to take place over the 90-day guaranteed period for the originally fetched rate. The extra fees ensure that the amount displayed and paid by the customer at checkout is the total and final cost they will pay—no hidden or surprise fees later on.