FX
Spot rates and locked quotes for cross-currency purchase intents. Lock the displayed rate, then pass its ID into Cart intent preparation so the accepted FX evidence is frozen in immutable terms.
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 into Cart purchase-intent preparation to bind the displayed rate to immutable terms.
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
import {
ORDER_TYPE,
PURCHASE_INTENT_PAYMENT_METHOD,
PURCHASE_INTENT_SOURCE_KIND,
} from '@cimplify/sdk'
const lock = await client.fx.lockQuote({ from: 'GHS', to: 'USD', amount: cart.pricing.total_price })
if (!lock.ok) return
const r = await client.purchaseIntents.mint({
client_intent_key: stableKey,
source: { kind: PURCHASE_INTENT_SOURCE_KIND.CART, cart_id: cart.id },
checkout: {
customer: { /* ... */ },
order_type: ORDER_TYPE.PICKUP,
address_info: {},
pay_currency: 'USD',
fx_quote_id: lock.value.id,
tender_preference: { method_kind: PURCHASE_INTENT_PAYMENT_METHOD.CARD },
},
})
if (r.ok) renderTerms(r.value.current_terms)FxQuote shape
| Field | Type | Notes |
|---|---|---|
id | string | Pass to Cart purchase-intent preparation 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.