POST /external-checkout/complete

See the full guides: CKO-03 Direct Delivery and CKO-03 Home-Drop Delivery.

Endpoint

POST /partner/external-checkout/complete

Authentication

X-Webhook-Secret header — your pre-shared webhook secret.

Routing — session path (`session_id` present)

With a session_id, delivery_mode is ignored. kurnl resolves the session’s building_id to the building’s line type (operator-side configuration) and routes:

Building line type	Session carries	Path	Response
`first`	a resolvable `location_hash`	Provision the port directly (ACTIVE)	200 with `job_id`
`first`	a `unit_id` and no port	Operator install job (`PENDING_INSTALL`)	200 without `job_id`
`second` / `third` / unclassified (NULL)	a `unit_id`	Operator install job (`PENDING_INSTALL`)	200 without `job_id`

A first-line building is reached two ways. From the captive portal the port is known (location_hash) and kurnl provisions it immediately. From address search or a QR landing there is no port — only a building and a suite — so the order takes the install path, exactly as a second- or third-line building does. kurnl fails closed — a payload carrying neither a port nor a unit_id is rejected with 422 (see error codes), and only an explicit first-line building with a resolvable port ever provisions a switch unattended. The same rule now applies to the no-session payload: delivery_mode says what you have, the building’s line type decides the outcome.

Request body — session-based (recommended)

When the subscriber arrived via a kurnl Marketplace redirect, you have a session_id (from the ?session_id= query parameter). The session is the source of truth for the provider, plan, location/unit, building, and MAC address — you only supply the subscriber PII:

{
  "session_id": "uuid",
  "partner_reference": "string (optional — stored on the session)",
  "subscriber": {
    "email": "string",
    "username": "string",
    "password": "string (optional)",
    "customer_type": "RESIDENTIAL | BUSINESS",
    "invoice_contact_detail": { "firstname": "", "lastname": "", "email": "" },
    "contract_contact_detail": { "firstname": "", "lastname": "", "email": "" },
    "invoice_address": {
      "street": "", "housenumber": "", "postalcode": "",
      "city": "", "province": "", "country": "Canada"
    }
  }
}

If both the session and your payload carry a location_hash or mac_address and they disagree, the session value wins (the conflict is logged). Idempotent: a second call with the same session_id returns the existing subscription without re-provisioning — response shape {subscription_id, subscriber_id, message} (no job_id), where subscriber_id is the real kurnl subscriber UUID.

Request body — explicit fields (legacy, no session)

For flows that do not go through a Marketplace session, pass the provisioning fields yourself. delivery_mode states which fields you are sending; the building’s line type still decides whether the order provisions a port or raises an install job, so a mismatch is refused with 422:

Building a storefront that owns its funnel? Prefer POST /provisioning/provider-initiated with your X-API-Key — it is the documented CKO-04 path, takes the same delivery_mode / unit_id pair, and tells you which route was taken.

{
  "service_provider_document_id": "uuid",
  "plan_version_id": "uuid",
  "delivery_mode": "direct | home_drop",
  "location_hash": "10-char hex (required when delivery_mode is 'direct')",
  "unit_id": "uuid (required when delivery_mode is 'home_drop')",
  "subscriber": { "...": "same subscriber object as above" }
}

This flow is idempotent per (subscriber email, plan version, location): a retry returns the existing subscription with "Subscription already exists (idempotent replay)" or "Provisioning already in progress" — job_id may be empty on replay.

Response — 200 OK (provisioned — first-line building, or legacy `direct`)

{
  "job_id": "uuid",
  "subscription_id": "uuid",
  "subscriber_id": "uuid",
  "message": "Provisioning started"
}

Webhook: subscription.activated, then provisioning.completed / provisioning.failed.

Response — 200 OK (install job — non-first-line building, or legacy `home_drop`)

{
  "subscription_id": "uuid",
  "subscriber_id": "uuid",
  "message": "Subscription pending installation. Call /provisioning/confirm-install when the port is ready."
}

No job_id; subscription status is PENDING_INSTALL. Webhook: subscription.pending_install (not subscription.activated).

The response shape varies with the routing (there is no fixed response model) — always parse job_id as optional and branch on its presence.

Error codes

Status	Error
401	Missing or invalid `X-Webhook-Secret`
403	`Plan version does not belong to your service provider`
404	`Session not found`; `Location not found for location_hash`; `Plan version … not found`; `Unit … not found`
409	`Unit already has a pending or active subscription` (install-job path)
410	Session expired or cancelled — nested body: `{"detail": {"detail": "Session expired", "expired_at": "…"}}`; the cancelled variant has no `expired_at`
422	`First-line building requires a resolvable port (location_hash) or a unit; the session carries neither.`
422	`Building line type '…' requires an operator install job, but the session has no unit_id — refusing to provision.`
422	`Invalid location_hash format`; missing required fields in the no-session payload
400	`Plan version not active` / `Plan version not yet active`; location has no switch; provider has no VLAN; unparseable port
429	Rate limit exceeded (120 req/min)

Overview

Plan Discovery

Provisioning

Reports

Checkout Utilities

Subscribers & Subscriptions

AI Support Agent

Provider Operations (Internal API)

Endpoint

Authentication

Routing — session path (`session_id` present)

Request body — session-based (recommended)

Request body — explicit fields (legacy, no session)

Response — 200 OK (provisioned — first-line building, or legacy `direct`)

Response — 200 OK (install job — non-first-line building, or legacy `home_drop`)

Error codes

​Endpoint

​Authentication

​Routing — session path (session_id present)

​Request body — session-based (recommended)

​Request body — explicit fields (legacy, no session)

​Response — 200 OK (provisioned — first-line building, or legacy direct)

​Response — 200 OK (install job — non-first-line building, or legacy home_drop)

​Error codes

Endpoint

Authentication

Routing — session path (`session_id` present)

Request body — session-based (recommended)

Request body — explicit fields (legacy, no session)

Response — 200 OK (provisioned — first-line building, or legacy `direct`)

Response — 200 OK (install job — non-first-line building, or legacy `home_drop`)

Error codes