Provider-Initiated Provisioning (PAY-03)

See Subscriber Management for the full guide.

Endpoint

POST /partner/provisioning/provider-initiated

Auth: X-API-Key
Rate limit: 120 requests / minute

When to use

PAY-03 is for ISP-initiated provisioning — you have the subscriber’s details (from your own storefront, a sales CRM, a signed contract, or a migration from another system) and want to create their account without redirecting them through a kurnl checkout flow. You can name the premise two ways:

`delivery_mode`	You send	Use when
`direct` (default)	`location_hash` or `location_identifier`	You know the physical port — a migration with mapped records, or a subscriber already detected on the network.
`home_drop`	`unit_id`	Your storefront asked the customer for their address and suite. Get the `unit_id` from `GET /serviceability/units`.

delivery_mode states what you have; it does not choose the outcome. The building’s line type decides whether kurnl provisions a port immediately or raises an install job for a technician. Outside first line, a suite whose router is already online (a suite of one, router heard from within the last 15 minutes) is provisioned too; every other suite takes the install path. A request that does not fit the building is refused with 422 rather than half-completed. Read route in the response to find out which happened.

Request body

{
  "plan_version_id": "uuid",
  "delivery_mode": "direct | home_drop (optional, default \"direct\")",
  "location_hash": "10-char hex (direct; preferred)",
  "location_identifier": "string (direct; legacy alternative)",
  "unit_id": "uuid (home_drop)",
  "discount_code": "string (optional)",
  "billing": {
    "owner": "partner | kurnl (optional, default \"partner\")",
    "stripe_customer_id": "string (required when owner is kurnl)",
    "billing_day": "integer 1–31 (optional, default 1; with owner kurnl, at most the provider's Latest billing day, default 10)"
  },
  "subscriber": {
    "email": "string",
    "username": "string (min 3 chars)",
    "password": "string (optional, min 8 chars)",
    "customer_type": "RESIDENTIAL | BUSINESS",
    "mac_address": "string (optional)",
    "invoice_contact_detail": {
      "firstname": "string",
      "lastname": "string",
      "email": "string",
      "phonenumber": "string (optional)",
      "company": "string (optional)"
    },
    "contract_contact_detail": {
      "firstname": "string",
      "lastname": "string",
      "email": "string",
      "phonenumber": "string (optional)",
      "company": "string (optional)"
    },
    "invoice_address": {
      "street": "string",
      "housenumber": "string",
      "postalcode": "string",
      "city": "string",
      "province": "string",
      "country": "Canada",
      "unitnumber": "string (optional)",
      "floor": "string (optional)"
    }
  }
}

With delivery_mode: "direct" (the default) provide at least one of location_hash or location_identifier (both is legal; location_hash wins). With delivery_mode: "home_drop" provide unit_id instead; location fields are ignored. There are no top-level subscriber.firstname / lastname / phonenumber fields — names and phone numbers live in invoice_contact_detail / contract_contact_detail. subscriber.password is optional; when set it controls the subscriber’s self-service login. discount_code is optional: a provider code of yours or a kurnl operator discount code (see Operator discounts). A code that does not resolve is a 400 (Invalid or expired discount code) and nothing is created. A provider code of yours changes nothing kurnl bills on a partner-billed line; a kurnl operator discount lowers the wholesale price kurnl invoices you. billing is optional. Without it, or with owner: "partner", kurnl provisions and you bill — no Stripe records, no invoices. With owner: "kurnl" you name the customer in your Stripe account whose card your storefront saved; kurnl verifies it can bill (see the 409/422 rows below), adopts the customer and its default payment method, and bills the subscription like a marketplace order — a prorated first invoice charged at activation, then monthly on billing_day. owner: "kurnl" without stripe_customer_id is a 422 model error. Full contract: Who bills.

Response — 200 OK

{
  "job_id": "uuid or null",
  "subscription_id": "uuid",
  "subscriber_id": "uuid",
  "message": "Provisioning started",
  "route": "provision | install",
  "billing_owner": "kurnl | partner",
  "unit_confirmation_pending": false
}

Field	Meaning
`route`	`provision` — the port is being configured now: a first-line building, or a second- or third-line suite whose router is already online. `install` — the subscription is `PENDING_INSTALL` and an operator install job was raised; a technician completes it with `POST /provisioning/confirm-install`.
`job_id`	The background switch job. `null` on the `install` route (there is no job yet), and an empty string on an idempotent replay — so branch on `route`, never on `job_id`.
`billing_owner`	`kurnl` — kurnl adopted the named Stripe customer and bills the subscription. `partner` — you bill it (the default).
`unit_confirmation_pending`	`true` when the order is on a suite with several connections and waits for the operator to confirm which one is the customer’s — see Shared suites. Otherwise `false`.

Your confirmation screen should differ between the two: provision means the customer is coming online now, install means someone will contact them to book a visit. Webhooks: subscription.activated fires immediately at subscription creation — before the port is live. provisioning.completed (or provisioning.failed) fires after the background job finishes. (A shared-suite order is the exception — see below.)

Shared suites

A suite can have several connections (GET /serviceability/units returns it as one entry with a postal_unit). An order on such a suite (delivery_mode: "home_drop" with its unit_id) is re-anchored to the suite’s first free connection and held until the kurnl operator confirms which connection really serves the customer. The response depends on the route the building takes. On a first-line building, where the order would otherwise be provisioned at once (route: "provision"), the held response is:

{
  "job_id": null,
  "subscription_id": "uuid",
  "subscriber_id": "uuid",
  "message": "Order accepted. The connection in the shared suite is being confirmed; provisioning starts once it is.",
  "route": "provision",
  "billing_owner": "kurnl | partner",
  "unit_confirmation_pending": true
}

route stays provision, but job_id is null and the subscription is PENDING: nothing is provisioned and no subscription.activated webhook fires yet.
When the operator confirms the connection, kurnl activates the subscription and provisions the port; then subscription.activated, followed by provisioning.completed / provisioning.failed, fire as for any other order.
On the install route the response is the usual install response (route: "install", job_id: null, PENDING_INSTALL) with unit_confirmation_pending: true; the operator’s confirmation picks the connection the technician installs on.
A retry never takes another connection. The check is per (subscriber, plan version, suite): on the provision route a retry returns the existing order (see Idempotency); on the install route it is refused with 409 Unit already has a pending or active subscription.
A suite with a single connection is unaffected and answers unit_confirmation_pending: false.

Idempotency

Idempotency is scoped to the exact (subscriber, plan version, location) triple — the same email + plan at a different location provisions normally (a genuine second line), also when the customer already has a line with you or with another provider. SUSPENDED subscriptions count as live for this check. Any other live order on the same port is refused with 409 port_in_use: another subscriber’s, or another plan version of the same subscriber. A line in PENDING, PENDING_INSTALL, ACTIVE, SUSPENDED or PAYMENT_FAILED holds its port. A line in PAYMENT_FAILED does not count for the replay, so a retry of its order answers port_in_use too. For a shared suite the key is the suite, not the connection: the same subscriber + plan on any connection of the suite is a replay. A replay of a held order answers "Subscription already exists (idempotent replay)" with unit_confirmation_pending: true while the operator has not confirmed, and job_id null (or the latest job id once provisioning ran). A replayed request returns 200 with the existing subscription, but only while its discount_code still resolves: the code is resolved before the idempotency check.

{
  "job_id": "uuid or \"\"",
  "subscription_id": "uuid",
  "subscriber_id": "uuid",
  "billing_owner": "kurnl | partner",
  "message": "Provisioning already in progress"
}

message is "Provisioning already in progress" when a provisioning job is still pending/running, or "Subscription already exists (idempotent replay)" otherwise. job_id may be the empty string when no job record exists. Safe to retry on network errors. A replay that names a different billing.stripe_customer_id for the same subscriber is refused with 409 stripe_customer_in_use rather than rebinding the subscriber.

Error codes

Status	Detail
`400`	`"Plan version not active"` / `"Plan version not yet active"`
`400`	`"Invalid or expired discount code"` — nothing was created
`400`	`"Location '…' has no switch"`
`400`	`"Cannot parse port from interface '…'"`
`400`	`"Service provider has no VLAN configured"`
`400`	`"VLAN '…' is not a valid integer"`
`400`	`"Plan version missing download_speed_mbps"`
`401`	Missing or invalid `X-API-Key`
`403`	`"Plan version does not belong to your service provider"`
`403`	`"API access is not enabled for this account"`
`404`	`"Plan version {id} not found"` / `"Location not found for location_hash"` / `"Location '…' not found"`
`404`	`"Unit '…' not found"`
`409`	`{"code": "port_in_use", "message": "This port already has a live subscription."}` — another live order is on the port: another subscriber’s, or another plan version of this subscriber. A retry of the same order gets its replay instead (unless its line is in `PAYMENT_FAILED`). Nothing was created
`503`	`Could not check whether the port is free; try again.` — retryable; nothing was created
`409`	`{"code": "no_free_connection", "message": "Every connection of this suite is taken."}` — every connection of the suite already has an order and none is yours to replay
`422`	`"Invalid location_hash format"`
`422`	`{"detail": {"code": "plan_audience", "message": "…", "target_audience": "EXISTING_SUBSCRIBERS"}}` — the plan is for existing customers only; nothing was created
`422`	The request does not fit the building’s line type — e.g. a `direct` order on a building that requires a technician visit. The message names what is missing.
`422`	`"unit_id is required when delivery_mode is 'home_drop'"`
`422`	`billing.owner` is `"kurnl"` and `billing.billing_day` is above the provider’s Latest billing day (partner-billed orders are not checked; the day is stored as sent): `"Choose a billing day from 1 to N."` (N defaults to 10)
`422`	`"billing.stripe_customer_id is required when billing.owner is 'kurnl'"`
`409`	`"Unit already has a pending or active subscription"` — a `home_drop` unit (or suite) that already has an order for this subscriber and plan on the install route
`409`	`"billing_not_available: …"` — kurnl billing requested, but your provider has no Stripe connection or no invoicing configured in kurnl
`422`	`"stripe_customer_not_found: …"` — no such customer in your Stripe account (or deleted, another account, test vs live)
`422`	`"stripe_customer_has_no_payment_method: …"` — no default method and no card, a method attached to another customer, or an expired card
`409`	`"stripe_customer_in_use: …"` — another subscriber carries this customer, or this subscriber is bound to a different one
`502`	`"stripe_unavailable: …"` — Stripe could not be reached during the billing pre-flight; retry
`400`	The sign-in service refused `subscriber.password`; the message gives its reason (e.g. `"Password should be at least 6 characters."`). Only for a new account; nothing was created. Send again with another password
`422`	Model validation (missing fields, bad email format, neither location field)
`429`	Rate limit exceeded (120/min)
`500`	`"Provisioning failed"` (unexpected error; partial creates are rolled back)
`502`	Inconsistent upstream data (e.g. plan version missing its service provider)

Overview

Plan Discovery

Provisioning

Reports

Checkout Utilities

Subscribers & Subscriptions

AI Support Agent

Provider Operations (Internal API)

Provider-Initiated Provisioning (PAY-03)

Endpoint

When to use

Request body

Response — 200 OK

Shared suites

Idempotency

Error codes

​Endpoint

​When to use

​Request body

​Response — 200 OK

​Shared suites

​Idempotency

​Error codes

Endpoint

When to use

Request body

Response — 200 OK

Shared suites

Idempotency

Error codes