Billing portal
Billing portal lets each Customer replace a card, fix billing details, download receipts, change plans and cancel, on the Startup’s own Domain.
It is the billing section of the Portal, and nothing in it waits on the Startup.
Contract
The section lives at /portal/, under the Startup’s Brand. Stripe’s embedded form collects card details on that page, so no step sends the Customer to another domain.
| Customer need | What the Customer sees | Call |
|---|---|---|
| Replace a card | Saved Payment Sources, the default marked, and a form to add one | PaymentSource.add or PaymentSource.remove |
| Fix billing details | Billing email, address and tax ids, printed on every new Invoice | Customer.billingEmail, Customer.billingAddress and Customer.taxIds, set through Customer.update |
| Download a receipt | Every Invoice and receipt as a PDF that names the seller of record | Invoice.pdf |
| Pay a failed charge | The unpaid Invoice and one button that pays it with the new card | Invoice.collect |
| Switch plans | Each Offer the Customer can move to, and today’s prorated amount before confirming | Subscription.switch |
| Add or remove units | Units held against units in use, and the prorated amount | Subscription.resize |
| Pause | The date billing resumes | Subscription.pause |
| Cancel | One confirm; access lasts until the period closes | Subscription.unsubscribe |
| Undo a cancel | A button that keeps the Subscription until the period closes | Subscription.keep |
| Rule | Detail |
|---|---|
| Preview first | A plan or unit change runs Subscription.switch or Subscription.resize as try, shows the prorated charge, then runs as do on confirm; see Modes. |
| Exits never wait | Subscription.unsubscribe, a move to a cheaper Offer and Subscription.keep run at once, with no Limit, Approval or delay window. |
| Cancel parity | Subscription.unsubscribe takes no more steps than buying did, as the renewals floor row requires. |
| Failed payments | Every Dunning message links here, signed in, at the unpaid Invoice. |
| Own records only | PaymentSource.list and every view here return only the Customer’s own records; a Payment Source never moves to a sibling Startup. |
| Developer tools | A keyed Offer adds Portal.tools: keys, usage against each Limit, the request log, Watches, the version pin and the test twin of each key. |
Verbs
Interfaces
Example
A clinic’s renewal on shiftnote.app fails on an expired card. The Dunning email opens shiftnote.app/ at the unpaid Invoice, and the office manager adds a new default card, which pays it at once. She then lowers the plan from 12 members to 9 and sees that the lower price starts at the next renewal.