Skip to content

Conversation

frankie567
Copy link
Member

No description provided.


When the Customer uses the merchant's app, the app tracks the usage and reports it to Polar using the Event Ingestion API. Polar deducts the cost of the usage from the Customer's Wallet balance. We inform the merchant of the new balance using a webhook.

We don't try to have any kind of blocking in case of low balance. It's up to the merchant to decide how to handle that, by estimating the cost of the usage before reporting it and compare it with the balance.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What if the merchant does nothing, can the customer get a negative balance?

Will the wallet be used for prorations?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The choice I made here is to not go negative, ever. If the usage surpasses the balance, then it's just lost on the merchant. Sounds a bit extreme, but that's the only way to make the Wallet safe for the user; otherwise, they could end up with big negative balance, which would entirely defeat the purpose.


The way I see it, Wallets can only be used to pay for metered price with Wallet enabled. Not fixed price or prorations of fixed price.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My proposal is to cover as much as possible of the Billing Entry with the Wallet balance, and lose the rest. This way, we don’t have to deal with negative balance, and the Customer can always top-up their Wallet to continue using the service.

So, from here I understand that if the customer has a $5 wallet, but the merchant does nothing and the customer goes to $6 metered price. We will display $0 to the wallet. 🤔

What will be the options to the merchant, cancel the subscription only?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or make sure there is enough money on the Wallet before accepting a new request

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

understood! Then I think there should be an easy API to make sure that we can serve this easily as it will be done on every client and every request.

Maybe something like wallet.enough_balance(meter)?

@frankie567 frankie567 force-pushed the wallets-design-document branch from 76878ec to a401f04 Compare October 15, 2025 07:38
@frankie567 frankie567 merged commit 54afa3a into main Oct 15, 2025
2 checks passed
@frankie567 frankie567 deleted the wallets-design-document branch October 15, 2025 07:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants