# Usage-based billing ## What this builds A billing service for a product that charges by usage. The product reports usage events. The service totals them per customer and billing period, prices them against the customer's plan, issues an invoice, and collects payment. Read `spekkr.inputs.json` first. Every amount is in the `currency` input. The person's other choices decide the first meter, whether plans include usage, and how invoices are paid. ## Out of scope - Tax calculation. Invoices carry a tax line that is always zero in this version. - More than one currency. - Refunds and credit notes. - Seat-based pricing. ## Terms - **Meter**: one kind of usage, counted in whole units. The first is the `meter_name` input. - **Plan**: a monthly base fee, a price per unit for each meter, and, if `included_usage` is on, an included amount per meter. - **Period**: one calendar month in UTC. ## Requirements Each requirement has an id. Tests name the id they cover. ### R1. Usage events - The product sends events with a customer id, a meter, a quantity, a timestamp and an idempotency key. - The endpoint is authenticated with `INGEST_API_KEY`. - Sending the same idempotency key twice records the event once and answers with success both times. - An event with a quantity below 1, an unknown meter or an unknown customer is refused with a message that names the problem. - An event is counted in the period of its timestamp. Events for a period that has been invoiced are refused. Accept when: 1,000 events sent twice in random order produce the same totals as sending them once. ### R2. Plans and subscriptions - An operator creates plans. A plan in use cannot be edited; create a new one instead. - A customer has at most one active subscription. - Changing plan takes effect at the start of the next period. - Cancelling ends the subscription at the end of the current period. Accept when: a mid-period plan change leaves the current period priced on the old plan. ### R3. Rating - Usage for a meter is the sum of quantities in the period. - Billable units are usage minus the included amount, never below zero. With `included_usage` off, the included amount is zero. - The charge for a meter is billable units times the unit price. - All money is held as whole minor units, such as cents. Unit prices may have up to four extra decimal places; round each line to the nearest minor unit, halves away from zero, once, after multiplying. Accept when: the worked examples in `design.md` produce exactly the amounts shown. ### R4. Invoices - On the first day of each month the service issues one invoice per active subscription for the period that just ended. - An invoice has a base-fee line, one line per meter with billable units, a zero tax line and a total. The total equals the sum of its lines. - Running the invoice job twice for a period creates no duplicates. - An issued invoice never changes, except its status. - Invoice numbers increase by one with no gaps. Accept when: running the job three times for one period leaves exactly one invoice per subscription, and every total equals the sum of its lines. ### R5. Collection - `payment_provider`: charge the customer's saved payment method for the invoice total. Mark the invoice paid only when the provider's signed webhook confirms it. Retry a failed charge after 3, 5 and 7 days, then mark the invoice uncollectible. - `manual`: an operator marks an invoice paid and records a reference. - A paid invoice cannot be charged again. Use the payment provider's current documentation for every API call. Do not rely on memory for endpoint names, fields or webhook formats. Accept when: a duplicated or replayed webhook leaves the invoice paid once, and a webhook with a bad signature is refused. ### R6. Payment reminders Only if `payment_reminders` is on. Email the customer when an invoice is 3 and 10 days overdue. Stop when it is paid. Accept when: a paid invoice sends no further reminders. ### R7. Operator pages - Customers with their plan and this period's usage so far. - Invoices with status, and one invoice with its lines. - Plans, with a form to create one. Accept when: the usage shown for a customer equals the sum of their events for the period. ## Definition of done - Every acceptance check above has an automated test, and all tests pass. - A README explains how to configure the secrets, send a test event and run the invoice job by hand.