Batches

Honors Idempotency-Key. Up to 1,000 items per call. Create batch.json with operation: "create" and a nonempty items array of complete parcel payloads. Save it unchanged for retries.

curl -X POST "https://apis.cloud.feeef.org/v1/parcels/batch" \
  -H "Authorization: Bearer $FEEEF_CLOUD_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $REQUEST_KEY" \
  -d @batch.json

{ "data": { "id": "bat_5Qp…", "status": "queued", "total": 740, "succeeded": 0, "failed": 0 } }

What happens after 202

The platform splits the batch into carrier-sized chunks (Yalidine's limit is 50 items per request, for example — different per carrier, see /geo/couriers), throttles per carrier account so a 1,000-item batch doesn't trip the carrier's own rate limits, retries chunk-level failures item by item rather than failing the whole chunk for one bad row, and fires a batch.completed webhook event when every item has either succeeded or permanently failed.

This is why the response is 202 Accepted, not 201 Created — a batch is accepted for processing, not immediately done. Poll for the result:

curl "https://apis.cloud.feeef.org/v1/batches/bat_5Qp…" \
  -H "Authorization: Bearer $FEEEF_CLOUD_KEY"

Adds results[]: { index, status: "succeeded"|"failed", parcelId?, error? } — one entry per item, in the exact order you submitted them, so results[i] always corresponds to items[i] in your original request. This is what you diff against your own order list to find which specific rows need attention, without having to match by any other key.

Generate REQUEST_KEY="$(uuidgen)" once before a write and reuse $REQUEST_KEY with the identical body on retries.