Create an order's AWB
const url = 'https://api.connectato.com/v1/shipments';const options = { method: 'POST', headers: { 'Idempotency-Key': 'example', Authorization: 'Bearer <token>', 'Content-Type': 'application/json' }, body: '{"order_id":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.connectato.com/v1/shipments \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'Idempotency-Key: example' \ --data '{ "order_id": "example" }'Scope: write_shipments.
With the delivery service picked on the order, exactly as the “Generate AWB” button. The courier is called in
the background: the answer is 202 with the shipment as it is (usually pending); follow it with
GET /shipments/{id} until it is created (its AWB issued), failed (error_code says why; asking again
retries it in place) or needs_attention (the courier’s answer is unknown: a person checks at the courier).
Requires an Idempotency-Key.
Refusals (code, the reason in detail): order_inactive (409, the order is no longer active in its store),
order_has_shipment (409, an AWB is already asked, issued or of unknown outcome), order_not_ready (409, a
blocking issue of its AWB step, no delivery service picked, or its prices on their way: ask again once ready),
try_again_later (409, the courier out of reach or turning requests away, or the order changing meanwhile),
shipment_refused (422: the service is off, or the order cannot be put in the courier’s terms).
Authorizations
Section titled "Authorizations"Parameters
Section titled "Parameters"Header Parameters
Section titled "Header Parameters"1 to 255 visible ASCII characters
A unique value per operation, sent again on a retry: a success or a definitive refusal is replayed for 24 hours; a validation failure, a 429 or a refusal whose code may pass later is not kept, so a retry with the same key runs again.
Request Bodyrequired
Section titled "Request Bodyrequired"Asks for an order’s AWB. The order is named by its public id and must be
one of the caller’s organization: an unknown one is a validation error on
order_id (a body field, never a 404). The scope is the authorization.
object
The order’s public id (ord_...).
Example generated
{ "order_id": "example"}Responses
Section titled "Responses"ShipmentResource
object
The shipment’s public id (shp_...).
The order it ships (ord_...); null once the order was deleted.
Outbound (to the buyer) or return (back to the merchant). New values may appear: treat one you do not know as such.
Pending, failed, needs_attention, created, picked_up, in_transit, customs_hold, out_for_delivery, awaiting_pickup, delivery_issue, delivered, returning, returned, cancelled, lost. New values may appear: treat one you do not know as such.
The vendor code of the integration the AWB was made through (woot, sameday, fancourier, …); kept when the account is removed.
The courier account (an installed integration, int_...); null once it was removed.
Who physically transports the parcel (dpd, sameday, fancourier, …); null until known.
The courier’s service code the AWB was asked with.
The carrier’s tracking number; null until the courier issues it. Not unique across couriers.
Whether the label can be printed in the app now; the label file is not served by API v1.
Why it is failed or needs_attention, a stable code: account_unavailable, not_supported, credentials_rejected, rate_limited, invalid_data, vendor_rejected, not_sent, outcome_unknown. Null in any other status. New codes may appear. New values may appear: treat one you do not know as such.
The code’s meaning, in English; the app shows the merchant the full reason in their language.
The courier’s own words when it answered (vendor_rejected), as it sent them, in its language: for display only, never to parse.
Address (the recipient’s door) or pickup_point (a locker, office or partner point); an order’s delivery.method in the same codes. New values may appear: treat one you do not know as such.
The point it is delivered to, for a pickup_point delivery; null otherwise.
object
The point’s id in the courier’s ids.
Every parcel of the shipment, in order (as many as the courier was asked for).
object
Parcel, envelope or pallet. New values may appear: treat one you do not know as such.
The parcel’s own tracking number, where the courier issues one per parcel.
Cash on delivery the courier collects from the recipient; null without.
object
The declared (insured) value; null when none was declared.
object
The v1 address shape (first_name, last_name, locality_code and the like null where the AWB holds none) plus the person to ask for at a company.
object
object
Carrier: cancelled at the courier (asked by the platform, or reported by its tracking); local: cancelled in the platform only (a courier without a cancel API, or a shipment set aside without an AWB).
object
New values may appear: treat one you do not know as such.
The courier’s latest tracking events, at most 20, newest last.
object
The same codes as status; null when the courier’s own status maps to none. New values may appear: treat one you do not know as such.
The event as the courier worded it, untranslated.
Where it happened, as the courier reported it.
When the AWB was asked for.
Example generated
{ "id": "example", "order_id": "example", "direction": "example", "status": "example", "vendor": "example", "integration_id": "example", "carrier": "example", "service_code": "example", "awb": "example", "label_available": true, "error_code": "example", "error_message": "example", "vendor_message": "example", "delivery_method": "example", "pickup_point": { "external_id": "example" }, "total_weight_kg": "example", "parcels": [ { "kind": "example", "weight_kg": "example", "length_cm": "example", "width_cm": "example", "height_cm": "example", "tracking_number": "example" } ], "cod": { "amount": "example", "currency": "example" }, "declared_value": { "amount": "example", "currency": "example" }, "sender": { "name": "example", "first_name": "example", "last_name": "example", "company": "example", "email": "example", "phone": "example", "address_line_1": "example", "address_line_2": "example", "city": "example", "region": "example", "region_code": "example", "postal_code": "example", "country_code": "example", "locality_code": "example", "contact_person": "example" }, "recipient": { "name": "example", "first_name": "example", "last_name": "example", "company": "example", "email": "example", "phone": "example", "address_line_1": "example", "address_line_2": "example", "city": "example", "region": "example", "region_code": "example", "postal_code": "example", "country_code": "example", "locality_code": "example", "contact_person": "example" }, "cancellation": { "kind": "example", "cancelled_at": "2026-04-15T12:00:00Z" }, "tracking_events": [ { "status": "example", "description": "example", "location": "example", "occurred_at": "2026-04-15T12:00:00Z" } ], "picked_up_at": "2026-04-15T12:00:00Z", "delivered_at": "2026-04-15T12:00:00Z", "returned_at": "2026-04-15T12:00:00Z", "created_at": "2026-04-15T12:00:00Z", "updated_at": "2026-04-15T12:00:00Z"}Headers
Section titled "Headers"Requests allowed per minute (per caller; before authentication, failed attempts per address).
Requests left in the current minute.
true when this is the stored answer of an earlier request with the same Idempotency-Key.
Missing or malformed Idempotency-Key (idempotency_key_required, idempotency_key_invalid).
object
The documentation URL of the code.
A short summary of the error, in English.
The HTTP status, repeated.
The stable code: one of bad_request, unauthenticated, insufficient_scope, forbidden, not_found, method_not_allowed, payload_too_large, validation_failed, idempotency_key_required, idempotency_key_invalid, idempotency_key_reused, idempotency_in_progress, conflict, rate_limited, server_error, unavailable, or the code an endpoint declares for a refused action.
The explanation for this case, in English.
Validation only: the messages per field.
object
Example generated
{ "type": "https://example.com", "title": "example", "status": 1, "code": "example", "detail": "example", "errors": { "additionalProperty": [ "example" ] }}Headers
Section titled "Headers"Requests allowed per minute (per caller; before authentication, failed attempts per address).
Requests left in the current minute.
No valid access token.
object
The documentation URL of the code.
A short summary of the error, in English.
The HTTP status, repeated.
The stable code: one of bad_request, unauthenticated, insufficient_scope, forbidden, not_found, method_not_allowed, payload_too_large, validation_failed, idempotency_key_required, idempotency_key_invalid, idempotency_key_reused, idempotency_in_progress, conflict, rate_limited, server_error, unavailable, or the code an endpoint declares for a refused action.
The explanation for this case, in English.
Validation only: the messages per field.
object
Example generated
{ "type": "https://example.com", "title": "example", "status": 1, "code": "example", "detail": "example", "errors": { "additionalProperty": [ "example" ] }}Headers
Section titled "Headers"Requests allowed per minute (per caller; before authentication, failed attempts per address).
Requests left in the current minute.
Bearer: send an access token as a Bearer token.
The app was not granted the scope (insufficient_scope).
object
The documentation URL of the code.
A short summary of the error, in English.
The HTTP status, repeated.
The stable code: one of bad_request, unauthenticated, insufficient_scope, forbidden, not_found, method_not_allowed, payload_too_large, validation_failed, idempotency_key_required, idempotency_key_invalid, idempotency_key_reused, idempotency_in_progress, conflict, rate_limited, server_error, unavailable, or the code an endpoint declares for a refused action.
The explanation for this case, in English.
Validation only: the messages per field.
object
Example generated
{ "type": "https://example.com", "title": "example", "status": 1, "code": "example", "detail": "example", "errors": { "additionalProperty": [ "example" ] }}Headers
Section titled "Headers"Requests allowed per minute (per caller; before authentication, failed attempts per address).
Requests left in the current minute.
A request with this Idempotency-Key is still running, or the action is refused by the record’s state.
object
The documentation URL of the code.
A short summary of the error, in English.
The HTTP status, repeated.
The stable code: one of bad_request, unauthenticated, insufficient_scope, forbidden, not_found, method_not_allowed, payload_too_large, validation_failed, idempotency_key_required, idempotency_key_invalid, idempotency_key_reused, idempotency_in_progress, conflict, rate_limited, server_error, unavailable, or the code an endpoint declares for a refused action.
The explanation for this case, in English.
Validation only: the messages per field.
object
Example generated
{ "type": "https://example.com", "title": "example", "status": 1, "code": "example", "detail": "example", "errors": { "additionalProperty": [ "example" ] }}Headers
Section titled "Headers"Requests allowed per minute (per caller; before authentication, failed attempts per address).
Requests left in the current minute.
true when this is the stored answer of an earlier request with the same Idempotency-Key.
Validation failed (validation_failed, errors per field), the action’s rules refuse it, or an Idempotency-Key was reused for another request (idempotency_key_reused).
object
The documentation URL of the code.
A short summary of the error, in English.
The HTTP status, repeated.
The stable code: one of bad_request, unauthenticated, insufficient_scope, forbidden, not_found, method_not_allowed, payload_too_large, validation_failed, idempotency_key_required, idempotency_key_invalid, idempotency_key_reused, idempotency_in_progress, conflict, rate_limited, server_error, unavailable, or the code an endpoint declares for a refused action.
The explanation for this case, in English.
Validation only: the messages per field.
object
Example generated
{ "type": "https://example.com", "title": "example", "status": 1, "code": "example", "detail": "example", "errors": { "additionalProperty": [ "example" ] }}Headers
Section titled "Headers"Requests allowed per minute (per caller; before authentication, failed attempts per address).
Requests left in the current minute.
true when this is the stored answer of an earlier request with the same Idempotency-Key.
Too many requests: retry after Retry-After seconds.
object
The documentation URL of the code.
A short summary of the error, in English.
The HTTP status, repeated.
The stable code: one of bad_request, unauthenticated, insufficient_scope, forbidden, not_found, method_not_allowed, payload_too_large, validation_failed, idempotency_key_required, idempotency_key_invalid, idempotency_key_reused, idempotency_in_progress, conflict, rate_limited, server_error, unavailable, or the code an endpoint declares for a refused action.
The explanation for this case, in English.
Validation only: the messages per field.
object
Example generated
{ "type": "https://example.com", "title": "example", "status": 1, "code": "example", "detail": "example", "errors": { "additionalProperty": [ "example" ] }}Headers
Section titled "Headers"Requests allowed per minute (per caller; before authentication, failed attempts per address).
Requests left in the current minute.
Seconds to wait before retrying.