POST /external-checkout/subscription-status - kurnl Developer Docs

Coming soon — in development. This endpoint is not yet deployed. The request/response shapes below are the planned contract and may change before release.

For integrations where you own all billing (e.g. WooCommerce Subscriptions): when your billing system puts a subscription on hold, tell kurnl to suspend the port; when it becomes active again, tell kurnl to restore it. No kurnl invoices or fees are created either way — kurnl only performs the network action.

Endpoint

POST /partner/external-checkout/subscription-status

Authentication

X-Webhook-Secret header — same secret as the other external-checkout endpoints.

Request body

Identify the subscription either by the original checkout session_id (preferred) or by an explicit subscription_id + service_provider_document_id pair.

{
  "action": "suspend | restore",
  "session_id": "uuid (option A)",
  "subscription_id": "uuid (option B)",
  "service_provider_document_id": "uuid (option B)"
}

Response — 200 OK

{
  "subscription_id": "uuid",
  "action": "suspend",
  "subscription_status": "SUSPENDED",
  "port_changed": true,
  "message": "Suspended"
}

suspend resets the switch port to the captive portal and marks the subscription SUSPENDED.
restore queues port re-provisioning and marks the subscription ACTIVE.
Both actions are idempotent — repeating a call for a subscription already in the target state returns port_changed: false with an “Already …” message.
port_changed: false on a state change means kurnl had no switch/port data for the subscription; the status was updated but no network action was taken.

Error codes

Status	Meaning
`401`	Missing or invalid `X-Webhook-Secret`
`403`	Subscription belongs to a different provider
`404`	Subscription not found
`409`	Session has no subscription yet (checkout not completed)
`410`	Session expired or cancelled