> ## Documentation Index
> Fetch the complete documentation index at: https://sendcloud.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Create or update a list of shipments
> Insert shipments (or 'orders') into an API integration from your shop system, and have them appear in your Sendcloud account.
**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](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-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](/api/v2/parcels/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.
## OpenAPI
````yaml /.openapi/v2/integrations/openapi.yaml post /integrations/{id}/shipments
openapi: 3.1.0
info:
title: Integrations
contact:
name: Sendcloud API Support
email: contact@sendcloud.com
url: https://www.sendcloud.dev
version: 2.0.0
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
description: >-
The Integrations API allows you to retrieve, update and add orders to custom
webshop integrations.
servers:
- url: https://panel.sendcloud.sc/api/v2
description: Sendcloud Production
security: []
tags:
- name: Integrations
- name: Shipments
paths:
/integrations/{id}/shipments:
parameters:
- name: id
in: path
required: true
schema:
type: integer
description: The id of the integration to which the shipments belong
post:
tags:
- Shipments
summary: Create or update a list of shipments
description: >-
Insert shipments (or 'orders') into an API integration from your shop
system, and have them appear in your Sendcloud account.
operationId: sc-public-v2-orders-post-create_a_list_of_shipments
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ShipmentBlobOrderCreate'
examples:
CreateUpdateShipments:
summary: Create or update a list of shipments
value:
- address: Lansdown Glade
address_2: string
city: Oss
company_name: string
country: AW
created_at: '2019-08-24T14:15:22Z'
currency: EUR
customs_invoice_nr: '120'
customs_shipment_type: 0
email: user@example.com
external_order_id: '555413'
external_shipment_id: '777413'
house_number: '15'
name: John Doe
order_number: OXSDFGHTD-12
order_status:
id: fulfilled
message: Fulfilled
parcel_items:
- description: Very orange color
hs_code: '01013000'
origin_country: AW
product_id: '1458734634'
properties:
size: small
colour: red
quantity: 2
sku: WW-DR-GR-XS-001
value: '3.5'
weight: '1'
mid_code: NLOZR92MEL
material_content: 100% Cotton
intended_use: Personal use
payment_status:
id: paid
message: Paid
postal_code: '5341'
shipping_method: 12345
shipping_method_checkout_name: string
telephone: string
to_post_number: string
to_service_point: 0
to_state: string
total_order_value: string
updated_at: '2019-08-24T14:15:22Z'
weight: string
checkout_payload:
sender_address_id: 0
shipping_product:
code: postnl:standard
name: PostNL Standard
selected_functionalities:
age_check: 18
last_mile: home_delivery
first_mile: pickup_dropoff
multicollo: true
form_factor: parcel
service_area: domestic
weekend_delivery: saturday
delivery_deadline: best_effort
direct_contract_only: false
delivery_method_type: string
delivery_method_data:
delivery_date: '2019-08-24T14:15:22Z'
formatted_delivery_date: string
parcel_handover_date: '2019-08-24T14:15:22Z'
width: string
height: string
length: string
customs_details:
discount_granted: '3.99'
insurance_costs: '9.99'
freight_costs: '5.99'
other_costs: '2.99'
tax_numbers:
sender:
- tax_number:
name: VAT
country: NL
value: NL987654321B02
receiver:
- tax_number:
name: VAT
country: DE
value: DE123456789B03
importer_of_records:
- tax_number:
name: VAT
country: NL
value: NL975318642B01
description: ''
responses:
'200':
description: >-
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.
content:
application/json:
schema:
type: array
items:
oneOf:
- $ref: '#/components/schemas/ShipmentCreateUpdateLog'
- $ref: '#/components/schemas/ShipmentErrorLog'
examples:
CreateUpdateShipments:
summary: Create or update a list of shipments
value:
- external_order_id: '1175584'
external_shipment_id: '777413'
shipment_uuid: 6b436cb2-65a4-482c-9d25-38be7868ff00
status: created
- error:
checkout_payload:
delivery_method_data:
delivery_date:
- This field is required.
external_order_id: '1184635'
external_shipment_id: ''
status: error
'400':
description: Bad Request
'404':
$ref: '#/components/responses/404-Shipments'
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
components:
schemas:
ShipmentBlobOrderCreate:
title: Shipment Blob Order Create Object
type: object
properties:
address:
title: Address
type: string
minLength: 1
address_2:
title: Address 2
type: string
minLength: 0
city:
title: City
type: string
minLength: 1
company_name:
title: Company name
type: string
minLength: 0
country:
$ref: '#/components/schemas/country-codes'
created_at:
type: string
title: Created at
format: date-time
description: >-
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:
type:
- string
- 'null'
title: Currency
minLength: 1
description: ISO 4217 currency code
enum:
- EUR
- USD
- GBP
customs_invoice_nr:
type: string
title: Customs invoice nr
minLength: 0
description: Your own commercial invoice number
example: '120'
customs_shipment_type:
type:
- integer
- 'null'
title: Customs shipment type
enum:
- 0
- 1
- 2
- 3
- 4
description: |
Type of shipment for customs purposes:
- `0` - Gift
- `1` - Documents
- `2` - Commercial Goods
- `3` - Commercial Sample
- `4` - Returned Goods
minimum: 0
maximum: 4
email:
title: Customer email address
type: string
format: email
minLength: 0
external_order_id:
title: External order id
type: string
minLength: 1
description: External order ID assigned by the shop system
external_shipment_id:
title: External shipment id
type:
- string
- 'null'
minLength: 1
description: External shipment ID assigned by the shop system
house_number:
title: House number
type: string
minLength: 0
name:
title: Name
type: string
minLength: 1
order_number:
title: Order number
type: string
minLength: 1
description: Unique order number generated manualy or by the shop system
order_status:
$ref: '#/components/schemas/ShipmentBlobStatus'
parcel_items:
type:
- array
- 'null'
description: List of items the parcel contains
items:
$ref: '#/components/schemas/ParcelItems'
payment_status:
$ref: '#/components/schemas/ShipmentBlobStatus'
postal_code:
title: Postal code
type: string
minLength: 1
shipping_method:
type:
- integer
- 'null'
title: Shipping method
description: Foreign key indicating shipping method used
example: 1234
shipping_method_checkout_name:
title: Shipping method checkout name
type: string
minLength: 0
maxLength: 100
description: Human readable shipping method name
telephone:
title: Telephone
type: string
minLength: 0
to_post_number:
title: To post number
type: string
minLength: 0
to_service_point:
title: To service point
type:
- integer
- 'null'
to_state:
title: To state
type:
- string
- 'null'
minLength: 1
total_order_value:
title: Total order value
type:
- string
- 'null'
format: decimal
description: The total price of an order
updated_at:
type: string
title: Updated at
format: date-time
description: >-
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'
weight:
type:
- string
- 'null'
title: Weight
format: decimal
description: Total weight of the order. Cannot be smaler than 0.001
example: '10.2'
maxLength: 10
checkout_payload:
$ref: '#/components/schemas/CheckoutPayload'
width:
type:
- string
- 'null'
title: Width
description: Volumetric weight width
format: decimal
maxLength: 10
example: '10.2'
height:
type:
- string
- 'null'
title: Height
description: Volumetric weight height
format: decimal
maxLength: 10
example: '10.2'
length:
type:
- string
- 'null'
title: Length
description: Volumetric weight length
format: decimal
maxLength: 10
example: '10.2'
customs_details:
$ref: '#/components/schemas/CustomsInformation'
required:
- address
- address_2
- city
- company_name
- country
- created_at
- currency
- customs_invoice_nr
- customs_shipment_type
- email
- external_order_id
- external_shipment_id
- house_number
- name
- order_number
- order_status
- parcel_items
- payment_status
- postal_code
- shipping_method_checkout_name
- telephone
- to_post_number
- to_service_point
- to_state
- updated_at
ShipmentCreateUpdateLog:
title: Shipment Creation or Update information log
type: object
properties:
external_order_id:
title: External Order ID
type: string
minLength: 1
external_shipment_id:
title: External Shipment ID
type: string
minLength: 1
shipment_uuid:
title: Shipment UUID
type: string
format: uuid
minLength: 1
status:
title: Status
type: string
enum:
- created
- updated
ShipmentErrorLog:
title: Shipment create/update error log
type: object
properties:
error:
title: Error(s)
type: object
external_order_id:
title: External Order ID
type: string
external_shipment_id:
title: External Shipment ID
type: string
status:
title: Status
type: string
enum:
- error
country-codes:
type: string
title: Country Code Object
enum:
- 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
description: A country represented by its ISO 3166-1 alpha-2 code
example: NL
ShipmentBlobStatus:
title: Shipment Blob Status Object
type:
- object
- 'null'
properties:
id:
title: Id
type: string
minLength: 1
description: Custom internal shop status, can be used for filtering
message:
title: Message
type: string
minLength: 1
description: User-defined human readable status
required:
- id
- message
ParcelItems:
title: Parcel Items Object
type: object
properties:
description:
type: string
title: Description
minLength: 1
description: Description of the type of product
example: Bag
hs_code:
description: Harmonized System Code
type: string
title: HS code
example: '01013000'
maxLength: 12
origin_country:
type:
- string
- 'null'
title: Origin country
enum:
- 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
description: >-
Country code from where the products were originally produced (ISO
3166-1 alpha-2)
minLength: 2
maxLength: 2
product_id:
type: string
title: Product id
description: Internal ID of the product
example: '1458734634'
properties:
title: Properties
type: object
additionalProperties:
type:
- string
- 'null'
description: >-
An object containing any additional properties of the product, e.g.
`color: Black`
quantity:
type: integer
title: Quantity
minimum: 1
description: Number of units of a given item
example: 2
sku:
type: string
title: Sku
description: >-
Internal stock keeping unit, used by retailers to assign to
products, in order to keep track of stock levels internally.
example: WW-DR-GR-XS-001
value:
title: Value
type: string
format: decimal
description: Price of an item
weight:
title: Weight
type:
- string
- 'null'
format: decimal
description: Weight of an item
mid_code:
title: MID Code
type:
- string
- 'null'
description: >-
MID code is short for Manufacturer's Identification code and must be
shown on the commercial invoice. It's used as an alternative to the
full name and address of a manufacturer, shipper or exporter and is
always required for U.S. formal customs entries.
example: NLOZR92MEL
material_content:
title: Material Content
type:
- string
- 'null'
description: A description of materials of the order content.
example: 100% Cotton
intended_use:
title: Intended Use
type:
- string
- 'null'
description: >-
Intended use of the order contents. The intended use may be personal
or commercial.
example: Personal use
required:
- description
- quantity
- value
CheckoutPayload:
title: Checkout Payload Object
type: object
properties:
sender_address_id:
title: >-
The [sender address unique
identifier](../sender-addresses/openapi.yaml) associated with the
order
type: integer
description: The sender_address_id associated with the order
shipping_product:
title: Shipping product
type: object
description: >-
The shipping product with the associated functionalities of the
order. See example payload. The `code`, `name` and
`selected_functionalities` fields are **all required**. This data
follows from the chosen `delivery_method` (by the end-consumer).
delivery_method_type:
title: Delivery method type
type: string
minLength: 1
description: >-
The type of the delivery method. Needs to be either
`standard_delivery`, `nominated_day_delivery` or
`same_day_delivery`.
delivery_method_data:
type: object
properties:
delivery_date:
title: Delivery date
type: string
format: date-time
description: The delivery date required by the end-consumer
formatted_delivery_date:
type: string
title: Formatted delivery date
minLength: 1
example: February 21, 2012
parcel_handover_date:
title: Parcel handover date
type: string
format: date-time
description: Date at which the parcel needs to be handed over to the carrier
required:
- delivery_date
- formatted_delivery_date
- parcel_handover_date
required:
- sender_address_id
- shipping_product
- delivery_method_type
CustomsInformation:
type:
- object
- 'null'
title: Customs Information
description: Customs information related to this shipment
properties:
discount_granted:
$ref: '#/components/schemas/CostsObject'
type:
- object
- 'null'
title: Discount Granted
description: Discount granted on the total order
insurance_costs:
$ref: '#/components/schemas/CostsObject'
type:
- object
- 'null'
title: Insurance Cost
description: Amount the order is insured for
freight_costs:
$ref: '#/components/schemas/CostsObject'
type:
- object
- 'null'
title: Freight Cost
description: Shipping cost of the order
other_costs:
$ref: '#/components/schemas/CostsObject'
type:
- object
- 'null'
title: Other Costs
description: Any other costs (for eg, wrapping costs) associated with the order
tax_numbers:
type:
- object
- 'null'
title: Tax information about sender, receiver, and importer of records
properties:
sender:
type: array
title: Sender's Tax Information
minItems: 0
items:
$ref: '#/components/schemas/TaxNumber'
receiver:
type: array
title: Receiver's Tax Information
minItems: 0
items:
$ref: '#/components/schemas/TaxNumber'
importer_of_records:
type: array
title: Receiver's Tax Information
minItems: 0
items:
$ref: '#/components/schemas/TaxNumber'
CostsObject:
properties:
value:
type:
- string
- 'null'
pattern: '[\d]+(\.[\d]+)?'
example: '3.99'
currency:
type:
- string
- 'null'
example: EUR
TaxNumber:
type: object
title: Tax Number
properties:
name:
type:
- string
- 'null'
title: Tax ID name
example: VAT
country_code:
type:
- string
- 'null'
title: The country code of the country in the address
example: NL
value:
type:
- string
- 'null'
title: The value of the Tax ID
example: NL987654321B02
responses:
404-Shipments:
description: Example response
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: integer
description: HTTP response status code
example: 404
request:
type: string
description: Endpoint which returned the response
message:
type: string
description: Human readable error message
required:
- code
- request
- message
examples:
ShipmentNotFound:
summary: Shipment not found
value:
error:
code: 404
request: api/v2/integrations/1/shipments/
message: No ShipmentBlob matches the given query.
IntegrationNotFound:
summary: Integration not found
value:
error:
code: 404
request: api/v2/integrations/1/shipments/
message: No Integration matches the given query.
securitySchemes:
HTTPBasicAuth:
type: http
description: >-
Basic Authentication using API key and secrets is currently the main
authentication mechanism.
scheme: basic
OAuth2ClientCreds:
type: oauth2
description: >-
OAuth2 is a standardized protocol for authorization that allows users to
share their private resources stored on one site with another site
without having to provide their credentials. OAuth2 Client Credentials
Grant workflow. This workflow is typically used for server-to-server
interactions that require authorization to access specific resources.
flows:
clientCredentials:
tokenUrl: https://account.sendcloud.com/oauth2/token/
scopes:
api: Default OAuth scope required to access Sendcloud API.
````