Multi-currencies #18

frankie567 · 2025-11-07T16:45:54Z

No description provided.

psincraian

Really nice writeup François!

psincraian · 2025-11-10T15:48:14Z

engineering/design-documents/multi-currency.mdx

+
+- Store presentment amount and currency in the current amount fields.
+- When receiving a payment or refund from Stripe, we'll need to get the converted amount in `usd` Stripe calculated (from the balance transaction), to impact the merchant's Account balance.
+- Revamp metrics so amount are always computed in `usd`, directly from the Account transactions amount.


How will history work with exchange rates?

So, the idea is to store the converted amount (say usd for simplicity) in the account transactions (at the moment we receive the payment), and use them not only for payouts like we do today, but for metrics.

Effectively, if you look at MRR, a single subscription might fluctuate over months following exchange rates.

psincraian · 2025-11-10T15:48:44Z

engineering/design-documents/multi-currency.mdx

+
+## Technical Considerations and Open Questions
+
+### Polar fees


@birkjernstrom to bring some wisdom here

This is a great question and has a lot of operational nuances on our end.

We will move towards having multiple PSP accounts (across regions) and multiple PSPs for orchestration too. So managing more than one balance account is inevitable, but will introduce some treasury challenges. Multi-currency could do that too. E.g imagine we leverage multiple currency accounts to optimize FX and settle everything in EUR on our end, but settle in in USD for the merchant. It will draw more from the USD balance than what is naturally in there from income. So we'll need dashboards and tooling long-term to manage this from a treasury perspective to always top-up and have sufficient balances across accounts for seamless payouts.

Ultimately, as a result, we will also need our own FX rates and do the conversion on our end.

But at stage 1, I think we can keep settlement in USD on our end too as we do with the merchants. Taking these complexities alongside the expansion to stage 2 – exposing multiple settlements to merchants, and ourselves at the same time.

Principally, I think our fees should apply on the "settlement amount". We might still be charged underlying fees in the "presentment amount", but with FX conversion on our end we should be protected that the ultimate fees are still at the same margin even after the conversion. But it feels cleaner to separate the financial operations that way:

Normalize currency (FX)

Charge fees on the settlement/balance currency of choice

Correct me if I'm wrong, but this also makes it easier right? As the fee logic remains intact based on current amount and currency?

Definitely easier :D

What about the conversion fees applied by Stripe (1%)? Should we swallow it or reflect it on the merchant?

engineering/design-documents/multi-currency.mdx

Yopi

Very good writeup. I agree with your proposal both on scenario 1 and implementation B.

It will give us some time to also consider other areas where there are currencies involved.

For example, in scenario 2: if you set settlement currency to EUR, what would it mean for comparison if you are ingesting costs in USD? We will probably need to track our own currency exchange rate to be able to display all money in the same currency.

birkjernstrom · 2025-11-12T12:38:02Z

engineering/design-documents/multi-currency.mdx

+
+### Key terms
+
+- Presentment Currency: The currency in which a payment/transaction is done, i.e. the price shown on the checkout page and customer's invoice.


I know Stripe calls it presentment currency, but to be honest, I really dislike the term :) Would be nice to find an alternative name we use that is clear, but more common tongue, e.g payment_currency

Well, I don't really expect to show that to the users — it's more of a term so we can all align on during this design phase :)

birkjernstrom · 2025-11-12T12:41:17Z

engineering/design-documents/multi-currency.mdx

+
+### Key terms
+
+- Presentment Currency: The currency in which a payment/transaction is done, i.e. the price shown on the checkout page and customer's invoice.


I think there might be a fourth one here too: "Display Currency". In the scenario of a currency being locked to USD for instance, but allowing it to be displayed in a local currency guesstimate across checkout, email etc? Something we discussed in the past and might still be relevant in the future even with a more robust and true multi-currency support which is the focus here?

Maybe, but I feel it may be out of the scope of the current proposal :)

birkjernstrom · 2025-11-12T12:43:11Z

engineering/design-documents/multi-currency.mdx

+
+### Scenario 1: Multiple Presentment Currencies, USD Settlement currency
+
+In this scenario, we would allow merchants to set prices in multiple currencies, and customers would be able to pay in their local currency. However, all funds would still be settled in USD.


Two core questions for me:

Can a product have multiple presentment currencies defined? E.g what it costs in USD, SEK, EUR and INR? Or only one?

Can the merchant change their settlement currency? E.g it's still locked to 1 at this stage, but a merchant can define it as either USD or EUR or ... for their entire account?

Personally, I think the answer should be yes to both above

Sorry, saw now that Scenario 2 covers question 2 above. But question 1 I'm not clear about here in this scenario still.

As we confirmed during the call, yes, a merchant should be able to set multiple currencies per product.

birkjernstrom · 2025-11-12T12:52:41Z

engineering/design-documents/multi-currency.mdx

+
+Then, we can quite quickly iterate to Scenario 2. Longer-term, we still have the possibility to expand easily towards Scenario 4 Variant 2 if we see a strong demand for it.
+
+From a technical standpoint, I would recommend to go with **Implementation B**. It feels cleaner and more consistent, and will save us from having to maintain two sets of amount fields in our models; even if it requires more work upfront.


I agree with this approach provided merchants can specify multiple presentment currencies for a product vs. one, e.g provide the prices in USD (might be their default – matching settlement currency), EUR, SEK, INR. Supporting specificity on a product-level vs. pure FX conversion based and PPP strategies too.

From there, I think it's smart to expand our support and configurability of settlement currency over time from USD. Starting with Scenario 2 of defining another settlement currency from USD, e.g EUR. Supporting multiple settlement currencies and thereby multiple balances will come, but later. But good that we make this implementation knowing that will come in the future to avoid making it harder still in the future.

I think it would be great to look at how we imagine this showing up in our API and data models though. Devils will be in the details there and especially considering backward compatibility. I think our current pricing should be the default one, e.g USD, for an account to support the amount, currency fields without an array or dict mapping. But that we introduce something like currencies (naming TBD) which offers a dict of <currency>: <amount> pairs.

Combined with finding another name for presentment_currency and how we store the actually paid amount/currency across our data models, e.g payment_amount and payment_currency, and amount + currency remaining as is and the normalized amounts in the configured settlement currency (USD at first).

The way I imagine to solve that:

A ProductPrice is tied to a unique currency. If a Product needs to support several currencies (say usd and eur), then we'll effectively have two ProductPrice attached, in usd and eur respectively.

The point of Implementation B is to avoid having presentment_amount/presentment_currency on the data models. We only store in the existing field (amount/currency) the actual amount/currency that was paid by the customer. The conversion to settlement currency is then only done at the Account transactions level.

pieterbeulque

Strong assessment overall, and I agree with the technical approach.

However, I think Scenario 1 has a viability issue: European startups wanting to operate in EUR/GBP would face significant conversion fees on every transaction if everything settles in USD. This maybe disqualifies it as a meaningful solution for the users currently requesting multi-currency support.

We might need to keep iterating to Scenario 2 for the initial release to avoid launching something that misses the mark?

frankie567 · 2025-11-13T09:42:08Z

Strong assessment overall, and I agree with the technical approach.

However, I think Scenario 1 has a viability issue: European startups wanting to operate in EUR/GBP would face significant conversion fees on every transaction if everything settles in USD. This maybe disqualifies it as a meaningful solution for the users currently requesting multi-currency support.

We might need to keep iterating to Scenario 2 for the initial release to avoid launching something that misses the mark?

Good point. I'm not sure if we have a lot of demands right now for that. WDYT @birkjernstrom?

pieterbeulque · 2025-11-13T12:48:18Z

To clarify, I'm talking about the use case of e.g. a Belgian company charging in EUR and expecting to be paid out in EUR. It was my assumption that this is the number 1 use case for multi-currency support, is that not correct then?

From my understanding of how payouts work, that's already possible with scenario 1 too, but they'd be hit unnecessarily by EUR → USD → EUR conversion rates & fees?

Edit — sorry, I understand things better now. So the question is whether we resolve what people are actually asking for when they request multi-currency support if we launch multiple presentment currencies without supporting matching settlement currencies too.

Edit 2 — regardless of explicit customer demand, I think it also makes sense to do the math if we can position ourselves competitively in terms of pricing if non-USD companies will have to incur these double fees (upon purchase by Stripe and upon payout either by Stripe or by the merchant's bank).

frankie567 · 2025-11-13T12:56:20Z

@pieterbeulque Well, my understanding was that the need was more about a merchant wanting to charge in the currency of the customer, but being fine with it being settled in usd in their side. But I might be wrong 😊

And yes, in the setup you describe, that's what would happen.

birkjernstrom · 2025-11-13T16:06:41Z

For the bigger customer we're chatting with now it's the ability to charge in 6 currencies, but for it all to settle in USD (Scenario 1). Needed before end of year.

But I agree that Scenario 2, i.e settle in other currencies too (EUR), is required in order for us to put this topic entirely to bed. However, I'm more than supportive of doing them sequenced like this. Scenario 1 introduces the currencies on the money inbound which is step 1 before changing the money outbound – step 2.

As long as we call that out clearly and state we're working on Scenario 2 in our docs around it, I don't think it's missing the mark. We ship iteratively on this to cater to Scenario 1 use cases (bigger US customers) and then expand to serve bigger European customers (Scenario 2).

pieterbeulque · 2025-11-13T18:06:38Z

Yep, agreed on the sequencing!

wip

aba7bec

mintlify bot deployed to staging November 7, 2025 16:46 View deployment

frankie567 mentioned this pull request Nov 7, 2025

Design Document: multi-currency support polarsource/polar#7717

Open

update

1feb49a

mintlify bot deployed to staging November 10, 2025 14:05 View deployment

update

f5450ba

mintlify bot deployed to staging November 10, 2025 14:11 View deployment

update

2ce6462

mintlify bot deployed to staging November 10, 2025 14:32 View deployment

update

026b675

mintlify bot deployed to staging November 10, 2025 14:42 View deployment

psincraian reviewed Nov 10, 2025

View reviewed changes

Yopi reviewed Nov 11, 2025

View reviewed changes

Yopi mentioned this pull request Nov 11, 2025

Increase minimum payout amount for certain currencies polarsource/polar#7753

Merged

birkjernstrom reviewed Nov 12, 2025

View reviewed changes

pieterbeulque reviewed Nov 12, 2025

View reviewed changes


		## Technical Considerations and Open Questions

		### Polar fees


		### Key terms

		- Presentment Currency: The currency in which a payment/transaction is done, i.e. the price shown on the checkout page and customer's invoice.


		### Scenario 1: Multiple Presentment Currencies, USD Settlement currency

		In this scenario, we would allow merchants to set prices in multiple currencies, and customers would be able to pay in their local currency. However, all funds would still be settled in USD.


		Then, we can quite quickly iterate to Scenario 2. Longer-term, we still have the possibility to expand easily towards Scenario 4 Variant 2 if we see a strong demand for it.

		From a technical standpoint, I would recommend to go with Implementation B. It feels cleaner and more consistent, and will save us from having to maintain two sets of amount fields in our models; even if it requires more work upfront.

Multi-currencies #18

Are you sure you want to change the base?

Multi-currencies #18

Uh oh!

Conversation

frankie567 commented Nov 7, 2025

Uh oh!

psincraian left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Yopi left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

frankie567 Nov 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pieterbeulque left a comment

Choose a reason for hiding this comment

Uh oh!

frankie567 commented Nov 13, 2025

Uh oh!

pieterbeulque commented Nov 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

frankie567 commented Nov 13, 2025

Uh oh!

birkjernstrom commented Nov 13, 2025

Uh oh!

pieterbeulque commented Nov 13, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

frankie567 Nov 12, 2025 •

edited

Loading

pieterbeulque commented Nov 13, 2025 •

edited

Loading