​
When to use this

Use CKO-04 when:
  • You are an incumbent or existing ISP bringing your own subscribers to the kurnl network
  • You handle your own billing entirely — no Stripe or kurnl invoices needed
  • You want to provision subscribers programmatically from your own back-office system without a marketplace flow
CKO-04 is the simplest integration path if you already have subscriber relationships and just need kurnl to activate the network port.

​
How it works

One API call does everything:
  1. Creates the subscriber record in kurnl (or reuses an existing account by email)
  2. Creates and activates the subscription
  3. Provisions the switch port via SSH (sets VLAN, bandwidth limits, optional MAC binding)
There is no marketplace redirect, no Stripe checkout, and no webhook required on your side (though you can configure one to receive provisioning status).

​
Making the call

curl -X POST https://api.kurnl.ca/api/v1/partner/provisioning/provider-initiated \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "plan_version_id": "f7e8d9c0-b1a2-3456-cdef-012345678901",
    "location_hash": "ab12cd34ef",
    "email": "carol@example.com",
    "firstname": "Carol",
    "lastname": "White",
    "phonenumber": "+16045559876",
    "street": "Pine Rd",
    "housenumber": "88",
    "postalcode": "C3D 4E5",
    "city": "Kelowna",
    "province": "BC",
    "country": "Canada",
    "mac_address": "BB:CC:DD:EE:FF:00"
  }'
Successful response — 200 OK: 
{
  "job_id": "5a7c9e11-...",
  "subscription_id": "2b4d6f80-...",
  "subscriber_id": "1c3e5a79-...",
  "message": "Provisioning started"
}
The port is provisioned asynchronously. Poll the job or wait for the provisioning.completed webhook.

​
Where does the location hash come from?

Unlike CKO-03, there is no marketplace redirect to supply the location_hash. You get it one of two ways:
  1. From your provisioning records — if you previously mapped your subscriber addresses to kurnl location hashes during onboarding
  2. From the kurnl dashboard — for manual provisioning, look up the port in Dashboard → Network and copy the location hash
If you’re provisioning large numbers of subscribers (e.g. migrating from another platform), use Bulk Provisioning to supply a CSV of addresses and location hashes.

​
No Stripe / no kurnl invoices

CKO-04 does not create any Stripe payment records or Invoice Ninja invoices. Billing is entirely your responsibility. kurnl tracks the subscription for network management purposes (deprovisioning on cancellation, reporting), but does not bill the subscriber on your behalf.
If you want kurnl to handle subscriber billing (invoices, Stripe payment links, self-service portal), use CKO-01 (the kurnl marketplace checkout) or CKO-03 instead.

​
Cancellation

When a subscriber’s service ends, call the subscription cancel endpoint so kurnl can deprovision the port: 
curl -X POST https://api.kurnl.ca/api/v1/subscription/{subscription_id}/cancel \
  -H "X-API-Key: YOUR_API_KEY"
This removes the VLAN assignment, clears bandwidth limits, resets the port to the captive portal VLAN, and marks the subscription as cancelled in kurnl.

​
Field reference

FieldTypeRequiredNotes
plan_version_idUUIDYesThe plan version to activate
location_hashstring (10 hex)YesPort location identifier
emailstringYesSubscriber account email
firstnamestringYes
lastnamestringYes
streetstringYesBilling address
housenumberstringYes
postalcodestringYes
citystringYes
provincestringYes
countrystringNoDefault: "Canada"
phonenumberstringNo
mac_addressstringNoEnables port security
external_subscription_idstringNoYour own reference ID for this subscription