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 it activates the subscription and provisions the port immediately; in second/third-line or unclassified buildings it creates a PENDING_INSTALL subscription plus an operator install job 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

1

Choose the external checkout type

In the dashboard, open Checkout and pick External checkout (your own store). WooCommerce is one kind of external store — there is no separate WooCommerce mode. Then set:
  • Store checkout URL — where kurnl sends shoppers to pay (the page your store serves).
  • Shared webhook secret — generate it here; your store sends it as X-Webhook-Secret on every call to kurnl.
Secrets are write-only once saved and cached briefly — a change can take a few minutes to take effect.
kurnl never calls into your WooCommerce store, so no WooCommerce REST API keys are needed. If you pasted WooCommerce consumer key/secret here in the past, they were never used — the fields have been removed.
2

Mint an API key (optional)

On the API Key page, generate a krnl_… key if your integration also reads plan data or reports. The checkout callbacks themselves authenticate with the shared webhook 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 are provisioned immediately (the response carries a job_id), while second/third-line or unclassified buildings get a PENDING_INSTALL subscription plus an operator install job — and the response has no job_id. Treat job_id as optional, and handle a 422 (unclassified building with no unit on the session).
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 the kurnl plan editor — 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 and term 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 and API Key pages, see Integrations & your team. For the full API contract, see the Partner Integration Overview.