Checkout Sessions

Sessions are how the kurnl Marketplace hands a subscriber over to your hosted checkout page. The Marketplace creates a session, redirects the subscriber to your external_checkout_url with ?session_id=<id> appended, and your page reads the session to get the plan, location, and delivery mode. See the flow guides: CKO-03 Direct, CKO-03 Home-Drop, CKO-03 Anonymous.

Endpoints

Method	Path	Auth	Description
`POST`	`/partner/external-checkout/sessions`	None (optional JWT)	Create a session (normally called by the kurnl Marketplace)
`GET`	`/partner/external-checkout/sessions/{session_id}`	`X-Webhook-Secret`	Read session state
`PATCH`	`/partner/external-checkout/sessions/{session_id}`	`X-Webhook-Secret`	Update plan (upsell) or your partner reference

Sessions expire after 30 minutes. Any endpoint that touches an expired session returns 410 Gone and marks it expired on the same call. Session lifecycle: pending → (redirected) → completed | expired | cancelled.

POST /partner/external-checkout/sessions

Creates a pending session and returns your hosted checkout URL with session_id appended. This endpoint is normally invoked by the kurnl Marketplace when a subscriber picks your plan — you only call it yourself if you originate checkouts programmatically. Auth: none required. If a signed-in kurnl user’s Bearer token is supplied, the session is linked to that account (so it appears in their hub).

Request body

{
  "service_provider_document_id": "uuid",
  "plan_version_id": "uuid",
  "delivery_mode": "direct | home_drop (optional)",
  "location_hash": "10-char hex (direct delivery, optional)",
  "location_identifier": "string (optional alternative to location_hash)",
  "unit_id": "uuid (home-drop, optional)",
  "building_id": "uuid (optional)",
  "mac_address": "string (optional)"
}

Response — 201 Created

{
  "id": "uuid",
  "external_checkout_url": "https://checkout.yoursite.com/?session_id=uuid",
  "expires_at": "2026-07-01T12:30:00Z"
}

In sandbox, external_checkout_url points to the kurnl fake-Stripe page instead of your configured checkout URL. If your provider has no external_checkout_url configured, the endpoint returns 503.

GET /partner/external-checkout/sessions/

Returns the current state of a session, with the referenced plan, unit/building, and provider embedded for display on your checkout page. Auth: X-Webhook-Secret header.

Response — 200 OK

{
  "id": "uuid",
  "status": "pending | redirected | completed",
  "service_provider_document_id": "uuid",
  "plan_version_id": "uuid",
  "delivery_mode": "direct | home_drop",
  "location_hash": "string | null",
  "location_identifier": "string | null",
  "unit_id": "uuid | null",
  "building_id": "uuid | null",
  "partner_reference": "string | null",
  "partner_subscriber_id": "string | null",
  "subscription_id": "uuid | null (set after completion)",
  "expires_at": "2026-07-01T12:30:00Z",
  "created_at": "2026-07-01T12:00:00Z",
  "updated_at": "2026-07-01T12:00:00Z",
  "plan_versions": {
    "id": "uuid",
    "retail_price_monthly": 79.0,
    "setup_fee": 0.0,
    "plans": { "id": "uuid", "name": "string", "description": "string" }
  },
  "units": {
    "id": "uuid",
    "unit_number": "304",
    "floor": "3",
    "building_id": "uuid",
    "buildings": { "id": "uuid", "name": "string", "address": "string" }
  },
  "service_providers": { "id": "uuid", "name": "string" }
}

expired and cancelled sessions are never returned as a body — they yield 410 Gone.

Error codes

Status	Meaning
`401`	Missing or invalid `X-Webhook-Secret`
`404`	Session not found
`410`	Session expired or cancelled — start a new checkout

PATCH /partner/external-checkout/sessions/

Upsell endpoint: swap the plan while the subscriber is still on your checkout page, or attach your own reference id. Only pending/redirected sessions are patchable. Auth: X-Webhook-Secret header.

Request body

Only these two fields are patchable — anything else (including unit_id, delivery_mode, service_provider_document_id) is rejected with 422.

{
  "plan_version_id": "uuid (must belong to the same provider)",
  "partner_reference": "string"
}

Response — 200 OK

Returns the updated session object (same shape as GET).

Error codes

Status	Meaning
`400`	`plan_version_id` not found
`403`	`plan_version_id` belongs to a different provider
`409`	Session no longer patchable (already completed)
`410`	Session expired or cancelled
`422`	Attempted to change an immutable field

Complete a session with subscriber PII: POST /external-checkout/complete
Complete without sharing PII: POST /external-checkout/anonymous-complete
Partner suspend/restore (in development): POST /external-checkout/subscription-status

Overview

Plan Discovery

Provisioning

Reports

Checkout Utilities

Subscribers & Subscriptions

AI Support Agent

Provider Operations (Internal API)

Endpoints

POST /partner/external-checkout/sessions

Request body

Response — 201 Created

GET /partner/external-checkout/sessions/

Response — 200 OK

Error codes

PATCH /partner/external-checkout/sessions/

Request body

Response — 200 OK

Error codes

​Endpoints

​POST /partner/external-checkout/sessions

​Request body

​Response — 201 Created

​GET /partner/external-checkout/sessions/

​Response — 200 OK

​Error codes

​PATCH /partner/external-checkout/sessions/

​Request body

​Response — 200 OK

​Error codes

​Related

Endpoints

POST /partner/external-checkout/sessions

Request body

Response — 201 Created

GET /partner/external-checkout/sessions/

Response — 200 OK

Error codes

PATCH /partner/external-checkout/sessions/

Request body

Response — 200 OK

Error codes

Related