Managing subscriptions from your platform

Overview#

A platform (hosting, messaging, cinema, support...) keeps its own customers and entitlements and lets CentraPoint run the money: the subscription, its billing periods, invoices, card / debit order / invoice collection, dunning and receipts. Everything below is the public API under /api/v1/customer-subscriptions (see the customer subscriptions API for the object) plus webhooks to keep your side in sync. Amounts are price-list amounts, like plan prices (net for tenants whose prices exclude VAT); previews and invoices show the tax on top.

Create a subscription#

{
  "customer": {
    "externalReference": "nh-cust-1042"
  },
  "planId": "cmg4p1a2b0002pln0001abcd",
  "collectionMethod": "gateway",
  "quantity": 1,
  "items": [
    {
      "code": "website_alias",
      "description": "Website alias",
      "unitAmount": 250,
      "quantity": 3
    }
  ],
  "couponCode": "WELCOME10",
  "billingAnchorDay": 1,
  "externalReference": "nh-sub-1042",
  "metadata": {
    "domain": "example.co.za"
  }
}

Creating twice with the same externalReference returns the existing subscription (200, created: false; new ones are 201 with created: true), so retries are safe, also when two requests arrive at the same time.

Add-ons, metered and one-time items#

Give add-ons a code: you can then address them as /items/website_alias and send the full list in change-plan (matched by code). Invoices show each line with its billing period; credits are taken off the positive lines (invoices have no negative lines).

{
  "quantity": 120,
  "action": "increment"
}

Find subscriptions#

Filters: status (comma list), planId, packageId, customerId, customerExternalReference, externalReference, nextBillingFrom / nextBillingTo (YYYY-MM-DD). Keyset paging with limit (max 100) and startingAfter; the response is { data, hasMore, nextCursor }.

Change plan, quantity or add-ons#

{
  "quantity": 5,
  "items": [
    {
      "code": "website_alias",
      "description": "Website alias",
      "unitAmount": 250,
      "quantity": 3
    }
  ],
  "proration": "now"
}

The response is the subscription plus change (the preview that applied) and charge (the proration invoice or card charge). Card subscriptions billed by the gateway change their amount in place where the gateway allows it (PayFast); otherwise the change is refused and you can replace the card subscription.

Preview a change#

Same body; nothing is changed.

{
  "object": "subscription_change_preview",
  "subscriptionId": "cmg4s9d8e0005csb0001abcd",
  "requestedProration": "now",
  "proration": "now",
  "note": null,
  "effectiveAt": "2026-10-16T08:00:00.000Z",
  "currency": "ZAR",
  "current": {
    "planId": "cmg4p1a2b0002pln0001abcd",
    "planName": "Pro",
    "quantity": 1,
    "frequency": "monthly",
    "amount": 500,
    "subtotal": 500,
    "tax": 75,
    "total": 575
  },
  "next": {
    "planId": "cmg4p1a2b0002pln0001abcd",
    "planName": "Pro",
    "quantity": 1,
    "frequency": "monthly",
    "amount": 1250,
    "items": [
      {
        "code": "website_alias",
        "kind": "addon",
        "description": "Website alias",
        "unitAmount": 250,
        "quantity": 3
      }
    ],
    "subtotal": 1250,
    "tax": 187.5,
    "total": 1437.5
  },
  "prorationInvoice": {
    "lines": [
      {
        "description": "Unused time on Hosting - Pro",
        "amount": -250,
        "periodStart": "2026-10-16T08:00:00.000Z",
        "periodEnd": "2026-10-31T00:00:00.000Z"
      },
      {
        "description": "Remaining time on Hosting - Pro",
        "amount": 625,
        "periodStart": "2026-10-16T08:00:00.000Z",
        "periodEnd": "2026-10-31T00:00:00.000Z"
      }
    ],
    "dueNow": true,
    "creditToNextRenewal": 0,
    "periodStart": "2026-10-01T00:00:00.000Z",
    "periodEnd": "2026-10-31T00:00:00.000Z",
    "resetsPeriod": false,
    "subtotal": 375,
    "tax": 56.25,
    "total": 431.25
  },
  "nextInvoice": {
    "date": "2026-10-31T00:00:00.000Z",
    "periodStart": "2026-10-31T00:00:00.000Z",
    "periodEnd": "2026-11-30T00:00:00.000Z",
    "lines": [
      {
        "description": "Hosting - Pro",
        "amount": 500
      },
      {
        "description": "Website alias x3",
        "amount": 750
      }
    ],
    "subtotal": 1250,
    "tax": 187.5,
    "total": 1437.5
  }
}

Pause, cancel, reactivate, renewal date#

Credits and discounts#

{
  "amount": 150,
  "description": "Downtime credit"
}

{
  "percent": 20,
  "description": "Loyalty"
}

Credit left over after a charge carries forward to the next one.

Invoices and payments#

Invoices have the fields of GET /api/v1/invoices/{id}: the billing period as inclusive YYYY-MM-DD dates (periodStart / periodEnd, the day before the next billing date), lines with details and their own periods, status (with partially_paid), amountDue, plus charge (first, cycle, recovery, setup, proration) and cycle.

Webhooks#

Every lifecycle change sends a subscription.* event: created, activated, renewed, trial_ending, trial_ended, payment_failed, past_due, paused, resumed, plan_changed, updated (items, credits, scheduled changes, scheduled start), cancelled, expired, reactivated. data is the subscription plus billingPeriod, and invoice (the same object as in the invoices list) / payment when the event concerns one. External (mirror) subscriptions send none.

Card subscriptions held at the gateway#

Gateway subscriptions (/api/v1/subscriptions) now report capabilities and support:

Migrating legacy Netcash subscriptions#

{
  "subscriptions": [
    {
      "payerName": "Jane Smith",
      "email": "[email protected]",
      "amount": 115,
      "frequency": "monthly",
      "nextDate": "2026-11-01",
      "legacyReference": "INV-2019-0042"
    }
  ]
}

For card subscriptions set up directly on Netcash Pay Now (not by CentraPoint). CentraPoint creates the customer and a gateway customer subscription and emails the payer a checkout link to confirm their card. When they pay, the subscription runs on CentraPoint and the legacy instruction is cancelled (DeleteSubscription with the legacy reference, using the service key of providerId), or left for you to cancel with cancelLegacy: manual. Track progress with GET /api/v1/subscriptions/migrations (status link_sent - authorised - legacy_cancelled) and act with POST /api/v1/subscriptions/migrations/:id/send-link | cancel-legacy | mark-legacy-cancelled | cancel. Idempotent on legacyReference. The same tool is under Subscriptions > Migrations in the dashboard (with CSV import).

Importing subscriptions (mirror mode)#

When your platform keeps billing its customers itself but every subscription should also be visible in CentraPoint (one customer view, reporting, a later switch to CentraPoint billing), import them with collectionMethod: "external". CentraPoint records the subscription and never charges, invoices, emails, reminds, duns or expires it: your platform stays the billing system and tells CentraPoint about each of its renewals. Available from API version 1.16.0.

Before you import#

• Call GET /api/v1/me and stop unless apiVersion is 1.16.0 or later and capabilities.externalSubscriptions is true. Older versions ignore the fields below and would start a subscription that CentraPoint bills. capabilities.externalSubscriptions is false while CentraPoint is being updated and not every part of it that could bill a subscription (the API with its scheduled jobs, the dashboard and the customer portal) runs a version that leaves imported subscriptions alone. Until then a create with collectionMethod: "external", a dry run included, answers 409 external_imports_unavailable and writes nothing: try again later. Check tenant.status too: a read-only account answers writes with 403 account_restricted.
• The rate limit (120 requests per minute) is per API key and shared with your live traffic. Import one request at a time at no more than 100 per minute, or use a separate API key for the import and deactivate it afterwards.
• Always send sendEmail: false, and keep your import report to ids and counts.
• Before the first import, update everything that reads GET /api/v1/customer-subscriptions to total income or expected renewals: unfiltered lists (for example ?status=active) include the imported records, with your renewal dates in nextBillingAt. Leave out collectedByCentraPoint: false, or filter on collectionMethod, and page through nextCursor.

Customers, package and plans#

1. Customers: POST /api/v1/customers with your own externalReference (it creates or updates the customer with that reference).
2. One package for the import, for example { "name": "Acme Hosting (imported)", "enabled": false }. Keep it disabled: it is then never offered at checkout or in the customer portal. External subscriptions may use disabled plans and packages.
3. One plan per platform plan and billing cycle, each with a code of your own (for example acmehosting:pro:monthly). Look it up first with GET /api/v1/plans?code=acmehosting:pro:monthly and create it with POST /api/v1/packages/{id}/plans only when it is missing; a second plan with the same code gets 409 plan_code_taken. Amounts are price-list amounts in your tax basis, like any plan price.

Create the record#

{
  "customer": {
    "externalReference": "acmehosting:user:1042"
  },
  "plan": "acmehosting:pro:monthly",
  "collectionMethod": "external",
  "status": "active",
  "currentPeriodStart": "2026-09-30",
  "paidThrough": "2026-10-31",
  "items": [
    {
      "code": "website_alias",
      "description": "Website alias",
      "unitAmount": 250,
      "quantity": 2
    }
  ],
  "externalReference": "acmehosting-sub:1042",
  "metadata": {
    "importedFrom": "Acme Hosting",
    "platformSubscriptionId": "1042",
    "mode": "mirror"
  },
  "sendEmail": false
}

providerId, mandateId, coupons, startDate, billingAnchorDay, trial and trialDays are refused with 400: import a discounted price as its own plan. The response is 201 with created: true, or 200 with created: false and the existing subscription when that externalReference was imported before (also for two requests at the same time), so a re-run of your import is safe. When the externalReference belongs to a subscription CentraPoint bills itself, or to another customer's, the create answers 409 external_reference_conflict instead: that row is not mirrored. The same code answers a create with another collectionMethod for a mirrored externalReference. To let CentraPoint bill one of them later, cancel the record (when: now, sendEmail: false) and create the new subscription with its own externalReference and paidThrough set to the end of the period your platform was paid for. payment.due is always false. The subscription has collectionMethod: "external", collectedByCentraPoint: false and billedBy (your metadata.importedFrom). nextBillingAt is your next renewal date, for information only.

Dry run#

With dryRun: true the request is validated exactly like a create and answers 200 without writing anything: no subscription, event, email or webhook, and no stored Idempotency-Key. It works for every collection method. The customer and plan must already exist: a dry run of a row whose customer or plan code you have not created yet answers the create's 400 (Customer not found / Plan not found), so create the customers and plans first (they are safe to repeat) and then dry-run the subscriptions. Other errors are the same 400s and 409s as a create.

{
  "dryRun": true,
  "action": "create",
  "subscription": {
    "id": null,
    "object": "customer_subscription",
    "status": "active",
    "customer": {
      "id": "cmg2c0s7t0003cust0001abcd",
      "externalReference": "acmehosting:user:1042",
      "email": "[email protected]"
    },
    "plan": {
      "id": "cmg4p1a2b0002pln0001abcd",
      "name": "Pro (monthly)",
      "packageId": "cmg4p1a2b0001pkg0001abcd",
      "packageName": "Acme Hosting (imported)"
    },
    "collectionMethod": "external",
    "collectedByCentraPoint": false,
    "billedBy": "Acme Hosting",
    "amount": 1000,
    "currentPeriodStart": "2026-09-30T04:00:00.000Z",
    "currentPeriodEnd": "2026-10-31T04:00:00.000Z",
    "nextBillingAt": "2026-10-31T04:00:00.000Z",
    "externalReference": "acmehosting-sub:1042",
    "createdAt": null
  }
}

action is create (with a preview: no id or timestamps yet) or exists (with the subscription that already has the externalReference).

Keep it in sync#

{
  "currentPeriodStart": "2026-10-31",
  "currentPeriodEnd": "2026-11-30",
  "status": "active"
}

Call it after each renewal or status change on your platform. External subscriptions only (409 not_external for the others). A period that starts where the recorded one ended counts as a renewal (cyclesBilled + 1); sending the recorded period and status again changes nothing. status (default: unchanged) is active (period end in the future), past_due (while you wait for payment; the period may have ended) or trialing (the period end is the trial end). A scheduled cancellation moves to the new period end. A cancelled or expired record returns 409 invalid_state: reactivate it first. A period that starts and ends before the recorded one with the same status returns 409 stale_period and changes nothing (an older update that arrived late, e.g. a retry); to correct the current period, keep its start or send the status with it. Two identical calls at the same time record one renewal; a call that keeps losing to other updates of the subscription at the same time answers 409 concurrent_update and changes nothing (send it again). Nothing is charged, emailed or sent.

What CentraPoint never does for them#

• No charges, invoices, payment links, card or debit order collections, so nothing reaches your accounting integration either.
• No customer emails: no activation, renewal, reminder, dunning, cancellation or invoice email.
• No scheduled changes: no renewals, trial ends, past_due, dunning, expiry or renewal reminders. Only a cancellation you scheduled is carried out, at its end date.
• No subscription.* webhooks. Webhook handlers usually match events to a payment by data.reference; these records have none, and a handler that rejected them would make CentraPoint retry. Read them with GET /api/v1/customer-subscriptions?collectionMethod=external instead.
• Refused with 409 external_subscription: pause, resume, retry payment, credit, discount, one-time and metered items, moving billing dates (PATCH nextBillingAt / billingAnchorDay), a debit order mandate for it (POST /api/v1/mandates with its subscriptionId), changing or removing the externalReference, and changes from the customer portal (which shows them read-only, as billed by your platform).

For income CentraPoint collects, leave these out: collectedByCentraPoint is false, or filter with ?collectionMethod=gateway,debit_order,invoice,manual. When you later let CentraPoint bill, payments carry sandbox (see Transactions): never settle a real invoice with a sandbox payment, and keep each gateway's CentraPoint sandbox setting the same as its own test mode.