Skip to main content
POST
Create or update a list of shipments
API v2 is entering maintenance mode. New users should start with API v3 to access our latest features and improved performance. Already using v2? Don’t worry, your current integration remains fully functional. Read more about maintenance mode, or check out the migration guide for API v3.
This endpoint is only available for official Sendcloud partners.
This endpoint allows you to insert shipments (or ‘orders’) into an API integration from your shop system, and have them appear in your Sendcloud account. Imported orders will appear in the Sendcloud platform under the Incoming order overview with the status “Ready to process”. This allows you to easily generate parcels and create shipping labels via the API or directly from the Sendcloud platform. The validation for this endpoint is more relaxed, therefore we recommend this method over the Create a parcel or parcels endpoint for third-party integrators. This is an UPSERT endpoint which attempts to be idempotent given specific fields to ensure that orders are not duplicated. If there’s an existing match in our database for specific fields (external_order_id and external_shipment_id), then the shipment will be updated. The system will only update orders that have had their updated_at (ISO 8601 DateTime) timestamp changed. The external_shipment_id field is used to split orders across multiple shipments, however, this field is not supported by all shop systems. If your shop system supports the distribution of product items within an order across multiple shipments, you can use the shipment data to create multiple entries. If your shop does not support this feature, you can set the external_shipment_id value to null. Batches are limited to 100 orders at once. This endpoint should accept most values in any of the available fields, but in the case of erroneous data, an error message will be returned directly. Your requests should almost always succeed unless the field structure is not correct.

Authorizations

​
Authorization
string
header
required

Basic Authentication using API key and secrets is currently the main authentication mechanism.

Path Parameters

​
id
integer
required

The id of the integration to which the shipments belong

Body

application/json
​
address
string
required
Minimum string length: 1
​
address_2
string
required
​
city
string
required
Minimum string length: 1
​
company_name
string
required
​
country
enum<string>
required

A country represented by its ISO 3166-1 alpha-2 code

Available options:
AW,
AF,
AO,
AI,
AX,
AL,
AD,
AE,
AR,
AM,
AS,
AQ,
TF,
AG,
AU,
AT,
AZ,
BI,
BE,
BJ,
BQ,
BF,
BD,
BG,
BH,
BS,
BA,
BL,
BY,
BZ,
BM,
BO,
BR,
BB,
BN,
BT,
BV,
BW,
CF,
CA,
CC,
CH,
CL,
CN,
CI,
CM,
CD,
CG,
CK,
CO,
KM,
CV,
CR,
CU,
CW,
CX,
KY,
CY,
CZ,
DE,
DJ,
DM,
DK,
DO,
DZ,
EC,
EG,
ER,
EH,
ES,
EE,
ET,
FI,
FJ,
FK,
FR,
FO,
FM,
GA,
GB,
GE,
GG,
GH,
GI,
GN,
GP,
GM,
GW,
GQ,
GR,
GD,
GL,
GT,
GF,
GU,
GY,
HK,
HM,
HN,
HR,
HT,
HU,
ID,
IM,
IN,
IO,
IE,
IR,
IQ,
IS,
IL,
IT,
JM,
JE,
JO,
JP,
KZ,
KE,
KG,
KH,
KI,
KN,
KR,
KW,
LA,
LB,
LR,
LY,
LC,
LI,
LK,
LS,
LT,
LU,
LV,
MO,
MF,
MA,
MC,
MD,
MG,
MV,
MX,
MH,
MK,
ML,
MT,
MM,
ME,
MN,
MP,
MZ,
MR,
MS,
MQ,
MU,
MW,
MY,
YT,
NA,
NC,
NE,
NF,
NG,
NI,
NU,
NL,
NO,
NP,
NR,
NZ,
OM,
PK,
PA,
PN,
PE,
PH,
PW,
PG,
PL,
PR,
KP,
PT,
PY,
PS,
PF,
QA,
RE,
RO,
RU,
RW,
SA,
SD,
SN,
SG,
GS,
SH,
SJ,
SB,
SL,
SV,
SM,
SO,
PM,
RS,
SS,
ST,
SR,
SK,
SI,
SE,
SZ,
SX,
SC,
SY,
TC,
TD,
TG,
TH,
TJ,
TK,
TM,
TL,
TO,
TT,
TN,
TR,
TV,
TW,
TZ,
UG,
UA,
UM,
UY,
US,
UZ,
VA,
VC,
VE,
VG,
VI,
VN,
VU,
WF,
WS,
YE,
ZA,
ZM,
ZW,
IC,
XK
Example:

"NL"

​
created_at
string<date-time>
required

Timestamp indicating when the shipment was created in the shop system. This value will be saved and accessible through shipment_created_at field in GET response.

Example:

"2022-05-07T15:08:12.152000Z"

​
currency
enum<string> | null
required

ISO 4217 currency code

Available options:
EUR,
USD,
GBP
Minimum string length: 1
​
customs_invoice_nr
string
required

Your own commercial invoice number

Example:

"120"

​
customs_shipment_type
enum<integer> | null
required

Type of shipment for customs purposes:

  • 0 - Gift
  • 1 - Documents
  • 2 - Commercial Goods
  • 3 - Commercial Sample
  • 4 - Returned Goods
Available options:
0,
1,
2,
3,
4
Required range: 0 <= x <= 4
​
email
string<email>
required
​
external_order_id
string
required

External order ID assigned by the shop system

Minimum string length: 1
​
external_shipment_id
string | null
required

External shipment ID assigned by the shop system

Minimum string length: 1
​
house_number
string
required
​
name
string
required
Minimum string length: 1
​
order_number
string
required

Unique order number generated manualy or by the shop system

Minimum string length: 1
​
order_status
Shipment Blob Status Object · object | null
required
​
parcel_items
Parcel Items Object · object[] | null
required

List of items the parcel contains

​
payment_status
Shipment Blob Status Object · object | null
required
​
postal_code
string
required
Minimum string length: 1
​
shipping_method_checkout_name
string
required

Human readable shipping method name

Maximum string length: 100
​
telephone
string
required
​
to_post_number
string
required
​
to_service_point
integer | null
required
​
to_state
string | null
required
Minimum string length: 1
​
updated_at
string<date-time>
required

Timestamp indicating when the shipment was updated in the shop system. This value will be saved and accessible through shipment_updated_at field in GET response.

Example:

"2022-05-07T15:08:12.152000Z"

​
shipping_method
integer | null

Foreign key indicating shipping method used

Example:

1234

​
total_order_value
string<decimal> | null

The total price of an order

​
weight
string<decimal> | null

Total weight of the order. Cannot be smaler than 0.001

Maximum string length: 10
Example:

"10.2"

​
checkout_payload
Checkout Payload Object · object
​
width
string<decimal> | null

Volumetric weight width

Maximum string length: 10
Example:

"10.2"

​
height
string<decimal> | null

Volumetric weight height

Maximum string length: 10
Example:

"10.2"

​
length
string<decimal> | null

Volumetric weight length

Maximum string length: 10
Example:

"10.2"

​
customs_details
Customs Information · object | null

Customs information related to this shipment

Response

List with references to created shipments, or the errors that occurred while creating the shipment. When a shipment can't be created, the response will contain an entry for the object with the errors. This object will have a path to each field containing errors, listing the error(s) it contains.

​
external_order_id
string
Minimum string length: 1
​
external_shipment_id
string
Minimum string length: 1
​
shipment_uuid
string<uuid>
Minimum string length: 1
​
status
enum<string>
Available options:
created,
updated