Orders, refunds, subscriptions and trials in Polar
Once Polar is connected and its products are mapped, Sealcord turns Polar’s events into licence changes. This page says what to expect, so you can answer a customer or a support question. The Console lists every webhook and what it did under Webhooks, Incoming.
In Polar, send these events to your integration’s webhook URL: order.paid, order.refunded,
subscription.created, subscription.active, subscription.updated, subscription.canceled
and subscription.revoked. Sealcord records any other event and does nothing with it.
What happens
Section titled “What happens”| What happens in Polar | What Sealcord does |
|---|---|
| A customer pays for a mapped one-time product | Issues a licence, once, however often Polar repeats the event |
| A customer pays for a mapped subscription | Issues a licence on the first payment |
| A subscription renews | Nothing: the same key keeps working, since renewals need no new key |
| A customer cancels a subscription | Nothing yet: access runs to the end of the paid period |
| The subscription ends | Applies the mapping’s choice: expires the licence (the default) or revokes it |
| A full refund of the order that issued a licence | Applies the mapping’s choice: revokes the licence (the default) or leaves it |
| A partial refund, or a refunded renewal | Records it and changes nothing |
| An order or subscription for an unmapped product | Issues nothing, records it as ignored and emails your owners and admins |
A paid order with no customer email issues nothing and is recorded as ignored: look into it by hand.
Subscriptions
Section titled “Subscriptions”A subscription’s key carries no expiry unless the mapping sets key_valid_days. When the
subscription ends, the licence is expired or revoked, as the mapping says, and the next status
check from the app sees it. Cancelling is not ending: Polar keeps the subscription active to the
end of the period the customer paid for, and the licence ends when Polar says the subscription
has.
A licence that you or a refund ended is never brought back by a later subscription event. Sealcord reinstates only a licence that ended because its subscription ended, when the subscription becomes active again.
Refunds
Section titled “Refunds”A refund revokes the licence only when it is a full refund of the order that issued the licence,
and the mapping’s on_refund is revoke. If the refund reaches Sealcord before the order does,
Sealcord remembers it, and the order that follows issues no licence.
Trials
Section titled “Trials”A Polar subscription that starts with a trial issues a trial licence at once: an active licence with a trial end. Your app sees an ordinary active licence, and the key does not change.
- While it is a trial, a verdict is valid at most a day past the trial’s end (why).
- When the customer pays, the trial converts: the trial end is cleared and the key stays the same. The licence’s audit log says it was converted.
- If Polar moves the trial’s end, the licence follows.
- If the subscription ends during the trial, the licence ends as for any subscription.
- If the conversion never reaches Sealcord, Sealcord asks Polar about every trial two hours after its end and settles it, so a paying customer is not locked out.
A trial issued by hand ends with its key, and is never checked with Polar.
When your plan has no room
Section titled “When your plan has no room”If an order or subscription would take your organization past its plan’s number of active licences, Sealcord does not lose it. It records the event as deferred (Webhooks, Incoming shows it with the detail “deferred: plan limit reached”), and issues the licence once your plan allows it, after you upgrade or revoke or expire licences you no longer need. Licences already issued keep working.
A subscription licence whose subscription just ended keeps its place in your count for 30 days. If the customer renews in that time, the licence is reinstated whatever your plan; after it, the renewal counts like any new licence.
Repeats and order
Section titled “Repeats and order”Polar delivers an event at least once, sometimes twice at the same time and not always in order. Sealcord applies each delivery once, and keeps one licence for each order or subscription, so a repeat issues nothing new. An event older than the last one it applied to a licence is recorded and changes nothing, so a late event cannot undo a conversion.
Alerts
Section titled “Alerts”Sealcord emails your organization’s owners and admins, and members who turned it on, when an event was ignored because the product is not mapped, the order had no customer email or the event could not be read, or when your plan deferred an order or a subscription. It sends at most one such email a day for each integration and reason. Each member chooses their alerts in the Console.
Questions
Section titled “Questions”Will a customer’s key change when their subscription renews?
Section titled “Will a customer’s key change when their subscription renews?”No. The key stays the same through renewals and when a trial converts.
What does a customer see when their subscription ends?
Section titled “What does a customer see when their subscription ends?”Their app’s next status check answers a signed revoked verdict, with the reason expired when
the mapping expires licences, or revoked when it revokes them. If the licence expired, its key
has an end (the mapping’s key_valid_days) and you set a renewal link, My licences shows them
where to renew (how).
Why does a refunded customer still have a licence?
Section titled “Why does a refunded customer still have a licence?”Either the refund was partial, the refunded order was a renewal and not the one that issued the
licence, or the mapping’s on_refund is none. You can revoke a licence by hand in the Console.
What happens to an ignored order after I fix the mapping?
Section titled “What happens to an ignored order after I fix the mapping?”Nothing is replayed. Issue that customer’s licence by hand, with external_ref set to the Polar order id, so you
can find it later.