FX
Spot rates and locked quotes for cross-currency checkout. `checkout.process` will lock a quote for you automatically when `pay_currency` differs from the cart currency; call `fx.lockQuote` directly only when you need the rate ahead of time (e.g. to display "Pay in USD" before the customer commits).
Get a spot rate
const r = await client.fx.getRate('GHS', 'USD')
if (!r.ok) {
console.error(r.error.code, r.error.message)
return
}
console.log(r.value.rate, r.value.inverse_rate)
console.log(r.value.quoted_at, r.value.valid_until)Lock a quote
A locked quote freezes the rate for a short window. Pass fx_quote_id back to checkout.process to bill at the locked rate.
import { money } from '@cimplify/sdk'
const r = await client.fx.lockQuote({
from: 'GHS',
to: 'USD',
amount: money('249.99'), // Money is a branded string
}, {
idempotencyKey: 'fx-lock-checkout-flow-once', // optional
})
if (!r.ok) {
console.error(r.error.code, r.error.message)
return
}
const quote = r.value
console.log(quote.id)
console.log(quote.base_amount, '→', quote.converted_amount)
console.log(quote.rate, 'valid until', quote.valid_until)Use it at checkout
const lock = await client.fx.lockQuote({ from: 'GHS', to: 'USD', amount: cart.pricing.total_price })
if (!lock.ok) return
const r = await client.checkout.process({
cart_id: cart.id,
customer: { /* ... */ },
order_type: 'pickup',
payment_method: 'card',
address_info: {},
pay_currency: 'USD',
fx_quote_id: lock.value.id,
})
if (r.ok && r.value.fx) {
console.log('Charged', r.value.fx.pay_amount, r.value.fx.pay_currency)
}FxQuote shape
| Field | Type | Notes |
|---|---|---|
id | string | Pass to checkout.process as fx_quote_id. |
base_currency | CurrencyCode | e.g. 'GHS' |
pay_currency | CurrencyCode | e.g. 'USD' |
rate | number | base → pay multiplier |
inverse_rate | number | pay → base multiplier |
base_amount | Money | Branded string |
converted_amount | Money | Branded string |
quoted_at | string | ISO timestamp |
valid_until | string | ISO timestamp; refresh after |
Method reference
| Method | Returns |
|---|---|
getRate(from, to) | Result<FxRateResponse> |
lockQuote(input, opts?) | Result<FxQuote> |
Related
-
Checkout Where the locked quote is consumed
-
Money type Branded strings, parsePrice, formatPrice
-
Cart Source of the base amount you lock
-
Error handling FX_QUOTE_FAILED is retryable
Activity
Lightweight session activity tracking: product views, category views, recommendations, and contextual messages. Calls are fire-and-forget where possible; failures never bubble into your UI.
Places
Address autocomplete and place details for delivery checkout. Pass a ` sessionToken` through both calls to bill the autocomplete and the resolution as a single session.