Sendcloud Parcels API v2
Legacy v2 Parcels surface for announcing shipments and retrieving parcel state. Superseded by the v3 Shipments API; documented for migration paths.
OpenAPI Specification
openapi: 3.1.0
info:
title: Parcels
version: 2.0.0
description: >
At the core of the Sendcloud Shipping API is the Parcels resource. Parcels
are data objects which can be announced, and have a shipping method and
shipping label assigned to them. You can also think of parcels as
**shipments**.
You can use this resource to perform a number of activities:
* Create a parcel and immediately announce it
* Create a parcel and choose not to announce it (no shipping label is
created)
* Update the details, or create a label, for an unannounced parcel
* Cancel an announced parcel
<!-- theme: info -->
> International parcels require more information than domestic parcels.
Certain customs documents must be created when shipping to countries outside
the EU. For Sendcloud to successfully generate these documents, all the
necessary information must be available in your parcel request. Read more
in-depth information on [international shipping and its
requirements](/docs/shipping/international-shipping/).
contact:
name: Sendcloud API Support
url: https://www.sendcloud.dev
email: [email protected]
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://panel.sendcloud.sc/api/v2
description: Sendcloud Production
tags:
- name: Parcels
paths:
/parcels:
get:
summary: Retrieve parcels
x-sendcloud-paginated: true
x-sendcloud-paginated-discriminator: parcels
x-mint:
href: /api/v2/parcels/retrieve-parcels
content: |-
<Warning>
**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).
</Warning>
tags:
- Parcels
responses:
'200':
description: OK
content:
application/json:
schema:
description: Retrieve parcels
type: object
properties:
next:
type: integer
nullable: true
previous:
type: integer
nullable: true
parcels:
type: array
uniqueItems: true
minItems: 1
items:
$ref: '#/components/schemas/ParcelResponseShort'
required:
- parcels
examples:
RetrieveParcels:
summary: Retrieve parcels
value:
next: null
previous: null
parcels:
- id: 3172
name: John Doe
company_name: Sendcloud
contract: 1
address: Stadhuisplein 10
address_divided:
street: Stadhuisplein
house_number: '10'
city: Eindhoven
postal_code: 5611 EM
telephone: '0612345678'
email: [email protected]
date_created: 01-01-2018 21:45:30
date_updated: 01-01-2018 21:47:12
date_announced: 01-01-2018 21:47:13
tracking_number: S0M3TR4Ck1NgNumB3r
customs_declaration: {}
weight: '2.000'
label:
normal_printer:
- >-
https://panel.sendcloud.sc/api/v2/label/normal_printer/3172?start_from=0&hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4
- >-
https://panel.sendcloud.sc/api/v2/label/normal_printer/3172?start_from=1&hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4
- >-
https://panel.sendcloud.sc/api/v2/label/normal_printer/3172?start_from=2&hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4
- >-
https://panel.sendcloud.sc/api/v2/label/normal_printer/3172?start_from=3&hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4
label_printer: >-
https://panel.sendcloud.sc/api/v2/label/label_printer/3172?hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4
status:
id: 0
message: Ready to send
data: {}
country:
iso_3: NLD
iso_2: NL
name: Netherlands
shipment:
id: 1
name: PostNL Standard 0-23kg
carrier:
code: postnl
colli_uuid: ab3ecb5e-61b6-42b1-8034-7c6befdeaa63
collo_nr: 0
collo_count: 1
reference: some_reference_123
RetrieveParcelsVerbose:
summary: >-
Get all parcels when `errors` query param is
`verbose-carrier`
value:
next: null
previous: null
parcels:
- id: 3172
name: John Doe
company_name: Sendcloud
contract: 1
address: Stadhuisplein 10
address_divided:
street: Stadhuisplein
house_number: '10'
city: Eindhoven
postal_code: 5611 EM
telephone: '0612345678'
email: [email protected]
date_created: 01-01-2018 21:45:30
date_updated: 01-01-2018 21:47:12
date_announced: 01-01-2018 21:47:13
tracking_number: S0M3TR4Ck1NgNumB3r
customs_declaration: {}
weight: '2.000'
label:
normal_printer:
- >-
https://panel.sendcloud.sc/api/v2/label/normal_printer/3172?start_from=0&hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4
- >-
https://panel.sendcloud.sc/api/v2/label/normal_printer/3172?start_from=1&hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4
- >-
https://panel.sendcloud.sc/api/v2/label/normal_printer/3172?start_from=2&hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4
- >-
https://panel.sendcloud.sc/api/v2/label/normal_printer/3172?start_from=3&hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4
label_printer: >-
https://panel.sendcloud.sc/api/v2/label/label_printer/3172?hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4
status:
id: 0
message: Ready to send
data: {}
country:
iso_3: NLD
iso_2: NL
name: Netherlands
shipment:
id: 1
name: PostNL Standard 0-23kg
carrier:
code: postnl
colli_uuid: ab3ecb5e-61b6-42b1-8034-7c6befdeaa63
collo_nr: 0
collo_count: 1
reference: some_reference_123
errors:
non_field_errors:
- >-
PostNL service error: The domain for email address
[email protected] seems to be invalid.
'404':
description: Not Found
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: integer
request:
type: string
message:
type: string
examples:
InvalidCursor:
summary: Invalid cursor
value:
error:
code: 404
request: api/v2/parcels
message: Invalid cursor
operationId: sc-public-v2-scp-get-all_parcels
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
description: >-
This endpoint allows you to retrieve a list of all the parcels which you
have created or imported into your Sendcloud account under your API
credentials. You can filter the results based on the query parameters
provided below, in order to retrieve a specific parcel or list of
parcels which match the defined criteria.
parameters:
- in: query
name: parcel_status
description: >-
Returns parcels that have the requested status. For a list of
possible statuses, see the [Retrieve a list of parcel
statuses](/api/v2/parcel-statuses/retrieve-a-list-of-parcel-statuses)
endpoint.
schema:
type: integer
- schema:
type: string
in: query
name: tracking_number
description: Returns parcels that match a specified tracking number
- schema:
type: string
in: query
name: external_reference
description: Returns parcels that match a specified external reference
- schema:
type: string
in: query
name: order_number
description: >-
Returns an order that matches a specific `order_number` property
from your parcels
- schema:
type: string
example: '2018-02-26T11:01:47.505309+00:00'
in: query
name: updated_after
description: >-
Returns all orders which have been updated in our system after a
given time. You can use the value of ISO 8601 DateTime string like
this
- schema:
type: string
example: '2018-02-26T11:01:47.505309+00:00'
in: query
name: announced_after
description: >-
Returns all orders which have been announced to the carrier after
the given time. You can use the value of ISO 8601 DateTime string
like this
- schema:
type: string
in: query
name: ids
description: >-
Filter results using a list of Parcel IDs. This is a comma separated
list of IDs, it may not contain more then 100 IDs.
- schema:
type: string
in: query
name: cursor
description: >-
Next and previous token that is used to paginate. The token is
included in the response.
- schema:
type: string
enum:
- verbose-carrier
in: query
name: errors
description: >-
If you are using this API for development purposes, you might want
to use the errors query string in the URL. This allows you to
visualize errors from the carrier.
post:
summary: Create a parcel or parcels
tags:
- Parcels
operationId: sc-public-v2-scp-post-create_parcel
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
x-mint:
href: /api/v2/parcels/create-a-parcel-or-parcels
content: >-
<Danger>
**This endpoint is now in maintenance mode and is closed to new users.**
- If your Sendcloud account was created before April 13th 2026, you can continue to use this endpoint as normal.
- New users should start with API v3 to access our latest features and improved
performance.
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).
</Danger>
This endpoint **creates a parcel** under your API credentials.
- You can choose to **announce the parcel** and create the shipping
label at the same time as you create the parcel by providing the
parameter `request_label: true`.
- When `request_label` is `false`, the parcel will be created, but not
announced.
- You can then request the shipping label at a later date by changing
the `request_label` parameter via the [Update a
parcel](/api/v2/parcels/update-a-parcel) endpoint.
<Warning>
Make sure you use the correct `sender_address` if you wish to ship this parcel from a location **other than** your **default** sender address. You can find the `sender_address` for each of the addresses you've saved in your Sendcloud account via the [Retrieve a sender address](/api/v2/sender-addresses/get-a-sender-address) endpoint.
</Warning>
<Warning>
Also keep in mind that the `sender_address` id will not be saved/reflected in the created order (Incoming Orders view / Pack & Go) if `request_label` is `false`.
</Warning>
## International parcel creation
If you want to create a parcel to ship to a destination country
outside the EU, it's mandatory to include additional information
related to the parcel contents. This allows Sendcloud to automatically
generate the required customs documentation based on the international
shipping method selected. After the shipping label and associated
documents are generated, you can retrieve and download them via the
[Retrieve parcel
documents](/api/v2/parcel-documents/retrieve-parcel-documents)
endpoint.
<Warning>
If you have more than one active contracts for a specific carrier, you must fill the `contract` field with your desired contract ID in your request. You can get your contract ID from the [Retrieve a list of contracts](/api/v2/contracts/retrieve-a-list-of-contracts) endpoint.
</Warning>
<Info>
International parcels require more information than domestic parcels. Certain customs documents must be created when shipping to countries outside the EU. For Sendcloud to successfully generate these documents, all the necessary information must be available in your parcel request. You can read more in-depth information on international shipping and its requirements in [our developer guides](/docs/shipping/international-shipping/).
</Info>
## Multicollo
More information on how to create multiple parcels within one shipment
can be found in the [Multicollo page](/docs/shipping/multicollo/) of
our developer guides.
responses:
'200':
description: OK
content:
application/json:
schema:
description: Create a parcel
oneOf:
- type: object
title: Failed to create parcels response
properties:
failed_parcels:
type: array
uniqueItems: true
items:
properties:
parcel:
$ref: '#/components/schemas/ParcelResponseFull'
errors:
type: object
type: object
- type: object
title: Single parcel created response
properties:
parcel:
$ref: '#/components/schemas/ParcelResponseFull'
- type: object
title: Batch of parcels created response
properties:
parcels:
type: array
uniqueItems: true
items:
$ref: '#/components/schemas/ParcelResponseFull'
examples:
CreateParcel:
summary: Parcel created
value:
parcel:
id: 3
name: John Doe
company_name: Sendcloud
contract: 1
address: Stadhuisplein 10
address_divided:
street: Stadhuisplein
house_number: '10'
city: Eindhoven
postal_code: 5611 EM
telephone: '0612345678'
email: ''
date_created: 01-01-2018 21:45:30
date_updated: 01-01-2018 21:47:12
date_announced: 01-01-2018 21:47:13
tracking_number: S0M3TR4Ck1NgNumB3r
weight: '2.000'
label:
normal_printer:
- >-
https://panel.sendcloud.sc/api/v2/label/normal_printer/3172?start_from=0&hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4
- >-
https://panel.sendcloud.sc/api/v2/label/normal_printer/3172?start_from=1&hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4
- >-
https://panel.sendcloud.sc/api/v2/label/normal_printer/3172?start_from=2&hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4
- >-
https://panel.sendcloud.sc/api/v2/label/normal_printer/3172?start_from=3&hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4
label_printer: >-
https://panel.sendcloud.sc/api/v2/label/label_printer/3172?hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4
documents:
- type: label
size: a6
link: >-
https://panel.sendcloud.sc/api/v2/parcels/3/documents/label
status:
id: 0
message: Ready to send
data: {}
country:
iso_3: NLD
iso_2: NL
name: Netherlands
shipment:
id: 1
name: PostNL Standard 0-23kg
carrier:
code: postnl
is_return: false
total_order_value_currency: GBP
total_order_value: '11.11'
colli_uuid: 88296eff-595c-4c62-9b6f-075112bf54f6
collo_nr: 0
collo_count: 1
awb_tracking_number: null
box_number: null
length: null
width: null
height: null
shipping_method_checkout_name: DHL Express Domestic
reference: some_reference_123
CreateParcels:
summary: Create multiple parcels with verbose errors
value:
failed_parcels:
- parcel:
id: 5
name: John Doe
company_name: Sendcloud
address_divided:
street: Stadhuisplein 10
house_number: ''
city: Eindhoven
postal_code: 5611 EM
telephone: '+31612345678'
email: ''
date_created: 01-01-2018 21:45:30
date_updated: 01-01-2018 21:45:30
date_announced: 01-01-2018 21:45:30
tracking_number: S0M3TR4Ck1NgNumB3r
weight: '10.000'
reference: some_reference_123
errors:
house_number:
- This field may not be blank.
CreateParcelVerboseCarrier:
summary: Create single parcel with carrier verbosity
value:
parcel:
address: Stadhuisplein 10
address_2: ''
address_divided:
house_number: '10'
street: Stadhuisplein
carrier:
code: dhl
city: Eindhoven
company_name: Sendcloud
contract: 1
country:
iso_2: NL
iso_3: NLD
name: Netherlands
customs_invoice_nr: ''
customs_shipment_type: 2
data: {}
date_created: 05-06-2018 11:27:55
date_updated: 05-06-2018 11:27:55
date_announced: 05-06-2018 11:31:16
email: [email protected]
id: 22
insured_value: 0
label:
label_printer: >-
https://panel.sendcloud.sc/api/v2/labels/label_printer/22
normal_printer:
- >-
https://panel.sendcloud.sc/api/v2/labels/normal_printer/22?start_from=0
- >-
https://panel.sendcloud.sc/api/v2/labels/normal_printer/22?start_from=1
- >-
https://panel.sendcloud.sc/api/v2/labels/normal_printer/22?start_from=2
- >-
https://panel.sendcloud.sc/api/v2/labels/normal_printer/22?start_from=3
name: John Doe
order_number: ''
shipment_uuid: 928a46f4-8891-4c09-8889-6d0f7c1dc01c
parcel_items: []
postal_code: 5611 EM
shipment:
id: 8
name: Unstamped letter
status:
id: 11
message: Delivered
documents:
- type: cn23-default
size: a4
link: >-
https://panel.sendcloud.sc/api/v2/parcels/22/documents/cn23-default
- type: commercial-invoice
size: a6
link: >-
https://panel.sendcloud.sc/api/v2/parcels/22/documents/commercial-invoice
- type: cp71
size: a6
link: >-
https://panel.sendcloud.sc/api/v2/parcels/22/documents/cp71
- type: label
size: a6
link: >-
https://panel.sendcloud.sc/api/v2/parcels/22/documents/cn23
telephone: '+31626262626'
to_service_point: '217165'
to_state: CA
total_insured_value: 0
total_order_value_currency: GBP
total_order_value: '11.11'
tracking_number: S0M3TR4Ck1NgNumB3r
tracking_url: >-
http://localhost:8000/?carrier=dhl&code=S0M3TR4Ck1NgNumB3r&destination=NL&lang=en-us&source=NL&type=parcel&verification=5642CV
weight: '1.000'
type: parcel
colli_uuid: ab3ecb5e-61b6-42b1-8034-7c6befdeaa63
collo_nr: 0
collo_count: 1
awb_tracking_number: null
box_number: null
length: null
width: null
height: null
shipping_method_checkout_name: ''
external_reference: 'null'
reference: some_reference_123
errors:
non_field_errors:
- >-
PostNL service error: The domain for email address
[email protected] seems to be invalid.
'400':
description: Carrier returned an error
content:
application/json:
schema:
$ref: '#/components/schemas/CreateParcelError'
examples:
Failed:
summary: Failed to create parcel
value:
error:
code: 400
message: >-
non_field_errors: 'PostNL service error: The domain for
email address [email protected] seems to be invalid'
request: api/v2/parcels
description: >-
Create one or multiple parcels, either to be immediately announced to
the carrier, or to be created for later announcement.
parameters:
- $ref: '#/components/parameters/SendcloudPartnerId'
- schema:
type: string
enum:
- verbose-carrier
- verbose
in: query
name: errors
description: >-
When making an API request, the errors query parameter can be used
to determine the type of errors that should be included in the
response. If `verbose` is specified, the response will only contain
errors that Sendcloud has validated. These errors may include
shipment details such as invalid addresses or missing postal codes.
On the other hand, if `verbose-carrier` is specified, the response
will include errors originating from the carriers side of the
shipping process. These errors may result from technical or
validation problems, such as connection failures or issues with the
carrier`s systems, that prevent the shipment from being processed.
More details are described on the page [Handling parcel
errors](/docs/shipping/handling-parcel-errors).
requestBody:
content:
application/json:
schema:
oneOf:
- title: Create a single parcel
properties:
parcel:
$ref: '#/components/schemas/ParcelCreation'
- title: Create a batch of parcels
properties:
parcels:
type: array
items:
$ref: '#/components/schemas/ParcelCreation'
examples:
CreateParcel:
summary: Create a single parcel
value:
parcel:
name: John Doe
company_name: Sendcloud
address: Stadhuisplein
house_number: '10'
city: Eindhoven
postal_code: 5611 EM
telephone: '+31612345678'
request_label: true
email: [email protected]
data: {}
country: NL
shipment:
id: 8
weight: '10.000'
order_number: '1234567890'
insured_value: 0
total_order_value_currency: GBP
total_order_value: '11.11'
quantity: 1
shipping_method_checkout_name: DHL Express Domestic
CreateParcels:
summary: Create a batch of parcels
value:
parcels:
- name: John Doe
company_name: Sendcloud
address: Stadhuisplein
house_number: '10'
city: Eindhoven
postal_code: 5611 EM
telephone: '+31612345678'
request_label: true
email: [email protected]
data: {}
country: NL
shipment:
id: 8
weight: '10.000'
order_number: '1234567890'
insured_value: 0
total_order_value_currency: EUR
total_order_value: '11.11'
quantity: 1
- name: John Doe
company_name: Sendcloud
address: Stadhuisplein
house_number: '10'
city: Eindhoven
postal_code: 5611 EM
telephone: '+31612345678'
request_label: true
email: [email protected]
data: {}
country: NL
shipment:
id: 1
weight: '8.000'
order_number: '1234567891'
insured_value: 0
total_order_value_currency: GBP
total_order_value: '99.99'
quantity: 1
shipping_method_checkout_name: DPD Classic
put:
tags:
- Parcels
summary: Update a parcel
operationId: sc-public-v2-scp-put-update_a_parcel
x-mint:
href: /api/v2/parcels/update-a-parcel
content: >-
<Warning>
**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).
</Warning>
You'll need to include the `parcel_id` of the parcel you wish to
update, which you can retrieve via the [Retrieve all
parcels](/api/v2/parcels/retrieve-parcels) endpoint.
Note that when updating a parcel with a `quantity` higher than 1 (e.g.
a multicollo shipment), setting `request_label=true` is not allowed,
since multiple parcels will be returned.
<Info>
Once a parcel is announced and a label is created, it's not possible to make further changes via this endpoint.
</Info>
## Change address or parcel details
If you need to make adjustments to details in the original parcel,
such as customer address details, shipping method, etc., you can do so
by adding any of the `POST` re
# --- truncated at 32 KB (92 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendcloud/refs/heads/main/openapi/sendcloud-v2-parcels-openapi.yml