Quickstart

The partner API operates on your live account — there is no separate sandbox API key. Use a test location you control, and remember a real provisioning job will run. To explore kurnl with zero impact, use the in-dashboard sandbox (operator-facing) first.

Before you start

You need:

A kurnl provider account — contact your kurnl account manager to get onboarded
Your API key from the API Key page (/api-keys) and your shared webhook secret from the Checkout page (/checkout-settings)
A test location hash / unit you control (from a Marketplace redirect or your account manager)

Step 1 — Verify your credentials

curl https://middleware.bso-projects.com/partner/marketplace/plans/me \
  -H "X-API-Key: YOUR_API_KEY"

You should get a list of your active plan versions. If you get a 401, double-check your API key (krnl_...).

Step 2 — Pick a plan version ID

The response is wrapped as {"plan_versions": [...]} — copy one plan version’s id. This is your plan_version_id for the next step.

Step 3 — Provision your first subscriber

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 '{
    "service_provider_document_id": "YOUR_PROVIDER_ID",
    "plan_version_id": "PLAN_VERSION_ID_FROM_STEP_2",
    "delivery_mode": "direct",
    "location_hash": "YOUR_TEST_LOCATION_HASH",
    "subscriber": {
      "email": "test+qs@example.com",
      "username": "testuser",
      "password": "test-password-123",
      "customer_type": "RESIDENTIAL",
      "invoice_contact_detail": {
        "firstname": "Test",
        "lastname": "User",
        "email": "test+qs@example.com"
      },
      "contract_contact_detail": {
        "firstname": "Test",
        "lastname": "User",
        "email": "test+qs@example.com"
      },
      "invoice_address": {
        "street": "Maple St",
        "housenumber": "42",
        "postalcode": "A1B 2C3",
        "city": "Anytown",
        "province": "ON"
      }
    }
  }'

Expected response:

{
  "job_id": "3d6e8f12-...",
  "subscription_id": "8c4a1b9e-...",
  "subscriber_id": "2f5d7a0c-...",
  "message": "Provisioning started"
}

Step 4 — Check webhook delivery

If you have a webhook URL configured, you should receive a subscription.activated event within a few seconds and a provisioning.completed (or provisioning.failed) shortly after. No webhook URL yet? Use webhook.site to get a temporary receiver, then set it as the Webhook URL on your ISP Profile page.

The same email + plan combination is idempotent. Sending the same request twice returns the existing job_id with "Provisioning already in progress" — safe to retry on network errors.

Getting Started

Operator Guides

Partner Integration

AI Support Agent

Changelog

Before you start

Step 1 — Verify your credentials

Step 2 — Pick a plan version ID

Step 3 — Provision your first subscriber

Step 4 — Check webhook delivery

Next steps

CKO-03: Direct delivery

Authentication

​Before you start

​Step 1 — Verify your credentials

​Step 2 — Pick a plan version ID

​Step 3 — Provision your first subscriber

​Step 4 — Check webhook delivery

​Next steps

CKO-03: Direct delivery

Authentication

Before you start

Step 1 — Verify your credentials

Step 2 — Pick a plan version ID

Step 3 — Provision your first subscriber

Step 4 — Check webhook delivery

Next steps