Skip to content

Create an order's AWB

POST
/shipments
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).

Idempotency-Key
required

1 to 255 visible ASCII characters

string

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.

Media typeapplication/json
StoreShipmentRequest

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
order_id
required

The order’s public id (ord_...).

string
<= 64 characters /^ord_[0-9a-z]{26}$/

Example generated

{
"order_id": "example"
}

ShipmentResource

Media typeapplication/json
ShipmentResource
object
id
required

The shipment’s public id (shp_...).

string
/^shp_[0-9a-z]{26}$/
order_id
required

The order it ships (ord_...); null once the order was deleted.

string | null
/^ord_[0-9a-z]{26}$/
direction
required

Outbound (to the buyer) or return (back to the merchant). New values may appear: treat one you do not know as such.

string
status
required

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.

string
vendor
required

The vendor code of the integration the AWB was made through (woot, sameday, fancourier, …); kept when the account is removed.

string
integration_id
required

The courier account (an installed integration, int_...); null once it was removed.

string | null
/^int_[0-9a-z]{26}$/
carrier
required

Who physically transports the parcel (dpd, sameday, fancourier, …); null until known.

string | null
service_code
required

The courier’s service code the AWB was asked with.

string | null
awb
required

The carrier’s tracking number; null until the courier issues it. Not unique across couriers.

string | null
label_available
required

Whether the label can be printed in the app now; the label file is not served by API v1.

boolean
error_code
required

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.

string | null
error_message
required

The code’s meaning, in English; the app shows the merchant the full reason in their language.

string | null
vendor_message
required

The courier’s own words when it answered (vendor_rejected), as it sent them, in its language: for display only, never to parse.

string | null
delivery_method
required

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.

string
pickup_point
required

The point it is delivered to, for a pickup_point delivery; null otherwise.

object
external_id
required

The point’s id in the courier’s ids.

string | null
total_weight_kg
required
string | null
parcels
required

Every parcel of the shipment, in order (as many as the courier was asked for).

Array<object>
object
kind
required

Parcel, envelope or pallet. New values may appear: treat one you do not know as such.

string
weight_kg
required
string | null
length_cm
required
string | null
width_cm
required
string | null
height_cm
required
string | null
tracking_number
required

The parcel’s own tracking number, where the courier issues one per parcel.

string | null
cod
required

Cash on delivery the courier collects from the recipient; null without.

object
amount
required
string
currency
required
string
declared_value
required

The declared (insured) value; null when none was declared.

object
amount
required
string
currency
required
string
sender
required

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
name
required
string | null
first_name
required
string | null
last_name
required
string | null
company
required
string | null
email
required
string | null
phone
required
string | null
address_line_1
required
string | null
address_line_2
required
string | null
city
required
string | null
region
required
string | null
region_code
required
string | null
postal_code
required
string | null
country_code
required
string | null
locality_code
required
string | null
contact_person
required
string | null
recipient
required
object
name
required
string | null
first_name
required
string | null
last_name
required
string | null
company
required
string | null
email
required
string | null
phone
required
string | null
address_line_1
required
string | null
address_line_2
required
string | null
city
required
string | null
region
required
string | null
region_code
required
string | null
postal_code
required
string | null
country_code
required
string | null
locality_code
required
string | null
contact_person
required
string | null
cancellation
required

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
kind
required

New values may appear: treat one you do not know as such.

string
cancelled_at
required
string | null format: date-time
tracking_events
required

The courier’s latest tracking events, at most 20, newest last.

Array<object>
object
status
required

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.

string | null
description
required

The event as the courier worded it, untranslated.

string | null
location
required

Where it happened, as the courier reported it.

string | null
occurred_at
required
string format: date-time
picked_up_at
required
string | null format: date-time
delivered_at
required
string | null format: date-time
returned_at
required
string | null format: date-time
created_at
required

When the AWB was asked for.

string format: date-time
updated_at
required
string format: date-time

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"
}
X-RateLimit-Limit
integer

Requests allowed per minute (per caller; before authentication, failed attempts per address).

X-RateLimit-Remaining
integer

Requests left in the current minute.

Idempotent-Replayed
string
Allowed values: true

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).

Media typeapplication/problem+json
Problem
object
type
required

The documentation URL of the code.

string format: uri
title
required

A short summary of the error, in English.

string
status
required

The HTTP status, repeated.

integer
code
required

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.

string
detail

The explanation for this case, in English.

string
errors

Validation only: the messages per field.

object
key
additional properties
Array<string>

Example generated

{
"type": "https://example.com",
"title": "example",
"status": 1,
"code": "example",
"detail": "example",
"errors": {
"additionalProperty": [
"example"
]
}
}
X-RateLimit-Limit
integer

Requests allowed per minute (per caller; before authentication, failed attempts per address).

X-RateLimit-Remaining
integer

Requests left in the current minute.

No valid access token.

Media typeapplication/problem+json
Problem
object
type
required

The documentation URL of the code.

string format: uri
title
required

A short summary of the error, in English.

string
status
required

The HTTP status, repeated.

integer
code
required

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.

string
detail

The explanation for this case, in English.

string
errors

Validation only: the messages per field.

object
key
additional properties
Array<string>

Example generated

{
"type": "https://example.com",
"title": "example",
"status": 1,
"code": "example",
"detail": "example",
"errors": {
"additionalProperty": [
"example"
]
}
}
X-RateLimit-Limit
integer

Requests allowed per minute (per caller; before authentication, failed attempts per address).

X-RateLimit-Remaining
integer

Requests left in the current minute.

WWW-Authenticate
string

Bearer: send an access token as a Bearer token.

The app was not granted the scope (insufficient_scope).

Media typeapplication/problem+json
Problem
object
type
required

The documentation URL of the code.

string format: uri
title
required

A short summary of the error, in English.

string
status
required

The HTTP status, repeated.

integer
code
required

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.

string
detail

The explanation for this case, in English.

string
errors

Validation only: the messages per field.

object
key
additional properties
Array<string>

Example generated

{
"type": "https://example.com",
"title": "example",
"status": 1,
"code": "example",
"detail": "example",
"errors": {
"additionalProperty": [
"example"
]
}
}
X-RateLimit-Limit
integer

Requests allowed per minute (per caller; before authentication, failed attempts per address).

X-RateLimit-Remaining
integer

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.

Media typeapplication/problem+json
Problem
object
type
required

The documentation URL of the code.

string format: uri
title
required

A short summary of the error, in English.

string
status
required

The HTTP status, repeated.

integer
code
required

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.

string
detail

The explanation for this case, in English.

string
errors

Validation only: the messages per field.

object
key
additional properties
Array<string>

Example generated

{
"type": "https://example.com",
"title": "example",
"status": 1,
"code": "example",
"detail": "example",
"errors": {
"additionalProperty": [
"example"
]
}
}
X-RateLimit-Limit
integer

Requests allowed per minute (per caller; before authentication, failed attempts per address).

X-RateLimit-Remaining
integer

Requests left in the current minute.

Idempotent-Replayed
string
Allowed values: true

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).

Media typeapplication/problem+json
Problem
object
type
required

The documentation URL of the code.

string format: uri
title
required

A short summary of the error, in English.

string
status
required

The HTTP status, repeated.

integer
code
required

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.

string
detail

The explanation for this case, in English.

string
errors

Validation only: the messages per field.

object
key
additional properties
Array<string>

Example generated

{
"type": "https://example.com",
"title": "example",
"status": 1,
"code": "example",
"detail": "example",
"errors": {
"additionalProperty": [
"example"
]
}
}
X-RateLimit-Limit
integer

Requests allowed per minute (per caller; before authentication, failed attempts per address).

X-RateLimit-Remaining
integer

Requests left in the current minute.

Idempotent-Replayed
string
Allowed values: true

true when this is the stored answer of an earlier request with the same Idempotency-Key.

Too many requests: retry after Retry-After seconds.

Media typeapplication/problem+json
Problem
object
type
required

The documentation URL of the code.

string format: uri
title
required

A short summary of the error, in English.

string
status
required

The HTTP status, repeated.

integer
code
required

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.

string
detail

The explanation for this case, in English.

string
errors

Validation only: the messages per field.

object
key
additional properties
Array<string>

Example generated

{
"type": "https://example.com",
"title": "example",
"status": 1,
"code": "example",
"detail": "example",
"errors": {
"additionalProperty": [
"example"
]
}
}
X-RateLimit-Limit
integer

Requests allowed per minute (per caller; before authentication, failed attempts per address).

X-RateLimit-Remaining
integer

Requests left in the current minute.

Retry-After
integer

Seconds to wait before retrying.