Responses and data formats

Success

{ "success": true, "data": { "id": "cm3o7rd0e0001h2j3k4l5m6n" } }

List endpoints add meta (see Pagination):

{ "success": true, "data": [{ "id": "cm3o7rd0e0001h2j3k4l5m6n" }], "meta": { "total": 120, "page": 1, "limit": 50, "pageCount": 3 } }

A call that creates something returns 201 with the new resource. Other successful calls return 200. Writes return the resource as it is after the change, exactly as the matching GET returns it where there is one (for example POST /v1/sku-mappings returns a mapping summary).

Errors

{ "success": false, "error": "This shipment was updated. Please review it again.", "code": "shipment_changed" }

Validation errors add details, one entry per problem:

{ "success": false, "error": "Quantities must be at least 1.", "code": "validation_failed", "details": [{ "path": "lines.0.qty", "message": "Quantities must be at least 1." }] }

See Errors.

Headers on every response

The public OpenAPI document is the one exception: it may be cached and has no X-Request-Id.

Sending requests

• Send request bodies as JSON with Content-Type: application/json. Another content type returns 415 unsupported_media_type; JSON that doesn't parse returns 400 invalid_json.
• A body can be at most 1 MB (413 payload_too_large) and nested at most 64 levels deep.
• Text can't contain NUL characters (\u0000).
• On endpoints that take a body, an empty body returns 422 validation_failed, except on POST /v1/orders/preview and POST /v1/orders/{id}/cancel, where an empty body counts as {}. Endpoints that take no body, such as POST /v1/shipments/{id}/cancel, ignore it.
• Fields the endpoint doesn't know are ignored. Text values are trimmed, and control characters are removed from most of them.
• Send each query parameter at most once: a repeated parameter returns 422 validation_failed on every endpoint. Unknown query parameters are ignored.
• In a query string, encode + as %2B (for example in a time zone offset); otherwise it arrives as a space.

Data formats

HTTP status codes