Overview

V2 is a REST API with two interaction patterns:

• Ingest endpoints (POST /ingest/*) are asynchronous — they queue data for background processing and return 202 Accepted immediately with a request_id. Use GET /requests/{request_id} to poll for the final result.
• Read endpoints (GET /orders/*, GET /requests/*) are synchronous and return results directly.

What V2 supports:

• Submitting orders
• Submitting inventory snapshots
• Submitting shipments
• Submitting return requests and per-item disposition decisions
• Retrieving return requests and registering webhooks for return events
• Retrieving orders (incremental polling for WMS/ERP fulfillment workflows)
• Querying request processing status

Unlike V1, V2 derives your account from the Bearer token — there is no {account_id} in the URL. All resources created with a token belong to that token’s account.

Async processing model

All ingest endpoints (POST /ingest/*) process data asynchronously. The request is validated, queued, and returns 202 Accepted immediately with a request_id and trace_id. Poll with the request_id; if you need to contact support about a specific request, include the trace_id too — it’s what support uses to look up the request across Gierd’s systems.

Use GET /requests/{request_id} to poll for the outcome:

Status lifecycle: pending → processing → succeeded | failed | dead

{
  "message": "Request accepted for processing",
  "request_id": "550e8400-e29b-41d4-a716-446655440002",
  "trace_id": "trace-abc123def459"
}

Open the full API reference