Subotiz supports multi-currency payments, enabling localized customer payments through seamless currency conversion while maintaining a single settlement currency for pricing, billing, and financial reconciliation. This approach helps improve checkout conversion, reduce payment friction, and streamline cross-border operations.
Currency Overview
All product pricing in Subotiz is defined in the store's settlement currency, which remains consistent across all products and pricing plans.
- Prices, subscriptions, and billing records are always based on the settlement currency.
- Different currencies cannot be set at the product or pricing level.
- Customers may be charged in a different currency during checkout.
This design ensures that all billing records, subscriptions, and financial reports remain consistent and easy to reconcile, even when customers pay in different currencies.
Charging Customers in a Different Currency
Currency conversion is handled at the time of checkout session creation. The following can be configured at checkout:
- The currency presented to and used by the customer.
- An optional custom exchange rate.
If no custom rate is provided, Subotiz automatically applies a real-time market exchange rate.
Checkout Configuration Fields
Field |
Required |
Description |
|---|---|---|
target_currency |
Required |
The currency used for customer payment (e.g. USD, EUR, CAD) |
merchant_rate |
Optional |
A custom exchange rate from the settlement currency to the target currency, expressed as a decimal (e.g. 0.92 means 1 unit of settlement currency = 0.92 units of target currency) |
Example: A SaaS Subscription Priced at $100 USD, Charged in EUR
Without a custom rate:
- Set
target_currency = EUR - $100 USD is converted to EUR using the live exchange rate.
- The customer sees and pays the converted EUR amount.
With a custom rate:
- Set
target_currency = EURandmerchant_rate = 0.92 - $100 USD → €92.00 EUR
- The customer is charged €92.00.
Note: The exchange rate directly affects the final amount shown and charged to the customer.
Important Notes
- Product pricing always uses the settlement currency and cannot be changed.
- Currency conversion only occurs at checkout.
- All records (subscriptions, invoices, billing history) remain in the settlement currency.
- If no custom exchange rate is set, the final charged amount may vary slightly due to real-time exchange rate fluctuations.
- Settlement amounts are always calculated in the settlement currency, regardless of the currency used for customer payment.
Developer Reference
Currency settings are configured when creating a checkout session via API. For implementation details, refer to the Checkout Session API documentation.