Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.batchrelay.com/llms.txt

Use this file to discover all available pages before exploring further.

The sandbox environment gives you a safe space to build and test your Batch Relay integration without touching production fulfillment. You activate it by setting "environment": "sandbox" in your request body, and from that point forward the request runs through the full API pipeline — authentication, validation, idempotency, and billing — without ever dispatching a real print job.
Sandbox requests must never submit production fulfillment. The sandbox is strictly for development and automation testing. If you need to validate a live print order, use a production request in a controlled environment with a clearly labeled test image.

​
What the Sandbox Supports

The sandbox is designed to exercise all of the meaningful API behaviors your integration will encounter in production:
  • Validate API keys — confirm your credentials are correctly configured before you go live.
  • Create API print-order records — generate real order objects in your account that you can inspect via the dashboard or API.
  • Exercise idempotency — replay requests with the same Idempotency-Key and verify that duplicate orders are not created.
  • Exercise billing gates — trigger the billing_required response path without spending real money.
  • Import orders into WHCC sandbox validation endpoints — later-stage testing against the WHCC sandbox can be layered on top of Batch Relay sandbox orders.

​
Testing the Billing Gate

To verify that your integration handles a missing or inactive billing method correctly, include the billing.required flag in your sandbox request. This instructs the API to enforce the billing check even though no production fulfillment will occur: 
{
  "environment": "sandbox",
  "billing": {
    "required": true
  }
}
If your account billing is inactive when this request is received, the API returns a 402 Payment Required response with the billing_required error code. Your integration should detect this response and surface a clear prompt for the user to complete billing setup.
Use the billing gate test as part of your automated test suite so that you catch billing-configuration regressions before they affect real customers in production.