Customers, plans, subscriptions

A subscription links a customer to a plan. This guide covers the three objects, then the life of a subscription. Examples use a qb_test_sk_… key.

Customers

curl -X POST https://api.qbill.dev/v1/customers \
  -H "x-api-key: qb_test_sk_…" \
  -H "content-type: application/json" \
  -d '{"name":"Boutique Awa","email":"awa@example.com","country":"CI"}'

Fields: name, email, and optionally phone, locale, tax_exempt, country. The country (a two-letter country code) picks that country’s VAT rate; tax_exempt: true exempts the customer from VAT.

Plans

curl -X POST https://api.qbill.dev/v1/plans \
  -H "x-api-key: qb_test_sk_…" \
  -H "content-type: application/json" \
  -d '{"name":"Pro","pricing_model":"flat_rate","amount_monthly":6000,"trial_days":7}'

Fields: name, pricing_model, and optionally description, amount_monthly, amount_annual, trial_days, installment_count, features, limits. Amounts are in XOF; there is no currency field.

`pricing_model`	In one line
`flat_rate`	A fixed amount per period.
`per_seat`	An amount per seat; the seat count is the `quantity` declared on the subscription.
`hybrid`	A base amount plus a variable part.
`metered`	Billed on the usage you report.
`tiered`	Per usage metric: each tier of usage is priced at its own unit price, through the plan’s tiers.
`volume`	Per usage metric: the price of the tier the total reaches applies to every unit.
`stairstep`	Per usage metric: a flat price per consumption band.
`credit`	A prepaid wallet: the customer tops it up (through an invoice paid with Wave) and each usage you report draws it down. Nothing is invoiced per period; the customer portal shows balance and history.
`one_time`	A single payment.
`installment`	Payment in several parts: one instalment per period, `installment_count` instalments.

trial_days sets the trial length of subscriptions to the plan. Add-ons. These are optional paid modules from the app’s catalogue (/v1/addons), added to a subscription with a quantity (/v1/subscriptions/:id/addons). Adding, changing the quantity and removing are prorated like a plan change, and add-ons count in MRR. They are refused on prepaid, one-time and instalment plans.

Overage. A price component can include a number of free units (free_units): usage beyond them is billed at the component’s per-unit rate. This applies to flat_rate, per_seat, hybrid and metered plans. Usage is reported as described in Usage.

Subscriptions

curl -X POST https://api.qbill.dev/v1/subscriptions \
  -H "x-api-key: qb_test_sk_…" \
  -H "content-type: application/json" \
  -d '{"customer":"<customer id>","plan":"<plan id>","billing_interval":"monthly","quantity":1}'

Body: customer, plan, and optionally payment_method, billing_interval (monthly or annual), quantity. If the plan has trial_days, the subscription starts in the trialing status.

Statuses: trialing, active, past_due, paused, cancelled.

Changing plan

curl -X POST https://api.qbill.dev/v1/subscriptions/<id>/change-plan \
  -H "x-api-key: qb_test_sk_…" \
  -H "content-type: application/json" \
  -d '{"plan":"<new plan id>","effective":"period_end"}'

Body: plan and/or quantity, and effective (immediately or period_end). period_end only defers downgrades. A mid-period change is settled by a proration adjustment, except for installment, one_time and credit plans, which are not prorated. To drop a scheduled change: DELETE /v1/subscriptions/<id>/pending-change.

Pause, resume, cancel

POST …/pause with { "resume_at": "…" } (optional) stops billing without ending the subscription.
POST …/resume picks it back up.
POST …/cancel with { "reason": "…" } (optional) cancels, immediately.

With the SDK

The @qbill/node package arrives on npm soon; the calls above read like this there:

const sub = await qbill.subscriptions.create({ customer, plan, billing_interval: 'monthly' });
await qbill.subscriptions.changePlan(sub.id, { plan: otherPlan, effective: 'period_end' });
await qbill.subscriptions.pause(sub.id);
await qbill.subscriptions.resume(sub.id);
await qbill.subscriptions.cancel(sub.id, { reason: 'customer_request' });

To bill next, see Invoices & payments.