​
When to use this

Use CKO-03 home-drop delivery when:
  • The subscriber’s building is already mapped in kurnl (has a building record with units), but the specific unit does not yet have a switch port assigned
  • You want subscribers to commit before you dispatch a technician
  • Payment is deferred until after installation is confirmed
If the subscriber’s port already exists and is assigned, use CKO-03 direct delivery instead.

​
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 technician confirms the physical installation.

​
Step-by-step

​
1. Configure your checkout URL

Same as direct delivery — kurnl Marketplace redirects to your external_checkout_url. For home-drop buildings, the redirect includes unit_id instead of location_hash:
ParameterDescription
unit_idUUID of the specific building unit the subscriber selected
plan_version_idUUID of the plan version
service_provider_document_idYour provider UUID
Example redirect: 
https://checkout.yourcompany.com/internet?unit_id=c3d4e5f6-...&plan_version_id=f7e8...&service_provider_document_id=a1b2...

​
2. Collect subscriber details

For home-drop, payment timing is flexible:
  • Card on file now, charge later — collect a card at checkout but don’t charge until the installation is confirmed. This is kurnl’s default behaviour when you use kurnl-managed billing.
  • Defer entirely — collect nothing at checkout, send a payment link after installation.
You decide which flow fits your business. kurnl sends the subscriber a Stripe payment link automatically after the technician confirms the install (if you’re using kurnl’s billing). If you manage billing yourself, handle payment on your own timeline.

​
3. Call kurnl after signup

curl -X POST https://api.kurnl.ca/api/v1/partner/external-checkout/complete \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: YOUR_WEBHOOK_SECRET" \
  -d '{
    "service_provider_document_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "plan_version_id": "f7e8d9c0-b1a2-3456-cdef-012345678901",
    "delivery_mode": "home_drop",
    "unit_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "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."
}
Note there is no job_id — provisioning has not started.

​
4. Dispatch a technician

kurnl fires subscription.pending_install to your webhook URL. This is your trigger to schedule the installation. Store the subscription_id — your technician will need it to confirm the install. The subscription shows as PENDING_INSTALL in your dashboard until confirmed.

​
5. Confirm installation (technician step)

When the physical fibre drop is installed and the port is patched, call the confirm-install endpoint from your field system or manually from the dashboard: 
curl -X POST https://api.kurnl.ca/api/v1/provisioning/confirm-install \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subscription_id": "8c4a1b9e-...",
    "switch_id": "switch-uuid",
    "port_number": 12
  }'
kurnl assigns the port to the subscription, triggers SSH provisioning, and emails the subscriber a Stripe payment link.

​
6. Activation

After the subscriber pays via the Stripe link, kurnl activates the subscription and fires subscription.activated to your webhook.

​
Webhook events

EventWhen
subscription.pending_installImmediately after your callback — trigger to schedule install
subscription.activatedAfter subscriber pays — internet is live
provisioning.completedSSH provisioning finished — port is configured
provisioning.failedSSH provisioning failed — contact support

​
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 subscription, you get a 409 conflict. 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.