Test mode

Every organisation has test and live keys. Items created with a pb_test_ key are marked isTest, go through the complete lifecycle, produce webhooks and never reach production, the carrier or billing. Test keys only see test resources, plus the shared read-only ones (products, templates and their versions, fonts and assets).

Use test mode to build and verify an integration before switching the key.

Simulated runs

Production runs collect live items only. To exercise the rest of the lifecycle for test items, call POST /v1/test-runs with a test key (or trigger it from the Developers section of the portal). READY test items move through SCHEDULED_FOR_RUN, IN_PRODUCTION, the carrier handoff and COMPLETED in one call, and each step publishes its event: item.scheduled, item.in_production, item.handed_to_carrier, item.completed. Nothing is printed, charged or handed to a carrier.

HTTP

POST /v1/test-runs
Content-Type: application/json

{ "postflowId": "pf_…", "outcome": "COMPLETED" }

postflowId limits the run to one Postflow; itemIds (up to 500) names the items instead; without either, up to limit (default 100) READY test items of the organisation take part.
outcome is COMPLETED (default) or FAILED, which ends the items in FAILED with item.failed, so failure handling can be tested too.
Items that are not READY are reported under skipped with the reason (not_ready, not_found, postflow_paused); an address on the suppression list ends as SUPPRESSED, as it would at a real cutoff.

The response lists the items with their final status and the counts. The item event trail (GET /v1/items/{id}/events) shows the simulated steps with the testRunId. Live keys receive 403 permission_denied.

#Simulated runs

Simulated runs