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
> 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: contact@sendcloud.com
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: |-
OAuth2 scopes required: `read:parcel`. See [Scopes for OAuth apps](/api/v3/scopes).
**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).
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: test@email.com
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: test@email.com
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 johndoe@email.com 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:
- read:parcel
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:
- write:parcel
x-mint:
href: /api/v2/parcels/create-a-parcel-or-parcels
content: |-
OAuth2 scopes required: `write:parcel`. See [Scopes for OAuth apps](/api/v3/scopes).
**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).
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.
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.
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`.
## 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.
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.
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/).
## 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: john@doe.com
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 johndoe@email.com 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 johndoe@email.com 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: john@doe.com
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: john@doe.com
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: john@doe.com
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: |-
OAuth2 scopes required: `write:parcel`. See [Scopes for OAuth apps](/api/v3/scopes).
**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).
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.
Once a parcel is announced and a label is created, it's not possible to make further changes via this endpoint.
## 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` request parameters listed under the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint. These request parameters must be nested under a `parcel` object.
## Create a shipping label for a parcel which is not yet announced
Use this endpoint to update the `request_label: false` parameter to `true`for parcels which you chose not to announce at the time of parcel creation, and which now need a shipping label.
```json
{
"parcel": {
"id": 1,
"request_label": true
}
}
```
The shipping label will be announced and can be downloaded via an endpoint in the [Labels API](/api/v2/labels) or [Parcel documents API](/api/v2/parcel-documents).
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds:
- write:parcel
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
parcel:
type: array
items:
$ref: '#/components/schemas/ParcelResponseFull'
examples:
ParcelUpdated:
summary: Parcel updated
value:
parcel:
- id: 3
name: Anna Tester
company_name: Summer Co
address: Stadhuisplein 10
address_divided:
street: Stadhuisplein
house_number: '10'
city: Eindhoven
postal_code: 5611 EM
telephone: '0612345678'
email: test@email.com
date_created: 01-01-2018 21:45:30
date_updated: 01-01-2018 21:45:31
date_announced: 01-01-2018 21:45:31
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
customs_declaration: {}
status:
id: 0
message: Ready to send
data: {}
country:
iso_2: NL
iso_3: NLD
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
'404':
description: Not Found
description: Update a parcel which has **not yet been announced**, either to make changes to the original parcel data, or to request a shipping label if one hasn't yet been created.
requestBody:
content:
application/json:
schema:
type: object
properties:
parcel:
$ref: '#/components/schemas/ParcelCreation'
examples:
UpdateParcel:
summary: Update a single parcel
value:
parcel:
id: 3
name: Sendcloud Userß
address: Stadhuisplein 10
postal_code: 5611 EM
city: Eindhoven
country: NL
company_name: Summer Co
/parcels/{id}:
parameters:
- schema:
type: integer
name: id
in: path
required: true
description: The id of the parcel you want to retrieve
get:
summary: Retrieve a parcel
tags:
- Parcels
responses:
'200':
description: OK
content:
application/json:
schema:
description: ''
type: object
properties:
parcel:
$ref: '#/components/schemas/ParcelResponseFull'
'404':
description: Not Found
operationId: sc-public-v2-scp-get-parcel_by_id
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds:
- read:parcel
x-mint:
href: /api/v2/parcels/retrieve-a-parcel
content: |-
OAuth2 scopes required: `read:parcel`. See [Scopes for OAuth apps](/api/v3/scopes).
**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).
description: Retrieve a specific parcel by its `id`.
parameters: []
/parcels/{id}/cancel:
parameters:
- schema:
type: string
name: id
in: path
required: true
description: ID of the parcel
post:
tags:
- Parcels
summary: Cancel a parcel
operationId: sc-public-v2-scp-post-cancel_specific
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds:
- write:parcel
x-mint:
href: /api/v2/parcels/cancel-a-parcel
content: |-
OAuth2 scopes required: `write:parcel`. See [Scopes for OAuth apps](/api/v3/scopes).
**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).
You can use this endpoint to:
1. **Cancel** an announced parcel; or,
2. **Delete** an unannounced parcel
## Cancelling a parcel
When you **cancel** a parcel which has already been announced (has a shipping label attached to it), you will still be able to find it via the `parcel_id` and the [Retrieve a parcel](/api/v2/parcels/retrieve-a-parcel) endpoint. In the Sendcloud platform, it will appear in your **Cancelled labels** overview.
**Insurance Notice**: If you proceed to ship a parcel that was initially cancelled, the parcel's insurance coverage will become void, and any insurance claims will not be valid for that shipment.
After 42 days, it's no longer possible to cancel a parcel, even if it hasn't been shipped.
### Conditions for label cancellation
It's not always possible to cancel a parcel which has already been announced. As a result, cancellation is not guaranteed and may be asynchronous depending on the state of the parcel. When you send a cancellation request via this endpoint, the response will indicate the status of the cancellation request.
Each carrier has different cancellation deadlines. Some carriers do not accept cancellation requests regardless of whether or not the label is cancelled within the deadline. You can find more information about cancellation deadlines in our [help center](https://support.sendcloud.com/hc/en-us/articles/360025143991-How-do-I-cancel-my-shipment-).
## Deleting a parcel
When you **delete** a parcel which hasn't been announced, the parcel will be removed from the Sendcloud system and you will no longer be able to locate it via the parcel `id`. You will need to create the parcel again if you want to announce it at a later date.
responses:
'200':
description: |-
Cancelled
- The parcel has been cancelled if all valid conditions apply.
content:
application/json:
schema:
$ref: '#/components/schemas/CancelParcelStatus'
examples:
Cancelled:
summary: Successfully Cancelled
value:
status: cancelled
message: Parcel has been cancelled
'202':
description: |-
Parcel cancelation has been queued
- The parcel having the status of ready to send (1000) will be watched for 14 days and if nothing nothing has changed to the parcel, it will be cancelled.
'400':
description: |-
Cancellation rejected
- When parcel has the status of 2000 which means it is already cancelled.
- After period of 42 days of the parcel being announced we cannot cancel it and will let you know about it through a response message.
- When parcel has the status ode (11) saying that it’s delivered it will not do anything to the parcel and your request will be rejected.
'404':
description: Not Found
'410':
description: |-
Deleted
- Happens when the parcel announcement has failed, the parcel status contains id of 1002 and you try to cancel it.
description: Cancel an announced parcel (if supported by the carrier) or delete an unannounced parcel.
/parcels/{id}/return_portal_url:
parameters:
- schema:
type: string
name: id
in: path
required: true
description: ID of the parcel
get:
summary: Retrieve a return portal URL
tags:
- Parcels
responses:
'200':
description: OK
content:
application/json:
schema:
description: ''
type: object
properties:
url:
type: string
minLength: 1
required:
- url
examples:
ReturnPortalURL:
summary: Returns portal URL
value:
url: http://mybrand.returns-portal.com/initiate/
'404':
description: Not Found
operationId: sc-public-v2-scp-get-return_portal_url
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds:
- read:parcel
x-mint:
href: /api/v2/parcels/retrieve-a-return-portal-url
content: |-
OAuth2 scopes required: `read:parcel`. See [Scopes for OAuth apps](/api/v3/scopes).
**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).
The URL which is retrieved will link directly to the parcel in the Sendcloud Return portal, so a **return parcel** can be created immediately based on the outgoing shipment.
If no Return portal is configured, or if no brand is connected to the parcel, this endpoint will return an error response with a 404 status code.
description: Check which of your branded return portals is associated with a specific parcel using the parcel's `id`.
components:
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:
read:analytics: View your shipping analytics
read:audit-log: View your account's audit log
read:brand: View your brands
write:brand: Manage your brands
write:carrier: Configure carriers and contracts
read:checkout: View your dynamic checkout configurations and templates
read:event-subscription: View your event subscriptions
write:event-subscription: Create and manage your event subscriptions
read:integration: View your integrations
write:integration: Connect and manage integrations
read:invoice: View your invoices
read:notification: View your notifications
write:notification: Manage your notifications
read:operational-settings: View your warehouses, shipping lanes, and other operational settings
write:operational-settings: Manage your warehouses, shipping lanes, and other operational settings
read:order: View your orders
write:order: Import and process your orders
read:organization: View organization settings
write:organization: Change organization settings
read:parcel: View your shipments and their tracking status
write:parcel: Create, announce, and cancel shipments
read:pickup: View carrier pickups and the options available for scheduling them
write:pickup: Schedule and manage carrier pickups
read:price: View shipping prices
write:product: Manage your product catalog
read:return: View your returns
write:return: Create and manage returns
read:return-settings: View your return settings
write:return-settings: Configure your return settings
read:service-point: View carrier service points
read:shipping-method: View shipping methods, products and prices
read:shipping-rule: View your shipping rules
write:shipping-rule: Create and manage shipping rules
read:support-ticket: View your support tickets
write:support-ticket: Manage your support tickets
read:tracking-message: View your tracking notifications
write:tracking-message: Manage your tracking notifications
read:tracking-page: View your tracking page
write:tracking-page: Customize your tracking page
read:user: Read your basic account information
schemas:
CreateParcelError:
description: Error returned during parcel creation
type: object
title: Parcel Creation Error Object
properties:
error:
type: object
properties:
code:
type: integer
description: Error code
message:
type: string
description: Concatenated to one string array of errors
request:
type: string
description: URL of the Sendcloud'd endpoint which returned an error
CarrierErrors:
description: Errors object for a parcel
type: object
title: Carrier Errors Object
properties:
non_field_errors:
type: array
items:
type: string
Documents:
title: Documents Object
type: object
properties:
type:
type: string
description: The type of the document. See the list below for available types.
enum:
- label
- cp71
- cn23
- commercial-invoice
- cn23-default
size:
type: string
description: 'The paper size of the document, you can expect: a4 and a6.'
link:
type: string
description: |-
A link to the document, which allows downloading of the document in PDF, PNG, and ZPL. Learn more about the [endpoint](/api/v2/integrations/retrieve-a-list-of-shipments).
Send a GET request to https://panel.sendcloud.sc/api/v2/parcels/{parcelID}/documents/label using your parcel ID.
You can pick the resolution in the parameters of the request. The default value is 203 dpi.
description: Documents object for a parcel
Status:
title: Status Object
type: object
properties:
id:
type: integer
message:
type: string
description: Status object for a parcel
Shipment:
title: Shipment Object
type: object
properties:
id:
type: integer
description: ID of shipping method
name:
type: string
description: Name of shipping method
required:
- id
description: Shipping method object for a parcel
Label:
title: Label Object
type: object
description: Label object for a parcel
properties:
label_printer:
type: string
normal_printer:
type: array
items:
type: string
Country:
title: Country Object
description: Country object for a parcel
type: object
properties:
iso_2:
type: string
iso_3:
type: string
name:
type: string
AddressDivided:
title: Address Divided Object
type: object
properties:
house_number:
type: string
street:
type: string
description: Address_divided object for a parcel
ParcelCreation:
description: Parcel object for a parcel creation
type: object
title: Parcel Creation Object
properties:
id:
type: integer
minimum: 1
description: Identifier of the parcel (ignored when creating)
name:
type: string
description: Name of the recipient
company_name:
type: string
description: Company name of the recipient the parcel will be shipped to
contract:
type: integer
description: Id of the contract that you would like to use to create the parcel with.
minimum: 1
address:
type: string
description: Address of the recipient
address_2:
type: string
description: Additional address information, e.g. 2nd level
house_number:
type: string
description: House number of the recipient
city:
type: string
description: City of the recipient
postal_code:
type: string
description: Zip code of the recipient
telephone:
type: string
description: Phone number of the recipient
request_label:
type: boolean
description: |
Should the parcel request a label. This property used to be called requestLabel. We kept it backwards compatible by still accepting the previous name.
email:
type: string
minLength: 1
description: E-mail address of the recipient
data:
type: object
description: This field previously served to store a `pakjegemak` key; however, the data provided in this field is no longer stored or used anymore. Please use `to_service_point` property to use service points.
deprecated: true
nullable: true
country:
type: string
minLength: 1
description: Country of the recipient
shipment:
$ref: '#/components/schemas/Shipment'
weight:
type: string
minLength: 1
description: Weight of the parcel in kilograms, if none given the default weight from settings is used. If you provide no weight in your request we’ll use the default weight set in your settings.
order_number:
type: string
description: Order number of your order
insured_value:
type: integer
description: |
This field is mutually exclusive with the `total_insured_value`. Amount of Sendcloud Insurance to add.
This must be a positive value, larger than 2. If a value between 0 and 2 is sent, it is rounded up to 2.
The maximum insurance is 5000.
This field does not take the carrier provided shipping method insurance into consideration.
Note: this value is an integer. If decimal numbers are sent, these are rounded up to the nearest whole number.
Example: sending 72.35 results in a `insured_value` of 73.
Note: For multicollo shipments, where the `quantity` is greater than 1, the specified insurance amount applies per parcel, not to the shipment as a whole.
For example, if you ship 5 parcels and set the `insured_value` to 500 EUR/GBP, each parcel will be insured for 500 EUR/GBP. This results in a total shipment coverage of 5 x 500 = 2500 EUR/GBP.
total_order_value_currency:
type: string
description: The currency of the total order value. Validated against a format of “XYZ” (ISO 4217).
total_order_value:
type: string
description: The value paid by the buyer (via various payment methods supported by the shop(cash on delivery, pre-paid or post-paid), it will also be used for the cash on delivery amount for example “99.99”.
quantity:
type: integer
description: 'Create a multi-collo shipment. Default value: 1. Minimal value: 1. Maximal value: 20. When request_label is true, it is required to use the Create multiple parcels method, since multiple parcels will be returned. When request_label is false, the number of parcels will be set according to this value in the incoming order overview.'
shipping_method_checkout_name:
type: string
description: Shipping method name selected by buyer during the checkout
to_post_number:
type: string
description: Code required in case of PO Box or post locker delivery
country_state:
type: string
description: Code of the state (e.g. NY for New York) or province (e.g. RM for Rome). Destinations that require this field are USA, Canada, Italy and Australia. Errors related to this field will mention the to_state field.
sender_address:
type: integer
description: |
ID of the SenderAddress
**Keep in mind that this id will not be saved / reflected in the created order (Incoming Orders View / Pack&Go) in case `request_label` is `false`.**
customs_invoice_nr:
type: string
description: Customs invoice number. Deprecated in favor of the `customs_information` object.
deprecated: true
customs_shipment_type:
type: integer
enum:
- 0
- 1
- 2
- 3
- 4
description: |
Customs shipment type. Deprecated in favor of the `customs_information` object.
* `0` - Gift
* `1` - Documents
* `2` - Commercial Goods
* `3` - Commercial Sample
* `4` - Returned Goods
deprecated: true
external_reference:
type: string
nullable: true
description: A reference to be assigned to this parcel. Must be unique across parcels. This field is used to create idempotence.
reference:
type: string
nullable: true
description: A reference to be assigned to this parcel. Multiple parcels can have the same reference.
default: '0'
to_service_point:
type: integer
description: ID of the selected service point
total_insured_value:
type: integer
description: |
This field is mutually exclusive with the `insured_value`. Amount of total insurance to add.
This must be a positive value, larger than 2. If a value between 0 and 2 is sent, it is rounded up to 2.
The maximum insurance is 5000 plus your shipping method’s insurance depending on the carrier.
This field works by automatically calculating how much Sendcloud Insurance you’d need to add plus your shipping method’s insurance so it matches the exact value you’ve given.
As an example, DPD insures all their shipments by 520€ by default.
If you pass the `total_insured_value`: 5000 your shipment will have a total insurance coverage of 5000€, but you’re only paying for 4480€.
Note: this value is an integer. If decimal numbers are sent, these are rounded up to the nearest whole number.
Example: sending 72.35 results in a `total_insured_value` of 73.
Note: For multicollo shipments, where the `quantity` is greater than 1, the specified insurance amount applies per parcel, not to the shipment as a whole.
For example, if you ship 5 parcels and set the `insured_value` to 500 EUR/GBP, each parcel will be insured for 500 EUR/GBP. This results in a total shipment coverage of 5 x 500 = 2500 EUR/GBP.
shipment_uuid:
type: string
description: Unique identifier that we assign to your shipment within the Sendcloud system.
parcel_items:
type: array
description: List of items the order contains. Check the structure of a parcel_item in the “Parcel_items” section (remember, it’s a list of them!).
items:
$ref: '#/components/schemas/parcel-item'
is_return:
type: boolean
description: Set to true if this parcel is a return
length:
type: string
description: Parcel length in centimeters (will be used for volumetric weight calculation)
width:
type: string
description: Parcel width in centimeters (will be used for volumetric weight calculation)
height:
type: string
description: |-
Parcel height in centimeters (will be used for volumetric weight calculation). Note: You must provide length, width and height all at once for calculating volumetric weight or passing them as-is to carriers that require these properties
Parcel height in centimeters (will be used for volumetric weight calculation). Note: You must provide length, width and height all at once for calculating volumetric weight or passing them as-is to carriers that require these properties
request_label_async:
type: boolean
description: Makes sure that the label is requested asynchronously. The parcel is returned, but without label. You will need to poll for status changes on the parcel.
apply_shipping_rules:
type: boolean
description: When set to True configured shipping rules will be applied before creating the label and announcing the Parcel
from_name:
type: string
description: Name of the sender (when creating a return parcel)
from_company_name:
type: string
description: Company name of the sender the parcel will be shipped from (when creating a return parcel)
from_address_1:
type: string
description: Address of the sender (when creating a return parcel)
from_address_2:
type: string
description: Additional address information of the sender (when creating a return parcel)
from_house_number:
type: string
description: House number of the sender (when creating a return parcel)
from_city:
type: string
description: City of the sender (when creating a return parcel)
from_postal_code:
type: string
description: Zip code of the sender
from_country:
type: string
description: Country of the sender (when creating a return parcel)
from_telephone:
type: string
description: Phone number of the sender (when creating a return parcel)
from_email:
type: string
description: E-mail address of the sender (when creating a return parcel)
from_vat_number:
type: string
description: VAT number of the sender (when creating a return parcel). Deprecated in favor of the `customs_information` object.
from_eori_number:
type: string
description: EORI number of the sender (when creating a return parcel). Deprecated in favor of the `customs_information` object.
deprecated: true
from_inbound_vat_number:
type: string
description: GB VAT number - needed for shipments from Europe to GB (when creating a return parcel). Deprecated in favor of the `customs_information` object.
deprecated: true
from_inbound_eori_number:
type: string
description: GB EORI number - needed for shipments from Europe to GB (when creating a return parcel). Deprecated in favor of the `customs_information` object.
deprecated: true
from_ioss_number:
type: string
description: IOSS(Import One-Stop Shop) number of the sender (when creating a return parcel). Deprecated in favor of the `customs_information` object.
deprecated: true
customs_information:
$ref: '#/components/schemas/ParcelCustomsInformation'
required:
- name
- address
- city
- postal_code
- country
ParcelResponseShort:
description: Parcel object model
type: object
title: Parcel Object
properties:
address:
type: string
address_2:
type: string
description: |
An apartment or floor number that has been extracted from general address input.
address_divided:
$ref: '#/components/schemas/AddressDivided'
carrier:
type: object
properties:
code:
$ref: '#/components/schemas/carrier'
city:
type: string
company_name:
type: string
contract:
type: integer
minimum: 1
description: Id of the contract that was used to create the parcel.
nullable: true
country:
$ref: '#/components/schemas/Country'
customs_invoice_nr:
type: string
description: Customs invoice number
customs_shipment_type:
type: integer
description: |
Customs shipment type. Deprecated in favor of the `customs_information` object.
* `0` - Gift
* `1` - Documents
* `2` - Commercial Goods
* `3` - Commercial Sample
* `4` - Returned Goods
enum:
- 0
- 1
- 2
- 3
- 4
nullable: true
deprecated: true
data:
type: object
date_created:
type: string
date_updated:
type: string
date_announced:
type: string
email:
type: string
description: An email address of the person this parcel is supposed to be delivered to.
id:
type: integer
insured_value:
type: integer
label:
$ref: '#/components/schemas/Label'
name:
type: string
order_number:
type: string
shipment_uuid:
type: string
parcel_items:
type: array
items:
$ref: '#/components/schemas/parcel-item'
postal_code:
type: string
external_reference:
type: string
nullable: true
description: A reference to be assigned to this parcel. Must be unique across parcels. This field is used to create idempotence.
reference:
type: string
nullable: true
description: A reference to be assigned to this parcel. Multiple parcels can have the same reference.
default: '0'
shipment:
$ref: '#/components/schemas/Shipment'
status:
$ref: '#/components/schemas/Status'
documents:
type: array
uniqueItems: true
description: An array of documents. A parcel can contain multiple documents, for instance labels and a customs form. This field returns an array of all the available documents for this parcel.
items:
$ref: '#/components/schemas/Documents'
telephone:
type: string
to_service_point:
type: string
description: An id of service point to which the shipment is going to be shipped.
to_state:
type: string
description: 'Represents the state or province of a country. Countries that need a state are USA, Canada, Italy and Australia. e.g. America’s city of Los Angeles belongs to the California state: CA. Shipments to Italy need a province. e.g. Italy’s city of Rome belongs to Roma province: RM.'
total_insured_value:
type: integer
total_order_value_currency:
type: string
total_order_value:
type: string
tracking_number:
type: string
description: Tracking number of the shipment.
tracking_url:
type: string
description: tracking url of this shipment.
weight:
type: string
type:
type: string
description: Returns either ‘parcel’ or ‘letter’ by which you can determine the type of your shipment.
enum:
- parcel
- letter
deprecated: true
nullable: true
colli_uuid:
type: string
collo_nr:
type: integer
description: A number indicating the collo number within a shipment. For a non-multi-collo shipment, this value will always be 0. In a multi-collo shipment with 3 collos, this number will range from 0 to 2.
collo_count:
type: integer
description: A number indicating the number of collos within a shipment. For non-multi-collo shipments, this value will always be 1.
is_return:
type: boolean
description: Indicates if the parcel correspond to a return.
awb_tracking_number:
type: string
description: Deutsche Post Global Mail only. This indicates the air waybill number of this box of Global Mail parcels. This will be only set once Finalize box has been called.
nullable: true
box_number:
type: integer
description: Deutsche Post Global Mail only. This indicates the box to which this parcel belongs. This will be only set for Global Mail parcels.
nullable: true
length:
type: string
description: 'Parcel length in centimeters (will be used for volumetric weight calculation). Examples: “48” or “52.3”'
nullable: true
width:
type: string
description: 'Parcel width in centimeters (will be used for volumetric weight calculation). Examples: “48” or “52.3”'
nullable: true
height:
type: string
description: 'Parcel height in centimeters (will be used for volumetric weight calculation). Examples: “48” or “52.3”'
nullable: true
shipping_method_checkout_name:
type: string
description: Shipping method name selected by buyer during the checkout
customs_declaration:
type: object
deprecated: true
description: An object with available printers that lists available links to the created customs declaration form. (deprecated in favour of documents).
note:
type: string
description: This field can be used to add additional notes regarding an order. The notes will not be displayed on a label, but will be displayed on both the Packing slips & Picking lists which you can use for Pack & Go feature. The value will not be shared with carriers. It may be used for packing instructions, such as "gift" or "do not send before monday".
nullable: true
errors:
$ref: '#/components/schemas/CarrierErrors'
required:
- id
ParcelResponseFull:
allOf:
- $ref: '#/components/schemas/ParcelResponseShort'
- properties:
customs_information:
$ref: '#/components/schemas/ParcelCustomsInformation'
type: object
ParcelCustomsInformation:
title: ParcelCustomsInformation
type: object
description: Optional customs information that should be provided for international parcels. This information is used for generating customs documents.
example:
customs_invoice_nr: INV-123
customs_shipment_type: 2
export_type: private
invoice_date: '2023-08-24'
discount_granted: '14.99'
freight_costs: '4.65'
insurance_costs: '3.60'
other_costs: '1.20'
general_notes: 'Compliance: Goods comply with international safety standards (CE certified).'
additional_declaration_statements:
- With reference to the above shipment, I understate that the content is not made of leather parts of animal species protected by the Washington Convention.
- I solemnly declare that the contents of this document represent a true and accurate account of the events as they occurred. I acknowledge my responsibility for the information presented herein and understand that any misrepresentation or falsification may result in legal consequences or other penalties as applicable.
importer_of_record:
name: John Doe
company_name: ImporterCo
address_1: Maple Avenue
house_number: '123'
postal_code: '90210'
city: Springfield
country_code: US
country_state: US-MA
telephone: '+15551234567'
email: info@importer-of-record-example.com
tax_numbers:
sender:
- name: VAT
country_code: NL
value: NL123456789B01
- name: EORI
country_code: NL
value: NL123456789
receiver:
- name: EIN
country_code: US
value: '123456789'
importer_of_record:
- name: EIN
country_code: US
value: '987654321'
return_data:
return_postal_code: 1111 AA
outbound_tracking_number: JT1234567890
outbound_shipment_date: '2023-08-14'
outbound_carrier_name: UPS
properties:
customs_invoice_nr:
type: string
description: Customs invoice number
example: INV-123
customs_shipment_type:
type: integer
description: |
Customs shipment type
* `0` - Gift
* `1` - Documents
* `2` - Commercial Goods
* `3` - Commercial Sample
* `4` - Returned Goods
enum:
- 0
- 1
- 2
- 3
- 4
example: 2
export_type:
type: string
description: 'Export type documentation serves to categorize international shipments into three primary classifications: Private exports, intended for personal use; Commercial B2C exports, directed towards individual consumers; and Commercial B2B exports, involving business-to-business transactions. These distinctions facilitate adherence to regulatory requirements and ensure the orderly movement of goods across international boundaries.'
enum:
- private
- commercial_b2c
- commercial_b2b
default: commercial_b2c
example: private
invoice_date:
type: string
format: date
description: The date when the commercial invoice for the goods was issued (ISO 8601). If not provided, the announcement date will be used by default.
discount_granted:
type: string
description: Shipper's granted discount amount to user.
example: '14.99'
freight_costs:
type: string
description: Charges associated with the transportation of the goods to their destination paid by the receiver.
example: '4.65'
insurance_costs:
type: string
description: The costs of insurance coverage for the goods during transit paid by the receiver.
example: '3.60'
other_costs:
type: string
description: Additional costs or charges associated with the shipment that are not covered by freight and insurance paid by the receiver.
example: '1.20'
general_notes:
type: string
description: Exporter or shipper can include any additional information or special instructions related to the goods being shipped. This section is used to provide details that may not be covered in other parts of the invoice but are relevant for customs clearance.
maxLength: 500
example: 'Compliance: Goods comply with international safety standards (CE certified).'
additional_declaration_statements:
type: array
description: List of additional declaration statements. Each statement may contain specific details about the nature of the goods being shipped, their origin, or any additional information required by customs authorities. The content of an additional declaration statement can vary based on the requirements of the importing and exporting countries, as well as the nature of the goods being transported.
maxItems: 100
items:
type: string
example: With reference to the above shipment, I understate that the content is not made of leather parts of animal species protected by the Washington Convention.
maxLength: 1024
importer_of_record:
type: object
description: |-
Importer of Record (IOR) information.
A customs-connected record importer specializes in importing goods and managing the associated customs documentation. If not provided, the receiver's address will be used instead.
properties:
name:
type: string
description: Name of IOR
maxLength: 75
company_name:
type: string
description: IOR company name
maxLength: 50
address_1:
type: string
description: Address of IOR
maxLength: 150
address_2:
type: string
description: Additional address information, e.g. 2nd level
maxLength: 150
house_number:
type: string
description: IOR house number
maxLength: 20
city:
type: string
description: IOR city
maxLength: 30
postal_code:
type: string
description: IOR postal code
maxLength: 12
country_code:
type: string
description: IOR country. ISO 3166-1 alpha-2 code
maxLength: 2
country_state:
type: string
description: Code of the state (e.g. NY for New York) or province (e.g. RM for Rome). Destinations that require this field are USA, Canada, Italy and Australia. Format ISO-3166-2.
example: IT-RM
maxLength: 14
telephone:
type: string
description: IOR phone number in E.164 format
maxLength: 20
email:
type: string
description: IOR email
maxLength: 320
required:
- name
- address_1
- city
- postal_code
- country_code
tax_numbers:
type: object
description: Identification numbers and codes related to sender, receiver and importer of record provider.
properties:
sender:
type: array
description: Sender's list of identification number objects
maxItems: 100
items:
$ref: '#/components/schemas/TaxNumber'
receiver:
type: array
description: Receiver's list of identification number objects
maxItems: 100
items:
$ref: '#/components/schemas/TaxNumber'
importer_of_record:
type: array
description: Importer of record's list of identification number objects
maxItems: 100
items:
$ref: '#/components/schemas/TaxNumber'
required:
- sender
- receiver
- importer_of_record
return_data:
type: object
description: Additional information that should be provided for return parcels.
properties:
return_postal_code:
type: string
maxLength: 12
description: The Postcode of the customer to whom the parcel was originally shipped.
outbound_tracking_number:
type: string
description: Tracking number of outbound shipment
example: BE123456789
maxLength: 40
outbound_shipment_date:
type: string
format: date
description: Data of outbound shipment
example: '2020-11-27'
outbound_carrier_name:
type: string
description: The name of the carrier used for outbound shipment
example: DHL
maxLength: 50
required:
- customs_invoice_nr
- customs_shipment_type
CancelParcelStatus:
title: Cancel Parcel Status Object
type: object
properties:
status:
type: string
minLength: 1
message:
type: string
minLength: 1
required:
- status
- message
carrier:
type: string
title: Carrier Code
enum:
- amazon
- bol
- bpost
- brt
- budbee
- chronopost
- cirro
- colisprive
- colissimo
- correos
- correos_express
- ctt_express
- dbschenker
- delivengo
- dhl
- dhl_2_man_handling
- dhl_de
- dhl_ecommerce
- dhl_express
- dhl_parcel_gb
- dhl_parcel_iberia
- dp
- dpd
- dpd_at
- dpd_fr
- dpd_gb
- dpd_local
- evri_international
- fadello
- fairsenden
- fedex
- fedexcrossborder
- fietskoeriers
- geodis
- glovo
- gls_de
- gls_es
- gls_eu
- gls_it
- gls_nl
- hermes_at
- hermes_c2c_gb
- hermes_de
- hermes_gb
- hived
- homerr
- hurby
- inpost_es
- inpost_gb
- inpost_it
- inpost_pl
- lettresuivie
- mhi
- mondial_relay
- mrw
- nacex
- paack
- parcelforce
- plx
- postat
- poste_italiane
- poste_it_delivery
- postnl
- postnl_fulfilment
- postnl_large
- postnord
- rjp
- rjpv2
- royal_mail
- sandd
- sendcloud
- seur
- skymail
- spring
- storeshippers
- tipsa
- tnt_it
- transforce
- trunkrs
- ups
- van_straaten
- viatim
- yodel
description: A carrier represented by a Sendcloud code
example: postnl
dangerous-goods:
title: DangerousGoods
type: object
description: Hazardous materials information for items.
properties:
chemical_record_identifier:
type: string
nullable: true
description: Chemical record identifier for the dangerous goods
regulation_set:
type: string
enum:
- IATA
- ADR
description: Regulation set governing the dangerous goods
packaging_type_quantity:
type: string
nullable: true
description: Quantity of packaging type
packaging_type:
type: string
nullable: true
description: Type of packaging used
packaging_instruction_code:
type: string
nullable: true
description: Packaging instruction code
id_number:
type: string
nullable: true
description: UN identification number
class_division_number:
type: string
nullable: true
description: Hazard class and division number
quantity:
type: string
nullable: true
description: Quantity of dangerous goods
unit_of_measurement:
type: string
enum:
- KG
- G
- L
- ML
description: Unit of measurement for dangerous goods quantity
proper_shipping_name:
type: string
nullable: true
description: Proper shipping name as defined by regulations
commodity_regulated_level_code:
type: string
enum:
- LQ
- EQ
description: Commodity regulated level code
transportation_mode:
type: string
enum:
- Highway
- Ground
- PAX
- CAO
description: Mode of transportation
emergency_contact_name:
type: string
nullable: true
description: Name of emergency contact person
emergency_contact_phone:
type: string
nullable: true
description: Phone number of emergency contact
adr_packing_group_letter:
type: string
enum:
- I
- II
- III
description: ADR packing group classification
local_proper_shipping_name:
type: string
nullable: true
description: Local proper shipping name
transport_category:
type: string
nullable: true
description: Transport category for ADR regulations
tunnel_restriction_code:
type: string
nullable: true
description: Tunnel restriction code
weight_type:
type: string
enum:
- Net
- Gross
description: Type of weight measurement
parcel-item:
title: Parcel Item Object
type: object
description: The items of a Parcel
properties:
hs_code:
type: string
description: |-
Harmonized System Code [Wikipedia Link](https://en.wikipedia.org/wiki/Harmonized_System).
Providing a complete HS code with more characters increases the delivery rate.
maxLength: 12
weight:
type: string
description: Weight of a single item in kilograms.
quantity:
type: integer
minimum: 1
description: Quantity of items shipped.
description:
type: string
description: Description of the item.
maxLength: 255
origin_country:
type:
- string
- 'null'
description: ISO-2 code of the country where the items were originally produced. [External Link](http://www.nationsonline.org/oneworld/country_code_list.htm).
value:
type: number
description: Value of a single item.
example: 10.5
sku:
type: string
description: The SKU of the product.
maxLength: 255
product_id:
type: string
description: The internal ID of the product.
maxLength: 255
properties:
type: object
description: 'The list of properties of the product. Used as a JSON object with {‘key’: ‘value’}.'
item_id:
type:
- string
- 'null'
maxLength: 255
description: External ID of the item generated by a shop system or similar.
return_reason:
type:
- integer
- 'null'
description: The return reason identifier matching the ones provided from Sendcloud. Only applicable for returns.
minimum: 1
return_message:
type:
- string
- 'null'
description: Optional a message relating to the return. Only applicable for returns.
mid_code:
type: string
description: Code to identify the manufacturer of the product. It is required when shipping to the US and is used for generating commercial invoice.
maxLength: 15
example: US1234567
material_content:
type: string
description: Composition of the items. Used for commercial invoice generation.
maxLength: 255
example: 100% Cotton
intended_use:
type: string
description: Text that identifies the Intended Use of the item. This will be used to classify the item based on the new ICS2 system. Used for commercial invoice generation.
maxLength: 255
example: Personal use
manufacturer_product_id:
type:
- string
- 'null'
description: A manufacturer or product supplier's unique code, assigned to an individual product.
maxLength: 70
example: ABC-12345
manufacturer_product_id_std:
type:
- string
- 'null'
description: A standardized manufacturer product identifier assigned by a global industry standard body (e.g. GTIN). Provide only if one exists for the product.
maxLength: 70
example: '01234567890128'
dangerous_goods:
$ref: '#/components/schemas/dangerous-goods'
dds_reference:
title: DDS Reference
type:
- string
- 'null'
description: The DDS (Due Diligence Statement) reference number associated with the item, if applicable. See EUDR system for more details.
example: 25FIYPEK0A7573
taric_doc_code:
title: TARIC document code
type:
- string
- 'null'
description: TARIC document codes are specific alphanumeric codes used in EU customs declarations (Box 44) to identify required supporting documents, certificates, or conditions for a product, like health certificates (e.g., 3200), origin proofs (e.g., EUR.1), or special authorizations (e.g., C716 for due diligence) for simplified procedures, ensuring compliance with EU trade rules for various goods.
example: Y142
required:
- hs_code
- weight
- quantity
- description
- value
TaxNumber:
title: Tax Number Object
description: Identification numbers and codes used in different contexts. These identifiers are used for taxation, customs, business registration, and other purposes, depending on the country and the specific regulatory requirements. Depending on these requirements you may need to pass one or several numbers related to sender, receiver or importer of record provider. These numbers and codes will be included into final Customs documents.
type: object
properties:
name:
type: string
example: EORI
description: |
Tax number abbreviation
* VAT - Value-Added Tax → VOEC number for Norway should be shared here as advised by the [Norwegian Tax Authorities](https://www.skatteetaten.no/globalassets/bedrift-og-organisasjon/voec/sending-and-marking-goods-through-postal-services-and-transporters.pdf)
* EIN - Employer Identification Number
* GST - Goods and Service Tax
* SSN - Social Security Number
* EORI - Economic Operators Registration and Identification for the European Union
* DUN - Data Universal Numbering System
* FED - Federal Tax ID
* STA - State Tax ID
* CNP - Brazil CNPJ/CPF Federal Tax
* IE - Brazil type IE/RG Federal Tax
* INN - Russia bank details section INN
* KPP - Russia bank details section KPP
* OGR - Russia bank details section OGRN
* OKP - Russia bank details section OKPO
* IOSS - SDT or Overseas Registered Supplier or Import One-Stop-Shop or GB VAT (foreign) registration or AUSid GST Registration or VAT on E-Commerce
* FTZ - Free Trade Zone ID
* DAN - Deferment Account Duties Only
* TAN - Deferment Account Tax Only
* DTF - Deferment Account Duties, Taxes and Fees Only
* RGP - EU Registered Exporters Registration ID
* DLI - Driver's License
* NID - National Identity Card - A PID (Personal Identification Number) should be provided as NID (National Identity Card).
* PAS - Passport
* MID - Manufacturer ID
* UKIMS - UK Internal Market Scheme -> customs clearance for shipping from Great Britain to Northern Ireland under the Windsor Framework, for more information see [Windsor Framework](https://www.gov.uk/government/publications/the-windsor-framework)
enum:
- VAT
- EIN
- GST
- SSN
- EORI
- DUN
- FED
- STA
- CNP
- IE
- INN
- KPP
- OGR
- OKP
- IOSS
- FTZ
- DAN
- TAN
- DTF
- RGP
- DLI
- NID
- PAS
- MID
- UKIMS
country_code:
type: string
example: NL
description: Issuing country code (ISO 3166-1 alpha-2 code)
maxLength: 2
value:
type: string
example: NL123456789B01
description: Tax number itself
maxLength: 100
required:
- name
- country_code
- value
parameters:
SendcloudPartnerId:
in: header
name: Sendcloud-Partner-Id
description: |-
If you are an official [Sendcloud Tech Partner](https://www.sendcloud.com/ecosystem/), send your unique Sendcloud Partner UUID as a request header for the system to recognize you.
The header is not required but if it is set, the system will check it. An unknown or invalid UUID will cause a 400 error.
schema:
type: string