Checkouts, refunds, subscriptions and trials in Stripe
Once Stripe is connected and its prices or products are mapped, Sealcord turns Stripe’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 and events, Incoming. The rules every provider shares, such as repeats, the renewal hold and plan limits, are on How payment integrations work.
In Stripe, send these events to your integration’s webhook URL:
checkout.session.completedandcheckout.session.async_payment_succeededcustomer.subscription.created,customer.subscription.updatedandcustomer.subscription.deletedinvoice.paidcharge.refunded
Sealcord records any other event and does nothing with it.
What happens
Section titled “What happens”| What happens in Stripe | What Sealcord does |
|---|---|
| A customer pays a one-time checkout for a mapped price | Issues a licence, once, however often Stripe repeats the event |
| A checkout pays by a delayed method and is still pending | Nothing yet; the licence is issued when checkout.session.async_payment_succeeded arrives |
| A customer starts a mapped subscription (active or trialing) | Issues a licence |
| A subscription renews | Nothing: the same key keeps working |
| A customer cancels at the end of the period | Nothing yet: access runs to the end of the paid period |
| The subscription is canceled, unpaid, expired or paused | Applies the mapping’s choice: expires the licence (the default) or revokes it |
| A subscription is past due or incomplete | Nothing: Stripe is still retrying a payment |
| A full refund of the payment 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 |
| A checkout or subscription for an unmapped price and product | Issues nothing, records it as ignored and emails your owners and admins |
A paid checkout with no customer email issues nothing and is recorded as ignored: look into it by hand. Sealcord decides from the state of the checkout or subscription when it reads it from Stripe, not from the name of the event, so events that arrive out of order still end up right.
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: Stripe keeps the subscription active to the
end of the period the customer paid for, and the licence ends when Stripe says the subscription
has. If the customer comes back and the subscription becomes active again, the licence is
reinstated, but only if it ended because the subscription ended: a licence you or a refund ended
stays ended.
Refunds
Section titled “Refunds”A refund revokes the licence only when it is a full refund of the payment 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 Stripe subscription that starts with a trial issues a trial licence at once, with the trial’s end from the subscription. The general rules are on How payment integrations work. What is particular to Stripe:
- A trial converts when the first invoice after it is paid. At the end of a trial Stripe marks the subscription active before it charges the first invoice, about an hour later, so active alone does not convert a licence. The trial’s own first invoice is for nothing and converts nothing.
- A paid renewal invoice converts too, whatever its amount, through
invoice.paid, which is why Sealcord asks for that event.
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.
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 payment 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 checkout after I fix the mapping?
Section titled “What happens to an ignored checkout after I fix the mapping?”An ignored event is not replayed, and resending it from Stripe’s dashboard answers a duplicate. Issue that customer’s licence by hand, with external_ref set to the Stripe payment intent id, so you can
find it later.
Why was a delivery recorded with a live-mode or test-mode note?
Section titled “Why was a delivery recorded with a live-mode or test-mode note?”The event came from the other mode than the integration’s. A sandbox integration ignores live events and a production one ignores test events.