Subscription Billing: Upgrades, Coupons and Credits

Subscription Billing: Upgrades, Coupons and Credits

You've joined the billing team at a small SaaS company. Customers subscribe to a plan, are billed every 30 days, and can change plan or cancel at any time. Finance has flagged that upgrade charges are wrong, and the roadmap has two features queued behind that fix. All amounts are integer cents, and days are integer day numbers.

Codebase

How your code is run

run(operations: list[list]) -> list executes the operations in order against a fresh billing system and returns one result per operation. Every operation is [name, day, ...args]; day is an integer and never decreases. Errors are returned as "error: <code>" strings, never raised.

• An unknown operation name returns "error: unknown operation". A wrong number or type of arguments (or a non-integer day) returns "error: invalid arguments". Booleans are not integers.
• A customer has at most one non-cancelled subscription at a time; after cancel they may subscribe again. Subscription ids and invoice ids are allocated in order of success; a failed operation never uses one up.
• Cycles. A subscription started on day s is billed in cycles of 30 days: cycle n covers days s + 30n through s + 30n + 29. Cycle 0 is invoiced when the customer subscribes, with the line "<plan> plan, cycle 0" for the plan's price. The *current cycle* on day d is the one containing d, whether or not it has been invoiced.
• Plan changes take effect immediately. For an upgrade the customer is charged for the days left in the current cycle, where days left = (first day of the next cycle) - d. On the first day of a cycle that is 30; on its last day it is 1. The charge is (new price - old price) * days left / 30, rounded to the nearest cent once, on the total (halves round up), and appears as one invoice line "upgrade <old> to <new>, <days left> days". charged in the result is that amount and invoice the id of the invoice that carries it.

Worked example

[["subscribe", 0, "ann", "basic"],
 ["change_plan", 10, "sub-1", "team"],
 ["invoices", 10, "ann"],
 ["invoice", 10, "inv-2"]]

returns

["sub-1",
 {"charged": 5333, "credited": 0, "invoice": "inv-2"},
 ["inv-1", "inv-2"],
 {"id": "inv-2", "customer": "ann", "day": 10,
  "lines": [["upgrade basic to team, 20 days", 5333]], "total": 5333}]

(8000 * 20 / 30 = 5333.33.)

Part 1 — Upgrade charges are wrong

Goal. Customers upgrading mid-cycle are charged slightly the wrong amount, and one customer reports an upgrade after cancelling. Find and fix the causes.

Rules

1. Upgrade proration follows the formula above: the right number of days left, and rounding applied once to the whole amount rather than per day.
2. A cancelled subscription cannot change plan: error: subscription cancelled (checked right after subscription not found and before the plan is looked at).
3. An upgrade whose prorated charge rounds to 0 creates no invoice ("invoice": null).
4. Everything else in the table above already works.

Part 2 — Coupons

Goal. Marketing wants limited-use discount codes that customers redeem when they subscribe.

Rules

1. create_coupon(code, kind, value, max_redemptions, expires_day) with kind "percent" (value 1-100) or "fixed" (value >= 1 cents). max_redemptions is null (unlimited) or an integer >= 1; expires_day is null or an integer. Returns true. A bad kind/value/limit is error: invalid coupon; a code that already exists is error: coupon exists (checked after the first). Codes are case-sensitive.
2. subscribe(customer, plan, code) adds a second line to the cycle 0 invoice, "coupon <code>", with a negative amount, so the invoice total is the price minus the discount. A percent discount is price * value / 100 rounded to the nearest cent once, halves rounding up; a fixed discount is value, but never more than the price. The discount applies to that first invoice only; no later invoice is discounted.
3. Coupon errors are checked in this order, after unknown plan and already subscribed: unknown coupon; coupon expired (the coupon can be used on expires_day itself, and not after); coupon already redeemed (this customer has used this code before, even on a subscription they cancelled); coupon exhausted (max_redemptions redemptions already used).
4. A redemption is used up only when the subscription is actually created. Any failed subscribe leaves the coupon's remaining count untouched.

Example. A 10% coupon on basic: 1999 * 10 / 100 = 199.9, so the discount is 200 and the invoice lines are [["basic plan, cycle 0", 1999], ["coupon SAVE10", -200]] with total 1799.

Part 3 — Downgrades, account credit and idempotent cycle invoices

Goal. Support downgrades that give credit for the unused time, spend that credit on later invoices, and let the nightly billing job invoice renewals safely even when it retries.

Rules

1. A change_plan to a cheaper plan credits the customer instead of charging: credited = (old price - new price) * days left / 30, rounded to the nearest cent once, halves rounding up. The result is {"charged": 0, "credited": <amount>, "invoice": null}; the plan changes immediately and no invoice is issued. Credit is stored per customer and shown by credit_balance. Rules 1-3 of Part 1 still apply.
2. Account credit is spent automatically on every invoice issued afterwards (including upgrade and cycle 0 invoices): the amount spent is min(balance, invoice subtotal) where the subtotal is the sum of the lines *including any coupon discount*. If it is more than 0 the invoice gets a last line "account credit" with a negative amount, and the balance goes down by the same amount. An invoice total is never negative.
3. invoice_cycle(sub_id, cycle) returns the id of the invoice for cycle number cycle (an integer

>= 0), creating it if it does not exist yet. The new invoice has one line "<plan> plan, cycle <n>" for the price of the subscription's current plan, plus the account credit line if any. Checks, in this order: subscription not found; a negative cycle is error: invalid arguments; cycle not started if day is before the first day of that cycle; if that cycle was already invoiced return the existing id, creating nothing, spending no credit and not repricing, even if the subscription is cancelled; subscription cancelled; previous cycle not invoiced unless cycle is exactly one more than the latest invoiced cycle.

1. Cycle 0's invoice (created by subscribe) counts: invoice_cycle(sub, 0) returns it. Upgrade invoices are not cycle invoices.

Example. Ann is on team (subscribed on day 0) and downgrades on day 10 to basic: 8000 * 20 / 30 = 5333.33, so she is credited 5333. On day 30, invoice_cycle for cycle 1 creates an invoice with lines [["basic plan, cycle 1", 1999], ["account credit", -1999]] and total 0, and her balance falls to 3334. Calling it again returns the same invoice id and changes nothing.

Notes

• models.py, errors.py, catalog.py and config.py are known-good.
• You may use the AI assistant freely. Later parts must not break earlier ones; the hidden tests re-check every part. Finishing all three parts is the goal.