← All posts

Engineering · 2026.10.10 · 4 min

From Performance Fees to a Flat Annual Fee: Design Decisions Behind Subscription Billing and Promotions

EZLO switched from performance fees to subscriptions. Plan limits shipped before billing, promo bonuses freeze onto the invoice, the 30-day notice only gates passive charges, and suspension never touches users' own lending toggles.

Reading
Theme
Size
Width

EZLO's pricing changed from a performance fee to a fixed-price subscription. These were the main design decisions. Plan limits shipped before billing. Bonus months from promotions are frozen onto the invoice when it's issued, so later rule changes never rewrite entitlements that already exist. The "30 days' notice before charging" rule only gates charge paths the user didn't actively start. Suspension is handled by the engine excluding the user, not by touching the user's own lending toggle. Prices and plan details aren't covered in this post.

The idea behind a performance fee is intuitive: however much extra the bot earns you, it takes a cut. I first built a shadow ledger that measured the fee without charging it. The problem is that a performance fee requires precisely measuring the bot's contribution, unrealized earnings and the amounts actually credited. The billing semantics get complicated, and any small error on the books changes what gets charged.

Switching to subscriptions wasn't just a matter of changing the price either. Plan limits, an invoice state machine, payment address monitoring, expiry reminders, admin corrections and user notifications all had to exist.

Limits first, then billing

The subscription data model and plan limits shipped first, and billing started afterward, to avoid collecting money first and adding the limits later.

The plan limits got another fix after that. A single user can have multiple lending configs, and each one used to check the limit on its own, which effectively multiplied the limit. Now multiple configs in the same cycle share one quota.

Illustration: before, each of a user's lending configs checked the plan limit on its own, so together they multiplied the limit; now configs in the same cycle share one quota and together stay within the plan limit. Illustrative; bar lengths are not actual quotas.

Payments go through invoices plus a movements watcher. The watcher talks directly to Bitfinex's real data, so receiving addresses, deposit events and invoice status can be reconciled against each other. Building this part myself means one less external payment service to depend on, and the cost is that reconciliation is my responsibility. The payment page, notifications and admin actions all shipped together, so users and operations see the same set of states.

Promotions: bonuses frozen on the invoice

Annual-plan promotions are built as a data model with rules, not hardcoded into frontend copy.

The most important decision is that bonus months are frozen into the invoice's period_end at the moment it's issued. However the campaign rules change later, they never go back and rewrite entitlements on invoices that already exist.

Illustration: when an invoice is issued, the plan period plus promotional bonus months is written into its period_end; when campaign rules change later, the period_end of existing invoices is not rewritten. Illustrative; lengths are not actual plan or bonus durations.

A few other rules:

  • A user who qualifies for multiple campaigns can stack them, but each person can redeem a given campaign only once.
  • Campaigns with redemptions can't be deleted, which preserves the audit trail for accounting.
  • When an overdue invoice is voided, the campaign redemptions it used are released too.
  • Campaigns only apply to checkouts the user starts, not to auto-renewals, so long-term billing rules don't get tied to an old campaign.

Permissions are separate too. Managing campaigns requires the permission to manage fees, while read-only access only needs the permission to view users. Operational lookups and price control stay apart.

The 30-day notice only gates passive charges

Billing must be announced 30 days before it starts. This gate covers the paths the user didn't actively take part in: automatically issued renewal invoices, and trials expiring.

Checkouts the user starts are deliberately exempt from this gate. An active purchase isn't a passive start to billing.

Suspension doesn't touch the user's toggle

Suspension used to simply turn off the user's lending toggle. The problem is that this mixed the user's intent and their billing eligibility into the same flag, and a suspended user could just turn it back on and keep lending.

Now the engine excludes suspended users when selecting configs, and the lending toggle isn't touched at all. Once payment is restored, any pause the user set themselves is still in place.

Before and after flow: before, the user's pause and resume and the suspension all wrote the same lending toggle, so a suspended user could turn it back on and keep lending; now the toggle only holds the user's intent, suspension lives in billing state, the engine skips suspended users when picking configs, and a pause the user set is still in place after payment is restored.

Wrap-up

  • Build plan limits before billing. Don't collect money first and patch in limits afterward.
  • Freeze promotion entitlements when the invoice is issued. Don't let rule changes rewrite historical invoices.
  • A notification gate is for passive charges. Users buying on their own don't need to wait.
  • Store user intent and system billing state separately. A system action like suspension shouldn't change values the user set.
#SaaS#Subscriptions#System Design

Letters

Loading comments…

Next

Engineering

From a FastAPI Script to a Spring Boot SaaS: Rebuilding My Bitfinex Auto-Lending Platform

How an auto-lending side project went from a "good enough to run" single-person script to a multi-module platform with idempotency, reconciliation, circuit breaking, and full monitoring.