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?

Plans and subscriptions: pricing desktopPlans and subscriptions: return confirmingPlans and subscriptions: billing past duePlans and subscriptions: pricing mobile

What can I customize?

Database
Who pays One person, or a workspace that several people share.
Payment provider For other, the spec builds the interface and a stand-in, and you write the adapter.

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.md Requirements 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.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.
    # 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.
    

    Open spec.md as plain text

  • design.md Data 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 database input. The payer is a user or a workspace, as the payer input says.

    TableColumns
    billing_customerspayer_id (primary key), provider_customer_id (unique), trial_used, created_at
    subscriptionspayer_id (primary key), provider_subscription_id (unique), plan, state, ends_with_period, period_end, trial_end, past_due_since, provider_updated_at
    billing_eventsid (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

    StateMeansAccess
    trialingIn a trial, not yet chargedThe plan
    activePaid upThe plan
    past_dueA payment failed and the provider is retryingThe plan for the grace_days input from past_due_since, then none
    canceledEndedNone
    FromToWhen
    nonetrialingCheckout completes, trial_days is more than 0, and no trial was used
    noneactiveCheckout 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_period set

    The adapter

    Everything provider-specific sits behind four operations. Tests use a stand-in that implements them in memory.

    OperationDoes
    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 eventThe app does
    checkout.session.completedReads the subscription and stores it
    customer.subscription.updatedReads the subscription and stores it
    customer.subscription.deletedSets canceled
    invoice.payment_failedSets past_due_since if it is empty, then reads the subscription
    invoice.paidClears 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

    SecretPurpose
    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.
    

    Open design.md as plain text

  • tasks.md Build tasks in order, each with a check.

    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.
    # 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.
    

    Open tasks.md as plain text

Is it for me?

Platforms
web, backend

What does it need?

Accounts
A payment provider account
Agent permissions
shell, network
Secrets it reads
DATABASE_URL PAYMENT_PROVIDER_KEY PAYMENT_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.