Quickstart

Before you start

You need:

A kurnl provider account — sign up here
Your sandbox API key and webhook secret from Dashboard → Settings → API Keys
A test location hash from your account manager (or use the sandbox try-it panel in your dashboard)

Step 1 — Verify your credentials

curl https://api.kurnl.ca/api/v1/partner/marketplace/plans/me \
  -H "X-API-Key: YOUR_SANDBOX_API_KEY"

You should get a list of your active plan versions. If you get a 401, double-check you’re using the sandbox key (prefixed krnl_sb_).

Step 2 — Pick a plan version ID

From the response above, copy one document_id. This is your plan_version_id for the next step.

Step 3 — Provision your first subscriber

curl -X POST https://api.kurnl.ca/api/v1/partner/external-checkout/complete \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Secret: YOUR_SANDBOX_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 in sandbox) shortly after. No webhook URL yet? Use webhook.site to get a temporary receiver, then set it in Dashboard → Settings → Sandbox → Webhook URL.

Step 5 — Reset and repeat

The sandbox keeps state between calls. When you’re done testing, hit Reset transactional data in the dashboard sandbox settings to clear all test subscribers and subscriptions.

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.

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

Step 5 — Reset and repeat

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

​Step 5 — Reset and repeat

​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

Step 5 — Reset and repeat

Next steps