CKO-03: External Checkout — Home-Drop Delivery

When to use this

You land on the home-drop path whenever the session has no directly provisionable port. That covers two cases: the building is not classified as first-line in kurnl (line type second, third, or unclassified/NULL), or it is first-line but the subscriber reached it through address search or a QR landing, so the session carries a suite instead of a location_hash. Either way kurnl creates the subscription in PENDING_INSTALL with an operator install job instead of provisioning a switch.

For session-based callbacks (session_id present), this routing is decided by the building’s line type — operator-side configuration that partners never set — not by delivery_mode. delivery_mode: "home_drop" only selects this path in the legacy explicit-fields flow. See the routing table in CKO-03 Direct.

The home-drop path requires a unit_id on the session — a session without one is rejected with 422 rather than provisioned.

How it works

The key difference from direct delivery: there is no job_id in the response — provisioning hasn’t started. The subscription stays in PENDING_INSTALL state until a kurnl operator or technician completes the physical installation.

Third-line buildings get a customer booking link. When the building needs a technician on site (line_type = "third"), kurnl e-mails the subscriber a link to a public booking page in the provider portal within a minute of your callback. The customer picks a four-hour window (weekdays, at least 24 hours ahead by default) and can move or cancel it from the same link. Nothing to build on your side — the kurnl operator sees the booking and the customer’s contact details on the dispatch board. Second-line buildings ship a CPE instead and get no link.

Step-by-step

1. Configure your checkout URL

Same as direct delivery — the kurnl Marketplace creates a checkout session and redirects to your external_checkout_url with ?session_id=<uuid> appended. Read the session to get the details; for non-first-line buildings it carries a unit_id:

curl https://middleware.bso-projects.com/partner/external-checkout/sessions/SESSION_ID \
  -H "X-Webhook-Secret: YOUR_WEBHOOK_SECRET"

{
  "id": "c3d4e5f6-...",
  "service_provider_document_id": "a1b2c3d4-...",
  "plan_version_id": "f7e8d9c0-...",
  "unit_id": "c3d4e5f6-...",
  "building_id": "d4e5f6a7-...",
  "status": "pending",
  "expires_at": "2026-07-01T12:30:00Z",
  "units": { "unit_number": "304", "buildings": { "name": "Oak Towers", "address": "7 Oak Ave" } }
}

See Checkout Sessions for the full session API.

2. Collect subscriber details

The CKO-03 home-drop path does not collect a card in kurnl — kurnl creates the subscriber without a Stripe payment method. After the install is confirmed, kurnl attempts to charge a saved payment method if one exists; when none exists (the usual case on this path), it emails the subscriber a Stripe payment link for the first invoice instead. If you manage billing yourself, handle payment on your own timeline. Pass the session_id — kurnl reads the plan, unit, and provider from the session:

curl -X POST https://middleware.bso-projects.com/partner/external-checkout/complete \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: YOUR_WEBHOOK_SECRET" \
  -d '{
    "session_id": "c3d4e5f6-...",
    "subscriber": {
      "email": "bob@example.com",
      "username": "bob",
      "invoice_contact_detail": {
        "firstname": "Bob",
        "lastname": "Jones",
        "email": "bob@example.com"
      },
      "contract_contact_detail": {
        "firstname": "Bob",
        "lastname": "Jones",
        "email": "bob@example.com"
      },
      "invoice_address": {
        "street": "Oak Ave",
        "housenumber": "7",
        "unitnumber": "304",
        "postalcode": "B2C 3D4",
        "city": "Victoria",
        "province": "BC"
      }
    }
  }'

Successful response — 200 OK:

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

Note there is no job_id — provisioning has not started.

Despite the message text, /provisioning/confirm-install is a kurnl-staff endpoint (dashboard login), not part of the partner API — see step 5.

4. Wait for installation

kurnl fires subscription.pending_install to your webhook URL. The install is now in the operator’s queue — kurnl creates an internal install job and support ticket automatically. Store the subscription_id for your records. The subscription shows as PENDING_INSTALL until the install is completed.

5. Installation is completed by kurnl (not by you)

The install is finished through the kurnl dashboard / field-service flow: an operator maps the switch and port to the unit, marks the hardware shipped, and a technician confirms the install. The confirming call (POST /provisioning/confirm-install) requires kurnl dashboard staff credentials, takes only a subscription_id, and needs the operator-mapped install job to be in the SHIPPED state — there is nothing for your integration to call here. After the install is confirmed, kurnl provisions the port and then:

charges the subscriber’s saved payment method, if one exists → subscription ACTIVE, or
emails the subscriber a Stripe payment link (the usual case for CKO-03 home-drop, since no card was collected) → subscription becomes ACTIVE when they pay.

6. Track activation by polling

No webhooks fire on the install-completion path today. Do not wait for subscription.activated or provisioning.completed after the pending-install response — they are not sent for home-drop installs.

To know when the subscription is live, poll:

GET /partner/external-checkout/sessions/{session_id}/status — public, no auth, safe from the browser; subscription_status flips to ACTIVE (reference), or
GET /partner/external-checkout/sessions/{session_id} — the authenticated session read.

Webhook events

Event	When
`subscription.pending_install`	Immediately after your callback — the install is queued

No further webhooks fire for a home-drop subscription today (see above — poll for activation).

Handling unit availability

A unit can only have one pending or active subscription at a time. If you call the endpoint for a unit that already has a PENDING_INSTALL or ACTIVE subscription, you get 409 Unit already has a pending or active subscription. Check the unit’s status before presenting it as available in your checkout. You can query unit status via the kurnl dashboard or by checking the building’s unit list in your dashboard.

Getting Started

Operator Guides

Partner Integration

AI Support Agent

Changelog

CKO-03: External Checkout — Home-Drop Delivery

When to use this

How it works

Step-by-step

1. Configure your checkout URL

2. Collect subscriber details

4. Wait for installation

5. Installation is completed by kurnl (not by you)

6. Track activation by polling

Webhook events

Handling unit availability

​When to use this

​How it works

​Step-by-step

​1. Configure your checkout URL

​2. Collect subscriber details

​3. Call kurnl after signup

​4. Wait for installation

​5. Installation is completed by kurnl (not by you)

​6. Track activation by polling

​Webhook events

​Handling unit availability

When to use this

How it works

Step-by-step

1. Configure your checkout URL

2. Collect subscriber details

3. Call kurnl after signup

4. Wait for installation

5. Installation is completed by kurnl (not by you)

6. Track activation by polling

Webhook events

Handling unit availability