Get Started with Batch Relay Print Orders Fast

This guide walks you through everything you need to submit your first print order against the Batch Relay API. By the end you’ll have a working sandbox order and a clear picture of how the billing gate behaves—all without touching production fulfillment.

Create an API account

Open the developer dashboard and create an individual API account. This gives you access to key management, usage reporting, and sandbox tooling.

https://app.batchrelay.com/developers

You don’t need an active billing method to create an account or submit sandbox orders. Billing is only required when you switch to the production environment.

Create an API key

Inside the developer dashboard, create a new API key and assign it the following scopes:

Scope	Why you need it
`print_orders:write`	Allows your key to create new print orders.
`print_orders:read`	Allows your key to check order status.

Copy your key immediately after creation. Batch Relay stores only a hash, a short prefix, and a masked display value — the full key is shown exactly once.

Create a sandbox order

With your key in hand, send a POST request to the print-orders endpoint. Setting "environment": "sandbox" ensures the order goes through validation and returns a real response without triggering live fulfillment.

curl -i -X POST "https://api.batchrelay.com/v1/print-orders" \
  -H "Authorization: Bearer br_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-order-001" \
  -d '{
    "environment": "sandbox",
    "externalOrderId": "test-order-001",
    "items": [
      {
        "product": "photo-print-5x7",
        "quantity": 1,
        "image": {
          "url": "https://images.batchrelay.com/team-5x7.jpg"
        }
      }
    ],
    "shipTo": {
      "name": "Test Customer",
      "addr1": "1337 Williams Street",
      "city": "Spokane",
      "state": "WA",
      "zip": "99201",
      "country": "US"
    }
  }'

A successful response uses a stable envelope with a top-level data object, the active environment, and a unique request_id you can use for support and logging:

{
  "data": {
    "environment": "sandbox",
    "id": "mn7...",
    "status": "created"
  },
  "environment": "sandbox",
  "request_id": "req..."
}

The Idempotency-Key header lets you safely retry a request without creating duplicate orders. Use a unique value per logical order—your own externalOrderId is a good choice.

Test billing in sandbox

You can exercise the billing gate in sandbox mode without touching production fulfillment. Add a billing object to your request body with "required": true:

{
  "environment": "sandbox",
  "billing": {
    "required": true
  }
}

If your account doesn’t have an active billing method, the API responds with a 402 status and the billing_required error code. This lets you verify that your integration handles the billing gate correctly before going live.

Switching your requests to "environment": "production" will submit real orders for fulfillment and charge your billing method. Make sure you’re ready before making that change.

Documentation Index