Skip to main content
Start here if you’re not sure which preset to use. It covers the standard SaaS billing behaviour: charge immediately for upgrades, wait until renewal for downgrades, give customers a week to sort a failed card.

​
Who should use this

  • Monthly or annual subscription SaaS
  • Nigerian B2B or B2C apps with card-paying customers
  • Any product where you want sane defaults without thinking too hard about policy

​
Settings

Policy knobValueWhy
Upgrade strategyImmediate, proratedCustomer gets the upgrade now, pays the difference now
Downgrade strategyAt period endCustomer keeps current plan until renewal — no partial credits to manage mid-cycle
Grace period7 daysEnough time to fix a card issue without losing the customer
Dunning retries4 (days +1, +3, +7, +14)Payday-aware schedule
Plan changes while past_dueBlock upgrades, allow downgradesDon’t let past-due customers upgrade without paying first
Billing modeAdvanceInvoice at start of period (standard SaaS)
ArrearsNo—
Max debtNoneNo cap on outstanding balance

​
Apply

curl -X POST https://api.useplinth.com/v1/tenant/apply-preset \
  -H "Authorization: Bearer sk_test_DOCS_SHARED_KEY" \
  -H "Content-Type: application/json" \
  -d '{"preset": "saas_standard"}'

​
Knob details

When a customer upgrades mid-cycle, we calculate the unused value of their current plan and the prorated cost of the new plan. They pay the difference immediately. The upgrade takes effect that moment — no waiting for renewal. This is what customers expect: pay more, get more right now.
When a customer downgrades, we schedule the change for the next renewal date. They stay on their current plan until then. This is simpler for you (no proration credit to issue) and better for the customer (they keep their access). The subscription.plan_change_scheduled event fires immediately; the actual change fires at period end.
After all dunning retries are exhausted, the customer has 7 days before access is cut. Most payment issues — expired cards, daily limits — resolve within a week. 7 days keeps voluntary churn low without leaving you waiting indefinitely.
The retry on day +7 shifts to the 25th of the month if it would otherwise fall after the 25th. Salary and payroll dates in Nigeria cluster around the 25th, so the probability of a successful charge is higher then.