> ## 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 a parcel or parcels
> Create one or multiple parcels, either to be immediately announced to the carrier, or to be created for later announcement.
**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.
## OpenAPI
````yaml /.openapi/v2/parcels/openapi.yaml post /parcels
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
security: []
tags:
- name: Parcels
paths:
/parcels:
post:
tags:
- Parcels
summary: Create a parcel or parcels
description: >-
Create one or multiple parcels, either to be immediately announced to
the carrier, or to be created for later announcement.
operationId: sc-public-v2-scp-post-create_parcel
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
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
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
components:
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
schemas:
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
ParcelResponseFull:
allOf:
- $ref: '#/components/schemas/ParcelResponseShort'
- properties:
customs_information:
$ref: '#/components/schemas/ParcelCustomsInformation'
type: object
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
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
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
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
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
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
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
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
AddressDivided:
title: Address Divided Object
type: object
properties:
house_number:
type: string
street:
type: string
description: Address_divided object for a parcel
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
Country:
title: Country Object
description: Country object for a parcel
type: object
properties:
iso_2:
type: string
iso_3:
type: string
name:
type: string
Label:
title: Label Object
type: object
description: Label object for a parcel
properties:
label_printer:
type: string
normal_printer:
type: array
items:
type: string
Status:
title: Status Object
type: object
properties:
id:
type: integer
message:
type: string
description: Status object for a parcel
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
CarrierErrors:
description: Errors object for a parcel
type: object
title: Carrier Errors Object
properties:
non_field_errors:
type: array
items:
type: string
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.
````