Run checkout on your own WooCommerce store while kurnl provisions the service. The shopper browses and picks a plan in the kurnl marketplace; at checkout they’re handed to your WooCommerce store to pay, and once the order is paid kurnl takes over: in first-line buildings, and for a second- or third-line suite whose router is already online, it activates the subscription and provisions the port immediately; for every other suite it creates a PENDING_INSTALL subscription and kurnl schedules the install instead.
kurnl does not ship a WooCommerce plugin. Connecting your store is a small server-to-server integration your developer builds against kurnl’s external-checkout API: read the checkout session, call kurnl when an order is paid, and — because you bill — tell kurnl to suspend/restore when a subscription payment fails or recovers. This keeps your store fully under your control and unaffected by kurnl releases.
WooCommerce stays your source of truth for the catalog, pricing and billing. kurnl never charges the shopper — it only creates the subscriber and configures the network port.

​
What’s involved

Selling through WooCommerce is an external checkout (CKO-03) with WooCommerce as the storefront. It needs a developer to wire your store to kurnl once; after that it runs on its own.
  1. The shopper selects a plan in the kurnl marketplace.
  2. kurnl creates a checkout session and redirects them to your store’s checkout URL with a session_id.
  3. Your store reads the session (kurnl API), shows the matching WooCommerce product, and the shopper pays.
  4. On payment, your store calls kurnl to provision the subscription.
  5. Your store then sends the shopper back to the kurnl marketplace return page — https://<marketplace-host>/external-checkout/return?session_id=<id> — which polls the public session-status endpoint and shows provisioning progress. Without this redirect the shopper is stranded on your thank-you page with no service status.
  6. When your billing puts a subscription on-hold or active again, your store tells kurnl to suspend or restore the port.

​
Prerequisites

  • A WooCommerce store — any setup works; kurnl never touches your store.
  • The WooCommerce Subscriptions extension and a tokenising gateway (Stripe / WooPayments) for recurring billing.
  • One WooCommerce product per kurnl plan you want to sell. Keep your own SKUs and prices — WooCommerce owns them.
  • A developer to implement the kurnl external-checkout API in your store (session read, order-paid callback, and suspend/restore hooks).

​
Step 1 — Checkout settings in kurnl

Your kurnl admin sets the Checkout type to External checkout (your own store) under Billing → Checkout & Integrations, with your Store checkout URL and a Shared webhook secret — see Checkout. WooCommerce is one kind of external store; there is no separate WooCommerce mode. Your store sends the shared secret as X-Webhook-Secret on every call to kurnl. kurnl never calls into your WooCommerce store, so no WooCommerce REST API keys are needed. If your integration also reads plan data or reports, create a partner API key — see Partner API keys. The checkout callbacks themselves authenticate with the shared secret, not the API key.

​
Step 2 — Connect your store (developer)

Your developer wires four things into the store. Each is covered in the partner guides — this is the WooCommerce mapping:
1

Read the session on the checkout page

When kurnl redirects the shopper to your store with ?session_id=…, fetch the session — GET /external-checkout/sessions/{session_id} with your shared secret as X-Webhook-Secret — to learn which plan and location they chose, then add the matching WooCommerce product to the cart. See Direct delivery.
2

Provision on a paid order

Hook WooCommerce’s order-paid / order-completed event and call POST /external-checkout/complete with the session and the shopper’s details. kurnl creates the subscriber; what happens next depends on the building’s line type: first-line buildings, and second- or third-line suites whose router is already online, are provisioned immediately (the response carries a job_id); every other suite gets a PENDING_INSTALL subscription and kurnl schedules the install — and the response has no job_id. Treat job_id as optional, and handle a 422 (unclassified building with no unit on the session).The call also answers 422 with detail.code = "speed_tier" when the plan is faster than the building’s connection delivers. Nothing is created, but the shopper has already paid in your store — refund the order or move them to a plan within the building’s speed. A 503 (“Could not verify the building’s speed tier”) means retry. All responses are listed in Direct delivery.
3

Send the shopper back to kurnl

After calling /complete, redirect the shopper from your thank-you page to https://<marketplace-host>/external-checkout/return?session_id=<id>. That page polls the public GET /external-checkout/sessions/{session_id}/status endpoint and shows the shopper their provisioning progress.
4

Sync suspend / restore from your billing

Because WooCommerce owns billing, map the WooCommerce Subscriptions on-hold / active hooks to POST /external-checkout/subscription-status (suspend / restore) so a failed payment actually cuts service and a recovery restores it. See Suspend / restore.
The session read returns plan_versions.woocommerce_product_id — set per plan version in Configurations → Plans, field WooCommerce Product ID / SKU — as the intended key for mapping the selected kurnl plan to a WooCommerce product (legacy fallback convention: WooCommerce SKU == plan_version_id). The mapping still executes in your store: your integration reads the session and picks the product. Keep each product’s price in sync with the kurnl plan.

​
Step 3 — Test the integration

1

Test the callbacks in the sandbox

The redirect leg cannot be tested against a staging store: for a sandbox provider, session creation ignores your Store checkout URL and redirects to a kurnl-internal fake-payment page instead. What you can sandbox-test are the callbacks — /complete and /subscription-status — using the sandbox provider id and sandbox webhook secret from GET /sandbox/provider-info. See Sandbox.
2

Run one plan end-to-end against a test location

From the marketplace, start a checkout for a plan at a test location you control. Confirm your store shows the right product, pay with a gateway test card, and check the subscription appears in kurnl and the shopper lands back on the kurnl return page.

​
Troubleshooting

  • Nothing to buy at the store — your integration didn’t resolve the session to a product. Log the session_id and the GET /external-checkout/sessions/{session_id} response (send your X-Webhook-Secret) and confirm the plan maps to a published WooCommerce product.
  • Service not cut on a failed payment — check your WooCommerce Subscriptions on-hold hook is calling subscription-status with action: "suspend".
For the checkout settings, see Checkout; for API keys, Integrations & your team. For the full API contract, see the Partner Integration Overview.