Map a bulk queue item index back to a SKU: keep your own ledger

The queue receipt does not echo your item bodies. Each entry in items has index, status, run_id and error, so the join back to your catalog is yours to keep. Write the SKU-by-index table when you create the queue.

Why not read it from the output

It is tempting to bind an output_schema with an order_id or sku field and read it back. The docs warn against it: the projection step never sees input or instruction, so an id you supplied does not reliably round-trip. Your own ledger does not depend on the model.

The ledger

index is the zero-based position in the array you sent, in the same order. A row in your database per item is enough.

create table batch_item (
  queue_id   text not null,
  idx        int  not null,
  sku        text not null,
  run_id     text,
  status     text not null default 'queued',
  primary key (queue_id, idx)
);

-- after each poll of GET /v1/format-run-queues/{id}:
-- update batch_item set run_id = $1, status = $2
--   where queue_id = $3 and idx = $4;

Edge cases

• run_id is null while an item is queued, and stays null if the child failed to start; the item then carries format_run_failed_to_start.
• A bad item makes the create fail with 400 invalid_request and details.index, before any queue exists, so there is nothing to map yet.
• A replayed Idempotency-Key returns the old queue, so the same ledger rows still apply.