​
What the sandbox does

The kurnl sandbox is a fully isolated environment. API calls in sandbox mode:
  • Create real database records — subscribers, subscriptions, provisioning jobs
  • Do not activate real switch ports or send commands to physical network equipment
  • Do not charge real Stripe payment methods
  • Fire real webhook events to your configured sandbox webhook URL
This means you can test your full integration flow — including webhook handling — without any production impact.

​
Getting your sandbox credentials

  1. Log in to your provider dashboard
  2. Go to Settings → API Keys
  3. Copy your sandbox API key (krnl_sb_...) and sandbox webhook secret
  4. Go to Documentation → Sandbox Settings to set your webhook URL and see your test location hashes
If you don’t have sandbox credentials yet, contact your kurnl account manager. Sandbox environments are provisioned separately from production.

​
Sandbox-specific values

Some values in sandbox are fixed test fixtures you use in your API calls:
ValueWhere to find it
service_provider_document_idDashboard → Settings → General
plan_version_idGET /partner/marketplace/plans/me using your sandbox key
location_hash (direct delivery)Dashboard → Documentation → Sandbox → Test locations
unit_id (home-drop)Dashboard → Documentation → Sandbox → Test locations

​
Try-it panels

The Documentation → Testing & Sandbox section in your dashboard has interactive try-it panels. These fire real API calls against your sandbox, with your credentials pre-filled. You don’t need to write any curl commands to explore the API.

​
Webhook testing

Set your sandbox webhook URL in Dashboard → Documentation → Sandbox Settings. When you save, kurnl sends a test ping to verify the URL is reachable. If you don’t have a server ready to receive webhooks, use webhook.site for a temporary receiver during development. kurnl delivers each event with up to 3 retry attempts (exponential back-off: 2s, then up to 30s). Your endpoint must return any 2xx status to acknowledge. Anything else is treated as a failure and retried.

​
Resetting state

The sandbox preserves data between test runs. To start fresh:
  1. Go to Dashboard → Documentation → Sandbox Settings
  2. Click Reset transactional data
This deletes all sandbox subscribers, subscriptions, provisioning jobs, and webhook events. It does not delete your plans, campaigns, or sandbox configuration.

​
Promoting to production

When your integration is working correctly in sandbox:
  1. Replace your sandbox X-API-Key with your production key (krnl_live_...)
  2. Replace your sandbox X-Webhook-Secret with your production webhook secret
  3. Replace api-staging.kurnl.ca with api.kurnl.ca in all endpoint URLs (if you were using the staging host)
  4. Update your service_provider_document_id to your production provider UUID
  5. Update your webhook URL to your production receiver
Production location_hash values come from real Marketplace redirects — you cannot use sandbox test hashes in production. Make sure your checkout flow reads location_hash dynamically from the redirect URL rather than hardcoding a value.