Sandbox testing

Sandbox workspaces let you exercise billing flows without real money movement. Two test artifacts are available in sandbox and return 403 FORBIDDEN in live workspaces: test clocks simulate the passage of time, and payment simulations pin deterministic charge outcomes. Sandbox keys use the sk_test_... prefix - see Workspace context.

Test clocks

In sandbox workspaces, test_clocks simulate the passage of time so you can exercise renewal, dunning, and trial-expiration logic without waiting.

Code
# Create a test clock pinned to a specific time.
curl -X POST https://api.kontier.eu/v1/test-clocks \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "renewal-test",
    "frozen_at": "2026-01-01T00:00:00Z"
  }'

Request body:

Response (201) returns the clock with fields id, workspace_id, name, frozen_at, status (active | advancing | completed), created_at, updated_at.

Code
# Advance the clock forward.
curl -X POST https://api.kontier.eu/v1/test-clocks/{id}/advance \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "frozen_at": "2026-02-01T00:00:00Z" }'

The frozen_at field is required on advance. The advance triggers any time-dependent jobs (invoice runs, dunning steps, trial transitions) that would have fired between the previous and the new pinned time.

Other test-clock endpoints: GET /v1/test-clocks, GET /v1/test-clocks/{id}, DELETE /v1/test-clocks/{id}.

Payment simulations

Assign a fixed outcome to a payment method so that any charge against it resolves to that outcome instead of being sent to a real gateway.

Code
curl -X POST https://api.kontier.eu/v1/test-payment-simulations \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method_id": "pm_...",
    "outcome": "success"
  }'

Other endpoints: GET /v1/test-payment-simulations, DELETE /v1/test-payment-simulations/{id}.