When to use this
You land on the home-drop path whenever the suite needs a technician visit or a shipped router: a second- or third-line building where the suite’s router is not online yet, or a shared suite. An unclassified building (line type NULL) always takes this path. kurnl then creates the subscription inPENDING_INSTALL with an operator install job
instead of provisioning a switch. A first-line suite is provisioned at once, also when
the subscriber reached it through address search or a QR landing (see
CKO-03 Direct).
This routing is decided by the building’s line type — operator-side configuration
that partners never set — and by whether the suite’s router is already online, not by
delivery_mode. In the legacy explicit-fields flow delivery_mode: "home_drop" only
says that you send a unit_id; the building still decides. See the routing table in
CKO-03 Direct.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 nojob_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: the kurnl operator ships the
router to the service address and e-mails the subscriber the tracking link.Step-by-step
1. Configure your checkout URL
Same as direct delivery — the kurnl Marketplace creates a checkout session and redirects to yourexternal_checkout_url with ?session_id=<uuid> appended. Read the session to get the details; outside first line it carries a unit_id:
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.3. Call kurnl after signup
Pass thesession_id — kurnl reads the plan, unit, and provider from the session:
job_id — provisioning has not started.
If the unit is part of a shared suite (several connections), the response also carries "unit_confirmation_pending": true: kurnl placed the order on the suite’s first free connection and the operator still has to confirm which connection is the customer’s before the install proceeds. It is false for any other unit.
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 firessubscription.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, and marks that ticket resolved when the line goes live. Store the subscription_id for your records.
The subscription shows as PENDING_INSTALL until the install is completed. (A line that was cancelled and
later reactivated through a technician visit passes through PENDING_INSTALL again with a second,
reinstall install job — a subscription holds at most one open install job, not one for ever.)
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.
On a second-line building nobody visits: the operator ships the router, the port is provisioned the moment it
ships, and the line activates — and the charge or payment link below happens — about an hour after the subscriber
plugs the router in and it connects. confirm-install is not used for these orders.
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
ACTIVEwhen they pay.
6. Track activation by polling
To know when the subscription is live, poll:GET /partner/external-checkout/sessions/{session_id}/status— public, no auth, safe from the browser;subscription_statusflips toACTIVE(reference), orGET /partner/external-checkout/sessions/{session_id}— the authenticated session read.
Webhook events
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 aPENDING_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.
For a shared suite the same applies per suite: when every connection is taken you get 409 no_free_connection, and a retry of an order you already placed returns it instead of taking another connection.
You can query unit status via the kurnl dashboard or by checking the building’s unit list in your dashboard.