Quickstart

1. Start in Test Mode

Create an isolated anonymous session with no signup or copied API key:

TOKEN="$(curl -fsS -X POST https://api.batchrelay.com/v1/anonymous-sessions | jq -r '.session_token')"

The token is a short-lived secret. The Batch Relay CLI performs this bootstrap and secure local storage automatically when its first stateful command runs. For durable CI or account-owned sandbox records, create a key with print_orders:write and print_orders:read in the developer dashboard. Test API keys use the br_test_ prefix. Live API keys use br_. Send both to https://api.batchrelay.com. The durable credential record selects Test Mode or Live Mode after authentication; a request field cannot change it. See Keyless Test Mode for the raw HTTP session flow.

2. Preview provider compatibility

Use a provider-neutral prepared order. The image is already prepared in its required orientation. This sample uses print-5x7, whose template_requirement is optional. You may submit prepared artwork directly or use a render first. Designed products require a succeeded Batch Relay render. Do not send a legacy composite product as a fulfillment line.

Each print-order asset accepts exactly one of url or asset_id. The compatibility route is read-only. Quote creation copies a URL into managed storage; an existing asset_id is reused in place.

curl -X POST https://api.batchrelay.com/v1/providers/compatibility \
  -H "Authorization: Bearer ${TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{
    "provider_id": "whcc",
    "order": {
      "schema_version": 1,
      "environment": "sandbox",
      "external_order_id": "weekend-test-001",
      "customer": { "email": "parent@example.com" },
      "ship_to": { "name": "Parent", "address_1": "123 Main St", "city": "Eagan", "state": "MN", "postal_code": "55121", "country": "US", "phone": "+16516468263" },
      "ship_from": { "name": "Studio", "address_1": "456 Studio Ave", "city": "Eagan", "state": "MN", "postal_code": "55121", "country": "US", "phone": "+16516468263" },
      "shipping_service": "economy",
      "items": [{
        "product": { "id": "print-5x7", "revision": 1 },
        "quantity": 1,
        "assets": [{ "role": "artwork", "url": "https://assets.example.com/5x7.jpg", "pixel_width": 1500, "pixel_height": 2100, "file_size_bytes": 240000, "format": "jpeg" }]
      }]
    }
  }'

Compatibility returns one provider and one result per line. Batch Relay never splits an order or substitutes another lab.

3. Create a quote

Send the same wrapper to POST /v1/print-orders/quote with an Idempotency-Key when any asset uses url. The response freezes the provider, selection source, capability revision, recipe revision, price, expiry, and managed asset bindings. Save its id. The source URL can disappear after the quote succeeds without breaking the accepted order.

4. Submit the frozen quote

POST /v1/print-orders requires quote_id, the matching order, and an Idempotency-Key. It cannot change the provider selected at quote time. See the canonical OpenAPI document for the complete request and response schemas.

Start

Core Concepts

Product reference

1. Start in Test Mode

2. Preview provider compatibility

3. Create a quote

4. Submit the frozen quote

​1. Start in Test Mode

​2. Preview provider compatibility

​3. Create a quote

​4. Submit the frozen quote

1. Start in Test Mode

2. Preview provider compatibility

3. Create a quote

4. Submit the frozen quote