GET /external-checkout/subscriptions/{external_subscription_id}

Look a subscription up by your own per-subscription identifier: the value you sent as external_subscription_id when you completed the checkout. You never have to store a kurnl id to find your own orders again. This is also how you show a truthful status on your own thank-you or account page. An order that needs a technician stays PENDING_INSTALL until the visit has happened — often for days — and nothing in the payment flow tells you when that changes.

Endpoint

GET /partner/external-checkout/subscriptions/{external_subscription_id}?service_provider_document_id={uuid}

Authentication

X-Webhook-Secret header — the same secret as the other external-checkout endpoints. The secret is verified before the lookup, so a wrong secret cannot be used to discover which identifiers exist. Rate-limited to 120 requests / minute.

Response — 200 OK

{
  "subscription_id": "uuid",
  "external_subscription_id": "wc_sub_881",
  "subscription_status": "PENDING_INSTALL",
  "is_anonymous": true,
  "install": {
    "job_id": "uuid",
    "workflow_state": "PENDING_LOCATION",
    "appointment_at": "2026-10-02T14:00:00Z",
    "on_hold": false,
    "booking_email_missing": false,
    "booking_invited_at": "2026-09-18T09:12:00Z"
  }
}

Field	Type	Meaning
`subscription_id`	string	kurnl’s own id, should you want to keep it.
`subscription_status`	string	`PENDING_INSTALL`, `ACTIVE`, `SUSPENDED`, `CANCELLED`, …
`is_anonymous`	boolean	`true` when kurnl holds no subscriber record — the customer has no kurnl portal account.
`install`	object \| null	Present only for an order that needs a technician visit. A direct order provisions without one and carries `null`.

Inside `install`

Field	Meaning
`workflow_state`	Where the job is in kurnl’s install flow.
`appointment_at`	The booked visit, or `null` while the customer has not picked a window.
`on_hold`	`true` while you have the order on hold — no booking link is sent and the customer cannot book. See subscription-status.
`booking_email_missing`	`true` when kurnl has no address to send the booking link to. Send `contact_email` on completion to avoid this; recovering it needs a kurnl operator.
`booking_invited_at`	When the booking link was sent, or `null` if it has not gone out yet.

No contact or address fields are returned. An anonymous subscription does not have them at all, and for a non-anonymous one they belong to the subscriber, not to the integration.

Error codes

Status	Meaning
`401`	Missing or invalid `X-Webhook-Secret`
`404`	`No subscription for this external_subscription_id`
`422`	`service_provider_document_id` missing
`429`	Rate limit exceeded (120 requests / minute)

Overview

Plan Discovery

Provisioning

Reports

Checkout Utilities

Subscribers & Subscriptions

AI Support Agent

Provider Operations (Internal API)

GET /external-checkout/subscriptions/{external_subscription_id}

Endpoint

Authentication

Response — 200 OK

Inside `install`

Error codes

​Endpoint

​Authentication

​Response — 200 OK

​Inside install

​Error codes

Endpoint

Authentication

Response — 200 OK

Inside `install`

Error codes