Subotiz supports multi-currency payments, allowing customers to pay in their local currency while merchants manage product pricing and reporting in their store's primary currency. Orders paid in other currencies are converted using the exchange rate locked when the Checkout Session is created. This helps reduce payment friction, improve checkout conversion rates, and streamline cross-border payments.
Currency Overview
Subotiz uses two currency types:
Currency |
Description |
|---|---|
Primary currency |
The currency configured for the store. All products are priced, and all admin reports are generated, in the store's primary currency. Once a trade order or discount has been created, the primary currency cannot be changed. |
Payment currency |
The currency used by the customer to pay for an order, specified by target_currency in the API (referred to as the "order settlement currency" in the API documentation). Different orders within the same store can use different payment currencies. |
- All products and pricing plans use the store's primary currency for pricing.
- Customers can pay in a currency other than the store's primary currency. The system converts the product price into the payment currency using the applicable exchange rate.
- Amounts displayed in subscriptions, trade orders, refund orders, invoices, and trade order exports are shown in the customer's payment currency. The trade order detail page also displays the Total in primary currency.
- Admin reports use the store's primary currency to provide consistent financial reporting and reconciliation.
Charging Customers in a Different Currency
Currency conversion occurs when a Checkout Session is created. The following can be configured when creating the Checkout Session:
- The payment currency displayed to the customer and used to process the payment.
- An optional custom exchange rate.
If a custom exchange rate is provided, the system uses the merchant-designated rate to convert the amount. Otherwise, the system uses the real-time exchange rate when the Checkout Session is created.
The exchange rate is locked when the Checkout Session is created and remains fixed when the customer completes payment.
At checkout, customers see the amount due in the payment currency. Merchants can view the applicable exchange rate on the trade order detail page and in the Next invoice section of the subscription detail page.
Checkout Session Parameters
Field |
Required |
Description |
|---|---|---|
target_currency |
Optional (pass when charging in a currency other than the store's primary currency) |
Specifies the order settlement currency for the Checkout Session using a supported ISO 4217 currency code, such as USD or CNY. The system converts the order amount from the store's primary currency into the specified currency for display and payment. If merchant_rate is not provided, the system uses the real-time exchange rate when the Checkout Session is created. If target_currency is omitted, the customer is charged in the store's primary currency. |
merchant_rate |
Optional |
Specifies a custom exchange rate from the store's primary currency to target_currency. The value must be a number greater than 0 and must be provided together with target_currency. This field applies only when the payment currency differs from the store's primary currency. The rate represents the amount of payment currency equivalent to 1 unit of the store's primary currency. For example, a rate of 0.92 means that 1 unit of primary currency equals 0.92 units of payment currency. |
Example: Charging EUR for a USD 100 Subscription
In this example, the store's primary currency is USD, and the subscription is priced at USD 100. The customer is charged in EUR.
Without a custom exchange rate:
- Request parameter:
"target_currency": "EUR" - The system converts USD 100 into EUR using the real-time exchange rate when the Checkout Session is created.
- The customer sees the converted amount in EUR and pays in EUR.
With a custom exchange rate:
- Request parameters:
"target_currency": "EUR","merchant_rate": "0.92" - USD 100 × 0.92 = EUR 92.00.
- The customer is charged EUR 92.00.
Note: The exchange rate directly affects the amount displayed to and charged to the customer.
Viewing Exchange Rates in the Admin
When a customer pays in a currency other than the store's primary currency, the merchant admin displays the exchange rate applied to the order or subscription.
The rate represents the amount of payment currency equivalent to 1 unit of the store's primary currency.
- Real-time exchange rate at checkout: Displayed when no custom exchange rate is provided. For example, 1 USD = 154.919019 JPY.
- Merchant-designated exchange rate: Displayed when
merchant_rateis provided. For example, 1 USD = 137.5 JPY.
The trade order detail page displays both the amount in the payment currency and the Total in primary currency. Hover over the ? icon next to Total in primary currency to view the exchange rate applied to the order.
For more information, see Trade orders｜Viewing and Managing Trade Orders.
The applicable exchange rate is also displayed in the Next invoice section of the subscription detail page.
Important Notes
- Primary currency: All product prices are set in the store's primary currency.
- Conversion timing: Currency conversion occurs only when the Checkout Session is created.
- Exchange rate lock: The exchange rate is locked when the Checkout Session is created. The customer is charged the resulting amount in the payment currency.
- Subscription renewals: The payment currency and exchange rate are determined during the initial checkout. Subsequent subscription renewals use the same payment currency and exchange rate.
- Refunds: Refunds are issued to the original payment method in the customer's payment currency. When converting the refund amount into the store's primary currency, the system uses the exchange rate locked when the original Checkout Session was created.
- Actual settlement amounts: Payment providers apply their own settlement exchange rates when converting funds for merchant payouts. As a result, the amount received by the merchant may differ from the amount recorded in the store's primary currency in admin reports. Merchants should reconcile these amounts separately.
Developer Reference
Multi-currency payment settings are configured through the API when creating a Checkout Session. For implementation details, see the Create Checkout Session API documentation.