​
Overview

There are two distinct surfaces, and it’s important not to confuse them:
  • Partner API (X-API-Key) — how you create subscribers programmatically, as part of checkout or a migration. This is the server-to-server integration surface.
  • Operator dashboard (JWT-authenticated) — where subscribers and subscriptions are managed after creation (edit details, change plan, cancel). These endpoints live under /api/v1/dashboard/* and are not reachable with a partner API key; they back your dashboard UI.
The partner API does not expose subscriber CRUD or subscription lifecycle (activate / change-plan / cancel) — those require a dashboard session. Earlier versions of this page documented X-API-Key calls to /provider/subscribers and /subscription/{id}/…; those paths do not exist on the partner surface.

​
Creating subscribers (partner API)

Programmatic subscriber creation happens through the checkout/provisioning flows, which create the subscriber, the subscription, and (optionally) provision the port in one call:
  • CKO-03 external checkout — POST /partner/external-checkout/complete (and the anonymous variant) create a subscriber + subscription from your own checkout. Subscriber creation is idempotent by email — the same email + plan returns the existing job rather than duplicating.
  • CKO-04 provider-initiated provisioning — POST /partner/provisioning/provider-initiated (and /bulk) create + activate a subscriber’s port without a marketplace redirect. Use this to migrate an existing subscriber base.

​
Managing subscribers & subscriptions (dashboard)

After creation, management is done in the operator dashboard (dashboard JWT + the subscribers permission), not via the partner API key:
  • Subscribers — create/list/get/update live under /api/v1/dashboard/subscribers (update is PUT). See the operator guide Add a subscriber & subscription.
  • Subscription lifecycle — activate, change-plan, and cancel are /api/v1/subscription/{id}/… and are deliberately dashboard-only (see Subscriptions reference). Changing a plan updates the port’s VLAN + bandwidth; cancelling deprovisions the port and resets it to the captive-portal VLAN.
  • Suspension is automatic — there is no suspend/reactivate API. kurnl suspends for non-payment (with a CRTC grace window) and restores automatically on payment; this is handled by the billing/suspension schedulers.

​
Subscription statuses

​
Migrating an existing subscriber base

  1. For each subscriber, call provider-initiated provisioning (CKO-04) with their plan_version_id and location_hash — this creates + activates them.
  2. Store kurnl’s returned subscriber_id / subscription_id in your own system.
  3. Manage them thereafter from the dashboard (or your own dashboard-authenticated integration).