Polar
A payment integration links your Sealcord organization to your own Polar organization. Polar keeps the money; Sealcord keeps the licences. Once connected and mapped, Polar’s webhooks issue a licence for each paid order of a product you mapped, and end it on a refund or when a subscription ends. Connecting takes five steps, about ten minutes.
You do not need an integration to sell through Polar: your own backend can issue through the Admin API on Polar’s webhook instead.
Connect
Section titled “Connect”- Create an organization access token in Polar, with the read scopes
organizations:read,products:read,orders:readandsubscriptions:read. Addcustomer_sessions:writeonly if your customers should reach Polar’s customer portal from their licence (how). - Paste it in the Console, under Payment integrations, choosing sandbox or production. Only
an owner or admin connects an integration; an admin API key cannot. Sealcord asks Polar which
organization the token belongs to, and refuses a token Polar does not accept, one without
organizations:read, or one that is not an organization’s. A token missing one of the other scopes is refused later, when Sealcord needs it, such as when you save a mapping. - Add the webhook endpoint in Polar (Settings, Webhooks) with the URL the Console shows for
the integration under Webhooks, Incoming,
https://api.sealcord.com/v1/webhooks/polar/<integration id>, in the Raw format, and the events listed on Orders, refunds, subscriptions and trials. - Paste the endpoint’s secret in the Console, under Webhooks, Incoming. It is write-only:
once saved it is never shown again, and you can replace or remove it. Until it is set,
Sealcord answers Polar’s webhooks with
503, and Polar retries them, so no order is lost. - Map your products so a paid order knows which licence to issue: Map Polar products. An order for a product without a mapping issues nothing.
Sealcord only reads from your Polar organization, apart from opening a customer portal session when one of your customers asks for one (portal). It never changes or deletes anything in it, and never creates the webhook endpoint for you.
Status and upkeep
Section titled “Status and upkeep”An integration is in one of three states:
| Status | Meaning |
|---|---|
active |
Polar accepts the token |
needs_attention |
Polar stopped accepting the token, or it now belongs to another Polar organization. Webhooks still work, since they need only the secret |
disconnected |
You erased its credentials. Its webhook answers 404 |
- Check asks Polar again. A working token sets the status back to
active; a token Polar no longer accepts, or one that now belongs to another Polar organization, setsneeds_attention. If Polar is down the check answers an error and changes nothing. - Disconnect erases the token and the webhook secret. Licences and mappings stay. Delete the endpoint in Polar yourself. Connecting the same Polar organization again from the same Sealcord organization brings the same integration back, with its webhook URL and mappings, and without a secret.
- Each integration is yours alone. Your webhook route reads only your mappings and issues only your organization’s products. A Polar organization can be connected to one Sealcord organization at a time.
You can list your integrations and manage their mappings with the Admin API (scopes polar:read
and polar:write) or an AI assistant; connecting, the token and the webhook secret stay
in the Console. Your plan decides how many integrations you may connect, and every plan allows
at least one.
Questions
Section titled “Questions”Do I need Polar’s license keys?
Section titled “Do I need Polar’s license keys?”No, and Sealcord does not use them. Polar’s keys are opaque strings that only Polar can check, so an app could not verify them offline. Sealcord issues its own signed keys when Polar reports a paid order, and delivers them through Polar’s success page and a lookup.
Can I try it with Polar’s sandbox?
Section titled “Can I try it with Polar’s sandbox?”Yes. Choose sandbox when you connect, with a sandbox token and a sandbox webhook. A sandbox purchase issues a licence in your Sealcord organization like any other, so revoke test licences you do not need.
What if Polar sends an event before I set the secret?
Section titled “What if Polar sends an event before I set the secret?”Sealcord answers 503 integration_webhook_not_configured, and Polar retries it later, so the
order is applied once you set the secret.
What if my plan has no room for another licence?
Section titled “What if my plan has no room for another licence?”The order is kept, not lost, and issued once your plan allows it. See Orders, refunds, subscriptions and trials.