Packages, plans & customer subscriptions

Overview#

Customer subscriptions let you sell recurring services from a catalogue. A package is the product you sell (for example "Acme Cloud"); each package has one or more plans, which are its price points (Starter monthly, Pro monthly, Pro annually…). A customer subscription links one of your customers to a plan and CentraPoint takes care of trials, billing periods, renewals, failed payments and cancellations. You manage them in the dashboard under Subscriptions, through the Customer subscriptions API, on hosted checkout pages, and customers can manage their own in the customer portal.

Requirements#

• A plan that includes Recurring billing (Growth and higher by default). The API endpoints also need the REST API; without Recurring billing they return 403 plan_restricted.
• The invoice collection method also needs Invoicing, and debit_order needs Debit orders (Business and higher by default) and a Netcash debit order provider.
• Coupons on subscriptions need Coupons in your plan (see Coupons).

Packages and plans#

Create packages under Subscriptions → Packages or with POST /api/v1/packages. A package has a name, description, sort order, an enabled flag and an optional default gateway used for card subscriptions. Each plan has:

Starting a subscription#

A subscription can be started from four places, recorded as its source:

• dashboard: Subscriptions → New subscription or the customer's page.
• api: POST /api/v1/customer-subscriptions. Send your own externalReference to make the call safe to repeat: the same reference returns the existing subscription.
• checkout: a customer signs up on a hosted checkout page or checkout session.
• portal: a signed-in customer subscribes in the customer portal.

The customer must be active and the plan and its package enabled. With a trial the subscription starts trialing; otherwise it starts incomplete and the first charge (setup fee plus the first period) is issued straight away. The API response's payment object tells you what is due and where the customer pays (payUrl).

Collection methods#

Every subscription has one collection method, chosen when it starts:

Gateway (card)#

collectionMethod: "gateway". The first payment is a CentraPoint payment link (emailed to the customer as a payment request unless sendEmail: false), created as a recurring link so that gateways with their own subscriptions (PayFast, Netcash Pay Now) set up a card subscription at checkout. From then on:

• Gateway-managed billing (PayFast, Netcash Pay Now): the gateway charges the card on its own schedule and CentraPoint tracks each renewal. If no renewal arrives within the gateway grace days after the billing date, the payment counts as failed. The amount and frequency of such a subscription can't be changed; cancel it and start a new one.
• Otherwise (gateways without their own subscriptions): each later period is an invoice with a pay link.

The gateway defaults to the package's default gateway; pass providerId to choose another allowed one.

Debit order#

collectionMethod: "debit_order". A Netcash debit order mandate collects each period on its debit day; ZAR monthly, quarterly, biannual or annual plans only. Pass an existing mandate of the customer with the same frequency as mandateId, or link one later from the subscription page (you can also create a mandate with subscriptionId through the Mandates API). The mandate amount follows the subscription amount; a setup fee is invoiced separately, because a mandate collects a fixed amount. With First invoice is pro forma on, the subscription's first invoice (normally that setup fee invoice) is issued as a pro forma (PRO FORMA INVOICE). During a trial the mandate's first debit moves to after the trial. Unpaid debits count as failed payments and can be re-presented by the debit order run.

Invoice#

collectionMethod: "invoice". CentraPoint creates and emails an invoice with a pay link for every period. An invoice unpaid after its due date (the invoice due days setting) counts as a failed payment. Invoices paid offline (recorded EFT or cash) still activate or renew the subscription.

Statuses and lifecycle#

Every change is recorded on the subscription's timeline (GET /api/v1/customer-subscriptions/{id}?include=events), for example created, trial_started, activated, charge_issued, renewed, payment_failed, dunning, plan_changed and cancelled.

Trials#

• The plan's trial days apply by default. The API can skip the trial (trial: false) or set its length (trialDays).
• On checkout pages and in the customer portal a customer gets a trial only once per package: a customer who has had a trial on any plan of the package subscribes without one.
• When the trial ends, the subscription becomes active, the first period starts and the first charge is issued (a debit order subscription simply waits for the mandate's next debit). A subscription.trial_ended webhook is sent.
• You can move the trial end with PATCH nextBillingAt (not for debit order or gateway-billed subscriptions).

Renewals and billing periods#

The subscription billing job runs every hour at a quarter past the hour (cron 15 * * * *, South African time). For each subscription whose nextBillingAt has passed it starts the next period and issues the charge by the collection method. Month-based periods keep the day of the month, clamped to the end of shorter months (31 Jan → 28 Feb → 31 Mar). When the plan has a fixed number of billing cycles, the last paid cycle sets endsAt, stops the gateway or debit order from collecting again and the subscription expires at the end of that period. Successful renewals send subscription.renewed.

Quantity, setup fees and coupons#

• amount on the subscription is the plan price × quantity (1–10 000).
• The setup fee is added to the first charge only (for debit orders it is a separate invoice).
• A coupon (by code) is validated for the plan and customer when the subscription starts. A forever coupon reduces the subscription amount itself; once and repeating coupons discount the first charge or the first N charges. See Coupons.

Failed payments and dunning#

A payment fails when a card charge is declined, a debit order is returned unpaid, a subscription invoice or payment request is still unpaid after its due date, or a gateway renewal doesn't arrive in time. An active or trialing subscription then becomes past_due and dunning starts:

1. The customer is emailed (subscription_past_due) with a link to pay the overdue amount, using the open invoice or a recovery invoice CentraPoint creates. No recovery invoice is created while an unpaid debit order will still be re-presented, or for gateway-billed subscriptions.
2. Every dunning interval days another attempt is made and another notice sent, up to dunning max attempts.
3. When the overdue amount is paid, the subscription is active again (subscription.renewed with recovered: true).
4. When the attempts are used up, the final action cancels or expires the subscription and your team is notified.

A failed first payment of an incomplete subscription doesn't start dunning: the customer can simply pay again. Staff can also Retry payment from the subscription page, which re-sends the open invoice or payment request.

Pausing, cancelling and changing plan#

Subscription settings#

Under Subscriptions → Settings:

Renewal, trial, expiry and unpaid invoice reminders are sent by a daily job at 08:00 South African time (cron 0 8 * * *).

Emails, webhooks and notifications#

• Customer emails use the subscription_* templates (activated, trial ending, renewing soon, renewed, payment request, past due, paused, resumed, upgraded, downgraded, expiring, cancelled, expired). Edit them under Email & templates. They go to the customer's billing email when one is set.
• Webhooks: subscription.created, .activated, .renewed, .trial_ended, .payment_failed, .past_due, .paused, .resumed, .plan_changed, .updated, .cancelled and .expired, with the customer subscription as data (object: "customer_subscription"). See Webhooks.
• Your team gets in-app notifications for new subscriptions, failed and recovered payments, changes made by customers or the API, and anything that needs manual action (for example a gateway that couldn't be told to stop billing).

How this relates to gateway subscriptions#

The older Subscriptions API (/api/v1/subscriptions) lists the card subscriptions a gateway created when a payer completed a recurring payment link. Those remain available and unchanged (dashboard: Subscriptions → Gateway). A customer subscription with the gateway collection method usually has one of these underneath: its paymentTokenId is the ID of the gateway subscription, and cancelling or pausing the customer subscription does the same at the gateway.