Batches

Bulk-create up to 1000 passes in a single request. The Worker processes items sequentially, item-level idempotent via your external_ref.

Limits

Limit	Value
Items per batch	1000
Active batches per tenant	10 (Pending + Processing)
Progress checkpoint interval	every 10 items

Create a Batch

POST /api/v1/batches

Headers:
  Authorization:   Bearer eyJhbGci...
  Idempotency-Key: nightly-import-2026-05-18

Body:
{
  "template_id": "3f2a1b4c-...",
  "intent":      "loyalty_card",
  "items": [
    {
      "external_ref": "cust-100",
      "data": { "member_name": "Anna", "member_id": "MBR100", "points": "100" }
    },
    {
      "external_ref": "cust-101",
      "data": { "member_name": "Ben",  "member_id": "MBR101", "points": "250" }
    }
  ]
}

● 202 Accepted

{
  "id":              "...",
  "status":          "pending",
  "total_count":     2,
  "completed_count": 0,
  "failed_count":    0,
  "progress_percent": 0,
  "job_id":          "...",
  "created_at":      "2026-05-18T10:00:00Z"
}

Get a Batch (with items)

GET /api/v1/batches/{id}

Returns the same shape as the create response, plus the items array with per-item success, pass_id and error.

Lifecycle

status	Meaning
pending	Queued, worker hasn't started.
processing	Worker is iterating items.
completed	Every item succeeded.
partial_success	Some items succeeded, others failed.
failed	Every item failed.
cancelled	Caller cancelled before processing started.

Cancel a Pending Batch

DELETE /api/v1/batches/{id}

Only pending batches can be cancelled. Once the worker enters processing, DELETE returns 409 invalid_state.

Errors

HTTP	error	When
400	invalid_request	> 1000 items, duplicate `external_ref` in items, missing fields.
400	invalid_template	Template not found / archived / wrong intent.
429	too_many_batches	Tenant already has 10 active batches.
409	invalid_state	DELETE on a non-pending batch.