POST /external-checkout/anonymous-complete

See CKO-03 Anonymous for the full guide.

Endpoint

POST /partner/external-checkout/anonymous-complete

Authentication

X-Webhook-Secret header.

Request body — session-based (recommended)

This is the flow the kurnl Marketplace uses. With session_id set, the session supplies the plan, building, location/unit and MAC address — only external_subscription_id is additionally required (and contact_email when the order needs a visit, see below). Any of the explicit fields below included alongside a session_id are ignored in favor of the session.

{
  "session_id": "uuid",
  "external_subscription_id": "your-own-id",
  "contact_email": "e-mail (required when the order needs a visit)"
}

A discount code the session itself carries applies here too, on the same terms as /external-checkout/complete: resolved as of the session’s creation day, and if it was archived meanwhile it lapses without failing the order. That silent lapse covers only the session’s own code. A discount_code you send in the body is checked as of the hand-over against the session’s building: a kurnl operator code from the session’s operator_offers or one of your own discount codes is honoured; anything else is a 400 (Invalid or expired discount code) and nothing is created. The session’s own code sent back counts as no code. Check it before you charge, and on a 400 retry without the code (the plan’s campaign price if a campaign is live, otherwise the list price). A bulk plan takes no code (422 bulk_discount). If the code cannot be checked right now, the call answers 503 (Could not check the discount code; try again.): retry.

The building decides the path, as on /external-checkout/complete, not the delivery_mode of the session or of your payload:

a first-line building is provisioned at once (ACTIVE) — a shared first-line suite is held as an install job until the operator confirms the connection;
a second- or third-line suite whose router is already online (a suite of one) is provisioned at once too;
every other suite — router not online, a shared suite, or any suite in an unclassified building — gets PENDING_INSTALL and an operator install job.

delivery_mode in the response reports the path taken: direct = provisioned, home_drop = install job. A direct order (a port, no suite) on a building that is not first line is refused with 422: outside first line kurnl needs the suite.

Request body — explicit fields (no session)

{
  "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')",
  "external_subscription_id": "your-own-id",
  "mac_address": "string (optional)",
  "contact_email": "e-mail (required when the order needs a visit)"
}

external_subscription_id is your own per-subscription identifier and acts as the idempotency key. contact_email (either path) is an e-mail for the household behind the line. It is stored on the subscription only — no customer record is created. It is required when the order needs a technician visit or a shipped router: a second- or third-line building, unless the suite’s router is already online, and an unclassified building, even when the suite’s router is online. Without it such an order is refused with 422 contact_email_required and nothing is created. On a first-line building, and for a second- or third-line suite whose router is already online, it is optional. On a third-line building it is the address the technician booking link is e-mailed to; the customer picks and manages the visit window from that link. Later it also serves the provider’s own outage notices. The provider can add or change it in the portal.

Response — 200 OK

{
  "subscription_id": "uuid",
  "external_subscription_id": "your-own-id",
  "delivery_mode": "direct",
  "subscription_status": "ACTIVE",
  "job_id": "uuid",
  "message": "Provisioning started",
  "idempotent_replay": false,
  "unit_confirmation_pending": false
}

Field	Type	Notes
`subscription_id`	UUID	The kurnl subscription
`external_subscription_id`	string	Echo of your identifier
`delivery_mode`	`"direct"` \| `"home_drop"`	The path taken: `direct` = provisioned, `home_drop` = install job. It can differ from the `delivery_mode` you sent. On an idempotent replay it echoes the mode of the session or of your payload instead.
`subscription_status`	string	`ACTIVE` (provisioned) or `PENDING_INSTALL` (install job)
`job_id`	UUID \| null	Provisioning job — `null` on the home-drop path and on replays
`message`	string	Human-readable outcome
`idempotent_replay`	boolean	`true` when an existing subscription was returned instead of creating one
`unit_confirmation_pending`	boolean	`true` on an install-job order for a shared suite (several connections) whose connection the kurnl operator has not confirmed yet; replays report the current value. `false` otherwise.

No subscriber_id is returned — no subscriber record is created. An order for a shared suite takes the install path. It is re-anchored to the suite’s first free connection and stays PENDING_INSTALL as usual; unit_confirmation_pending: true says the operator still has to confirm which connection is the customer’s. If every connection of the suite is taken the call is refused with 409 no_free_connection. Replays (same external_subscription_id or already-completed session_id) report the subscription’s real current status — e.g. PENDING_INSTALL for a home-drop order still awaiting install.

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 or unit not found
409	`{"code": "no_free_connection", "message": "Every connection of this suite is taken."}` — an order onto a shared suite with no free connection
409	`{"code": "suite_not_wired", …}` — the suite is provisioned but no switch port serves it
410	Session expired or cancelled — nested body: `{"detail": {"detail": "Session expired", "expired_at": "…"}}`; the cancelled variant has no `expired_at`
422	`{"detail": {"code": "bulk_plan", "message": "…", "building_bulk": true, "plan_bulk": false}}` — the plan and the building do not match. A paid plan ordered in a bulk building answers `"This building includes internet in the rent — choose one of its included plans."`; a bulk plan ordered elsewhere answers `"<Plan name> is only available in buildings that include internet in the rent."`. `building_bulk` and `plan_bulk` say which side each is. Nothing was created; offer a plan from the building’s `plans` in serviceability
503	`Could not verify the building's bulk offer; try again.` — retryable; nothing was created
422	`{"detail": {"code": "not_covered", "message": "This building is not covered by <provider>. …", "building_id": "…"}}` — your provider does not cover the building (no ticked division, picked building or contract). Nothing was created
503	`Could not verify the building's coverage; try again.` · `Could not read the line's building; try again.` — retryable; nothing was created
422	`{"detail": {"code": "plan_not_offered", "message": "<Plan> is not offered in this building.", "building_id": "…"}}` — your provider does not offer this plan in the building. Nothing was created
503	`Could not verify the building's plan offer; try again.` — retryable; nothing was created
422	`{"detail": {"code": "contact_email_required", "message": "This order needs a technician visit or a shipped router. Send contact_email so the household gets the booking link."}}` — the order takes the install path and carries no `contact_email`; nothing was created. Ask the household for an e-mail and send the order again
422	The request does not fit the building’s line type — e.g. a `direct` order (a port, no suite) on a building that is not first line: `Building line type '…' requires an operator install job, but the session has no unit_id — refusing to provision.` A port whose switch belongs to no building counts as unclassified.
422	`{"detail": {"code": "plan_audience", "message": "…", "target_audience": "EXISTING_SUBSCRIBERS"}}` — the plan is for existing customers only
422	`Invalid location_hash format`; missing required fields in the no-session payload
400	Plan version not active; location has no switch; provider has no VLAN
400	`Invalid or expired discount code` — session form: the `discount_code` is neither a kurnl operator code from the session’s `operator_offers` nor one of your own discount codes, or it no longer resolves; no-session form: it does not resolve. Nothing was created
422	`{"detail": {"code": "bulk_discount", "message": "This plan is included in the rent — discount codes do not apply."}}` — the plan version is a bulk plan; it takes no discount code. Nothing was created
503	`Could not check the discount code; try again.` — retryable; nothing was created
429	Rate limit exceeded (120 req/min)

Overview

Plan Discovery

Provisioning

Reports

Checkout Utilities

Subscribers & Subscriptions

AI Support Agent

Provider Operations (Internal API)

POST /external-checkout/anonymous-complete

Endpoint

Authentication

Request body — session-based (recommended)

Request body — explicit fields (no session)

Response — 200 OK

Error codes

​Endpoint

​Authentication

​Request body — session-based (recommended)

​Request body — explicit fields (no session)

​Response — 200 OK

​Error codes

Endpoint

Authentication

Request body — session-based (recommended)

Request body — explicit fields (no session)

Response — 200 OK

Error codes