Plans and subscriptions
Paid plans through a payment provider's hosted checkout, kept in step by webhooks, with one function that says what an account may use.
This is an app part spec on Spekkr, published by juno. It is listed with the other specs. Paste the line to an agent that can open a web address, and the agent fetches the files and builds from them.
- Spec
juno/subscriptions- Version
- 0.1.2
- Published by
- juno
- Updated
- 15 Nov 2026
Build this spec
Build the spec at https://spekkr.com/juno/subscriptions/start.md.
Paste this to your AI agent. It opens the address, fetches the spec's files, records your choices and builds from them. Nothing to install, no account.
Published by juno.
What does the result look like?
What can I customize?
Your choices go into the line you copy. Anything else is yours to edit, but it leaves the tested path.
What do I get?
-
spec.mdRequirements and acceptance criteria.Plans and subscriptions
What this builds
Paid plans for an app. A person picks a plan and pays on the payment provider's own checkout page. The provider tells the app what happened, the app keeps its own copy of the subscription, and every part of the app asks one function what an account may use.
Read
spekkr.inputs.jsonfirst.payersays whether a user or a workspace subscribes.providersays which adapter is built. A trial laststrial_daysdays, and access lastsgrace_daysdays after a failed payment.free_planchanges R5. Useapp_nameon the pages.This spec needs the app to know who is signed in. It does not build sign-in. It never sees a card number: paying happens on the provider's pages.
Out of scope
- Charging by usage.
spekkr/usage-billingbuilds that. - Tax. The provider's checkout handles it or it is not handled.
- Coupons, seats and more than one subscription for one payer.
Requirements
Each requirement has an id. Tests name the id they cover.
R1. Plans
- Plans are a list in code: a key, a name, the price as shown, the provider's price id, and what the plan allows.
- What a plan allows is a set of features, each on or off, and a set of limits, each a whole number or unlimited.
- The list has a test: every plan names every feature and limit, so a new one cannot be forgotten on one plan.
Accept when: the test fails when a plan misses a feature.
R2. Check out
POST /billing/checkoutwith a plan starts the provider's hosted checkout and redirects to it.- A payer has one customer at the provider. It is created the first time and reused after, even when two requests arrive together.
- A payer who already has a subscription that is not ended is sent to R7 instead.
- Coming back from checkout changes nothing. The page says the payment is being confirmed, and shows the plan once R3 has stored it.
Accept when: two checkouts started at once leave one customer, and a forged visit to the "success" address grants nothing.
R3. Hear from the provider
POST /billing/webhookchecks the provider's signature on the raw bytes before reading them. A bad signature gets status 400.- Each event is stored by its id and handled once. A repeat is answered with 200 and does nothing.
- Events can arrive late or out of order. An event that is older than what the app already holds for that subscription is not applied.
- When in doubt, the app asks the provider for the subscription as it is now and stores that. The provider is right and the app's copy follows.
- An event of a kind the app does not use is stored and answered with 200.
Accept when: the same event twice changes the subscription once, an older event arriving after a newer one changes nothing, and a bad signature changes nothing.
R4. States
- A subscription is in one state from the table in
design.md:trialing,active,past_due,canceled. - "Cancel" from R7 does not end access at once. The subscription stays
activewith a mark that it ends when the paid period does. - Only R3 and R8 change the state. No page does.
Accept when: every arrow in the table in
design.mdhas a test, and no other change of state is possible.R5. What an account may use
can(payer, feature)answers yes or no.limit(payer, name)answers a number or unlimited.plan_of(payer)names the plan.- They read the app's own copy. They never call the provider.
- A payer with no subscription, or an ended one, is on the free plan if
free_planis on, and otherwise can use nothing that needs a plan. - A subscription that is
past_duekeeps its plan forgrace_daysdays from the first failed payment, and is treated as having none after that.
Accept when: each state in the table gives the access listed there, including one second before and one second after the grace ends.
R6. Trials
- If
trial_daysis more than 0, a first subscription starts astrialingfor that many days. - A payer gets one trial, ever. A second subscription starts as
active.
Accept when: a payer who cancels during a trial and subscribes again is charged at once.
R7. Manage
- "Manage billing" sends the payer to the provider's own portal for the card, the invoices, cancelling and changing plan.
- With
payerset toworkspace, only people who may manage the workspace can check out or open the portal. Everyone in it can see the plan.
Accept when: a member who may not manage the workspace gets 403 for both.
R8. Catch what was missed
- Once a day a job compares every subscription that is not ended with the provider, and stores the provider's version where they differ. Each difference is logged.
Accept when: a subscription changed at the provider with no event sent is right after the job runs.
R9. Pages
- A pricing page made from the list in R1, with the payer's own plan marked.
- A billing part of the settings: the plan, the state in words, the next payment date, and "Manage billing".
- A banner for
past_duethat says when access ends, and one for the last 3 days of a trial.
Accept when: each page works with a keyboard alone and at a 360 pixel wide screen.
Definition of done
- Every acceptance check above has an automated test, and all tests pass. Tests run against a stand-in provider and set the clock.
- No log line holds a key or a webhook secret.
- A README explains how to add a plan, how to ask
canfrom code, how to set up the webhook at the provider, and how to run the tests.
# Plans and subscriptions ## What this builds Paid plans for an app. A person picks a plan and pays on the payment provider's own checkout page. The provider tells the app what happened, the app keeps its own copy of the subscription, and every part of the app asks one function what an account may use. Read `spekkr.inputs.json` first. `payer` says whether a user or a workspace subscribes. `provider` says which adapter is built. A trial lasts `trial_days` days, and access lasts `grace_days` days after a failed payment. `free_plan` changes R5. Use `app_name` on the pages. This spec needs the app to know who is signed in. It does not build sign-in. It never sees a card number: paying happens on the provider's pages. ## Out of scope - Charging by usage. `spekkr/usage-billing` builds that. - Tax. The provider's checkout handles it or it is not handled. - Coupons, seats and more than one subscription for one payer. ## Requirements Each requirement has an id. Tests name the id they cover. ### R1. Plans - Plans are a list in code: a key, a name, the price as shown, the provider's price id, and what the plan allows. - What a plan allows is a set of features, each on or off, and a set of limits, each a whole number or unlimited. - The list has a test: every plan names every feature and limit, so a new one cannot be forgotten on one plan. Accept when: the test fails when a plan misses a feature. ### R2. Check out - `POST /billing/checkout` with a plan starts the provider's hosted checkout and redirects to it. - A payer has one customer at the provider. It is created the first time and reused after, even when two requests arrive together. - A payer who already has a subscription that is not ended is sent to R7 instead. - Coming back from checkout changes nothing. The page says the payment is being confirmed, and shows the plan once R3 has stored it. Accept when: two checkouts started at once leave one customer, and a forged visit to the "success" address grants nothing. ### R3. Hear from the provider - `POST /billing/webhook` checks the provider's signature on the raw bytes before reading them. A bad signature gets status 400. - Each event is stored by its id and handled once. A repeat is answered with 200 and does nothing. - Events can arrive late or out of order. An event that is older than what the app already holds for that subscription is not applied. - When in doubt, the app asks the provider for the subscription as it is now and stores that. The provider is right and the app's copy follows. - An event of a kind the app does not use is stored and answered with 200. Accept when: the same event twice changes the subscription once, an older event arriving after a newer one changes nothing, and a bad signature changes nothing. ### R4. States - A subscription is in one state from the table in `design.md`: `trialing`, `active`, `past_due`, `canceled`. - "Cancel" from R7 does not end access at once. The subscription stays `active` with a mark that it ends when the paid period does. - Only R3 and R8 change the state. No page does. Accept when: every arrow in the table in `design.md` has a test, and no other change of state is possible. ### R5. What an account may use - `can(payer, feature)` answers yes or no. `limit(payer, name)` answers a number or unlimited. `plan_of(payer)` names the plan. - They read the app's own copy. They never call the provider. - A payer with no subscription, or an ended one, is on the free plan if `free_plan` is on, and otherwise can use nothing that needs a plan. - A subscription that is `past_due` keeps its plan for `grace_days` days from the first failed payment, and is treated as having none after that. Accept when: each state in the table gives the access listed there, including one second before and one second after the grace ends. ### R6. Trials - If `trial_days` is more than 0, a first subscription starts as `trialing` for that many days. - A payer gets one trial, ever. A second subscription starts as `active`. Accept when: a payer who cancels during a trial and subscribes again is charged at once. ### R7. Manage - "Manage billing" sends the payer to the provider's own portal for the card, the invoices, cancelling and changing plan. - With `payer` set to `workspace`, only people who may manage the workspace can check out or open the portal. Everyone in it can see the plan. Accept when: a member who may not manage the workspace gets 403 for both. ### R8. Catch what was missed - Once a day a job compares every subscription that is not ended with the provider, and stores the provider's version where they differ. Each difference is logged. Accept when: a subscription changed at the provider with no event sent is right after the job runs. ### R9. Pages - A pricing page made from the list in R1, with the payer's own plan marked. - A billing part of the settings: the plan, the state in words, the next payment date, and "Manage billing". - A banner for `past_due` that says when access ends, and one for the last 3 days of a trial. Accept when: each page works with a keyboard alone and at a 360 pixel wide screen. ## Definition of done - Every acceptance check above has an automated test, and all tests pass. Tests run against a stand-in provider and set the clock. - No log line holds a key or a webhook secret. - A README explains how to add a plan, how to ask `can` from code, how to set up the webhook at the provider, and how to run the tests.
- Charging by usage.
-
design.mdData model, rules and flows.Design
This file fixes the parts that are easy to get wrong. Choose the language and framework that fit the person's project; nothing here depends on them.
Data model
Use the database in the
databaseinput. The payer is a user or a workspace, as thepayerinput says.Table Columns billing_customerspayer_id(primary key),provider_customer_id(unique),trial_used,created_atsubscriptionspayer_id(primary key),provider_subscription_id(unique),plan,state,ends_with_period,period_end,trial_end,past_due_since,provider_updated_atbilling_eventsid(the provider's event id, primary key),type,received_at,handled_at,payloadOne row per payer in
subscriptions. A new subscription after an ended one replaces the row.States
State Means Access trialingIn a trial, not yet charged The plan activePaid up The plan past_dueA payment failed and the provider is retrying The plan for the grace_daysinput frompast_due_since, then nonecanceledEnded None From To When none trialingCheckout completes, trial_daysis more than 0, and no trial was usednone activeCheckout completes otherwise trialingactiveThe first payment succeeds trialingcanceledCancelled in the trial, or the first payment fails for good activepast_dueA payment fails past_dueactiveA retry succeeds past_duecanceledThe provider gives up activecanceledThe paid period ends with ends_with_periodsetThe adapter
Everything provider-specific sits behind four operations. Tests use a stand-in that implements them in memory.
Operation Does ensure_customer(payer)Returns the provider's customer id, creating it if needed checkout_url(customer, plan, trial_days)Returns the address of a hosted checkout portal_url(customer)Returns the address of the provider's portal read_subscription(id)Returns the subscription as the provider has it now and one function that turns a webhook's raw bytes and headers into either "signature bad" or an event with an id, a time, a kind and a subscription id.
Stripe
When the
providerinput isstripe. Confirm the event names in Stripe's documentation before building.Stripe event The app does checkout.session.completedReads the subscription and stores it customer.subscription.updatedReads the subscription and stores it customer.subscription.deletedSets canceledinvoice.payment_failedSets past_due_sinceif it is empty, then reads the subscriptioninvoice.paidClears past_due_since, then reads the subscriptionStripe's
trialing,active,past_dueandcanceledmap to the same names. Treatunpaidandincomplete_expiredascanceled, andincompleteas no subscription yet.Rules
- Create the customer inside a transaction that first inserts the
billing_customersrow with an empty id, so a second request waits on the row instead of creating a second customer. Give the provider an idempotency key made from the payer's id as well. - Insert the
billing_eventsrow before handling. A unique-key failure means the event was seen: answer 200 and stop. - Store
provider_updated_atfrom the provider's own time on the event or the subscription, and apply nothing older than it. - Take the time from one function, so tests can set it.
Configuration
Secret Purpose DATABASE_URLConnection string for the chosen database. PAYMENT_PROVIDER_KEYCalls the provider. PAYMENT_WEBHOOK_SECRETChecks the signature on webhooks. Who is signed in
The spec reaches the app's sign-in through one function,
current_user(request). It answers with the person's id, and says whether they are an administrator where this spec asks. In the person's app it reads their session.When there is no app yet, build this stand-in and nothing more: a page that lists two seeded people, one of them an administrator, with a button for each that sets a signed cookie naming them. The stand-in refuses to start in production.
What this spec leaves to you
Where this spec names something, use that name, so that two builds of it agree. Where it does not, the choice is yours. List what you chose in the README.
# Design This file fixes the parts that are easy to get wrong. Choose the language and framework that fit the person's project; nothing here depends on them. ## Data model Use the database in the `database` input. The payer is a user or a workspace, as the `payer` input says. | Table | Columns | | --- | --- | | `billing_customers` | `payer_id` (primary key), `provider_customer_id` (unique), `trial_used`, `created_at` | | `subscriptions` | `payer_id` (primary key), `provider_subscription_id` (unique), `plan`, `state`, `ends_with_period`, `period_end`, `trial_end`, `past_due_since`, `provider_updated_at` | | `billing_events` | `id` (the provider's event id, primary key), `type`, `received_at`, `handled_at`, `payload` | One row per payer in `subscriptions`. A new subscription after an ended one replaces the row. ## States | State | Means | Access | | --- | --- | --- | | `trialing` | In a trial, not yet charged | The plan | | `active` | Paid up | The plan | | `past_due` | A payment failed and the provider is retrying | The plan for the `grace_days` input from `past_due_since`, then none | | `canceled` | Ended | None | | From | To | When | | --- | --- | --- | | none | `trialing` | Checkout completes, `trial_days` is more than 0, and no trial was used | | none | `active` | Checkout completes otherwise | | `trialing` | `active` | The first payment succeeds | | `trialing` | `canceled` | Cancelled in the trial, or the first payment fails for good | | `active` | `past_due` | A payment fails | | `past_due` | `active` | A retry succeeds | | `past_due` | `canceled` | The provider gives up | | `active` | `canceled` | The paid period ends with `ends_with_period` set | ## The adapter Everything provider-specific sits behind four operations. Tests use a stand-in that implements them in memory. | Operation | Does | | --- | --- | | `ensure_customer(payer)` | Returns the provider's customer id, creating it if needed | | `checkout_url(customer, plan, trial_days)` | Returns the address of a hosted checkout | | `portal_url(customer)` | Returns the address of the provider's portal | | `read_subscription(id)` | Returns the subscription as the provider has it now | and one function that turns a webhook's raw bytes and headers into either "signature bad" or an event with an id, a time, a kind and a subscription id. ## Stripe When the `provider` input is `stripe`. Confirm the event names in Stripe's documentation before building. | Stripe event | The app does | | --- | --- | | `checkout.session.completed` | Reads the subscription and stores it | | `customer.subscription.updated` | Reads the subscription and stores it | | `customer.subscription.deleted` | Sets `canceled` | | `invoice.payment_failed` | Sets `past_due_since` if it is empty, then reads the subscription | | `invoice.paid` | Clears `past_due_since`, then reads the subscription | Stripe's `trialing`, `active`, `past_due` and `canceled` map to the same names. Treat `unpaid` and `incomplete_expired` as `canceled`, and `incomplete` as no subscription yet. ## Rules - Create the customer inside a transaction that first inserts the `billing_customers` row with an empty id, so a second request waits on the row instead of creating a second customer. Give the provider an idempotency key made from the payer's id as well. - Insert the `billing_events` row before handling. A unique-key failure means the event was seen: answer 200 and stop. - Store `provider_updated_at` from the provider's own time on the event or the subscription, and apply nothing older than it. - Take the time from one function, so tests can set it. ## Configuration | Secret | Purpose | | --- | --- | | `DATABASE_URL` | Connection string for the chosen database. | | `PAYMENT_PROVIDER_KEY` | Calls the provider. | | `PAYMENT_WEBHOOK_SECRET` | Checks the signature on webhooks. | ## Who is signed in The spec reaches the app's sign-in through one function, `current_user(request)`. It answers with the person's id, and says whether they are an administrator where this spec asks. In the person's app it reads their session. When there is no app yet, build this stand-in and nothing more: a page that lists two seeded people, one of them an administrator, with a button for each that sets a signed cookie naming them. The stand-in refuses to start in production. ## What this spec leaves to you Where this spec names something, use that name, so that two builds of it agree. Where it does not, the choice is yours. List what you chose in the README.
- Create the customer inside a transaction that first inserts the
-
tasks.mdBuild tasks in order, each with a check.Tasks
Work in order. Finish a task's check before starting the next.
- Set up. Add the tables in
design.md, the adapter interface and the stand-in provider. If there is no app yet, build the smallest one: a signed-in user, and a workspace ifpayerisworkspace. Check: migrations run from empty and the stand-in passes its own tests. - Plans (R1). Check: the R1 test passes.
- States (R4). A pure function from a state and an event to the next state. Check: a test covers every arrow in the table in
design.md. - What an account may use (R5). Use
grace_daysandfree_plan. Check: the R5 acceptance tests pass with a clock the tests set. - Check out (R2) and trials (R6). Use
trial_days. Check: the R2 and R6 acceptance tests pass. - Webhooks (R3). Check: the R3 acceptance tests pass.
- The real adapter. For the
providerinput. Skip if it isother. Check: the adapter passes the same tests as the stand-in, against the provider's test mode or its recorded answers. - Manage (R7) and the daily job (R8). Check: the R7 and R8 acceptance tests pass.
- Pages (R9). Use the
app_nameinput. Check: every page can be used with a keyboard alone and at 360 pixels wide. - Finish. Write the README and run the whole test suite. Check: every item under "Definition of done" in
spec.mdis true.
# Tasks Work in order. Finish a task's check before starting the next. 1. **Set up.** Add the tables in `design.md`, the adapter interface and the stand-in provider. If there is no app yet, build the smallest one: a signed-in user, and a workspace if `payer` is `workspace`. Check: migrations run from empty and the stand-in passes its own tests. 2. **Plans (R1).** Check: the R1 test passes. 3. **States (R4).** A pure function from a state and an event to the next state. Check: a test covers every arrow in the table in `design.md`. 4. **What an account may use (R5).** Use `grace_days` and `free_plan`. Check: the R5 acceptance tests pass with a clock the tests set. 5. **Check out (R2) and trials (R6).** Use `trial_days`. Check: the R2 and R6 acceptance tests pass. 6. **Webhooks (R3).** Check: the R3 acceptance tests pass. 7. **The real adapter.** For the `provider` input. Skip if it is `other`. Check: the adapter passes the same tests as the stand-in, against the provider's test mode or its recorded answers. 8. **Manage (R7) and the daily job (R8).** Check: the R7 and R8 acceptance tests pass. 9. **Pages (R9).** Use the `app_name` input. Check: every page can be used with a keyboard alone and at 360 pixels wide. 10. **Finish.** Write the README and run the whole test suite. Check: every item under "Definition of done" in `spec.md` is true. - Set up. Add the tables in
Is it for me?
- Kind
- app part
- Platforms
- web, backend
What does it need?
- Accounts
- A payment provider account
- Agent permissions
- shell, network
- Secrets it reads
DATABASE_URLPAYMENT_PROVIDER_KEYPAYMENT_WEBHOOK_SECRET
What changed?
- 0.1.215 Nov 2026Names what it builds.
- 0.1.114 Nov 2026Says "person" where it said "buyer".
- 0.1.014 Nov 2026Moved from dwrtz/subscriptions.
For agents: start.md says how to build this spec, spec.json holds everything on this page, and bundle.tar.gz holds its files.