7. Shipment related Object Definitions
7.A Shipment Object Definition
7.A.1 Overview
You can create shipments with this object. You can specify multiple address ids in the recipients column to create multiple shipments. If you want to create a return shipment you have to use the ReturnShipment object.
barcode
Data type: string
Required: n/a.
Shipment barcode.
id
Data type: integer
Required: n/a.
Shipment id.
parent_id
Data type: integer
Required: no
The parent shipment. This is used for related return shipment.
account_id
Data type: integer
Required: n/a.
The account id to which this shipment belongs.
shop_id
Data type: integer
Required: n/a.
The shop id to which this shipment belongs.
reference_identifier
Data type: string
Required: No.
Arbitrary reference indentifier to identify this shipment.
shipment_type
Data type: integer
Required: n/a.
recipient
Data type: Address
Required: Yes for application/vnd.shipment+json
The recipient address. Use this field when you want to create a shipment for one address.
recipients
Data type: array of Address objects
Required: Yes for application/vnd.shipment_recipients+json Use this field when you want to create multiple shipments for multiple addresses.
status
Data type: shipment_status
Required: no
This is the internal shipment status. What we do is filter and translate the shipment status provided by the carrier in order to reduce the number of statuses.
options
Data type: ShipmentOptions
Required: Yes.
The shipment options.
pickup
Data type: PickupLocation
Required: Yes for options.delivery_type 4.
The pickup location for this shipment.
customs_declaration
Data type: CustomsDeclaration
Required: yes for non-EU shipments.
The customs declaration information.
physical_properties
Data type: PhysicalProperties
Required: yes for non-EU and digital stamp shipment types .
Shipment physical properties such as dimension, weight etc. This object may be updated when fetching shipment status update from the carrier.
carrier
Data type: carrier
Required: yes.
The carrier that will deliver the package.
general_settings
Data type: ShipmentGeneralSettings
Required: no
You can specify general settings for the shipment with this object.
price
Data type: price
Required: n/a.
The shipment price.
secondary_shipments Data type: an array of shipment
Required: no
You can specify secondary shipments for the shipment with this object. This property is used to create a multi collo shipment: multiple packages to be delivered to the same address at the same time. Secondary shipment can be passed as empty json objects as all required data will be copied from the main shipment. When data is passed with the secondary shipment this data will be used in favor of the main shipment data.
multi_collo_main_shipment_id Data type: integer
In case of a multi collo shipment this field contains the id of the main shipment.
created
Data type: timestamp
Required: n/a.
Date of creation.
modified
Data type: timestamp
Required: n/a.
Date of modification.
7.A.2 Examples
POST example national shipment
POST example national multi collo shipment
POST example international shipment
POST example pickup location
GET example national shipment A
GET example national shipment B
GET example national multi collo shipment
7.B Address Object Definition
7.B.1 Overview
This is the adress object
cc
Data type: country_code
Required: yes.
The address country code.
region
Data type: string
Required: no.
The region, department, state or province of the address.
state
Data type: string
Required: no.
Depending on the carrier and destination this field should contain address state. Up to 2 characters long.
postal_code
Data type: string
Required: Yes for NL and EU destinations except for IE.
The address postal code.
city
Data type: string
Required: yes.
The address city.
street
Data type: string
Required: yes.
The address street name. When shipping to an international destination, you may include street number in this field.
street_additional_info
Data type: string
Required: no.
Additional information for the street that should not be included in the street field.
number
Data type: string
Required: Yes for domestic shipments in NL and BE.
Street number.
number_suffix
Data type: string
Required: no
Street number suffix.
box_number Data type: string Required: no Only applicable for Belgian addresses. Up to 8 characters long.
person
Data type: string
Required: yes.
The person at this address. Up to 40 characters long.
company
Data type: string
Required: no.
Company name.
email
Data type: string
Required: no
The address email.
phone
Data type: string
Required: no.
The address phone.
eori_number
Data type: string
Required: Depending on the carrier and recipient country.
Only applicable for recipient address data. Containing the eori number of the recipient.
vat_number
Data type: string
Required: Depending on the carrier and recipient country.
Only applicable for recipient address data. Containing the vat number of the recipient.
7.B.2 Examples
Dutch recipient
Street and number in one field
With company
Belgian recipient
French recipient
Japanese recipient
7.C ShipmentOptions Object Definition
7.C.1 Overview
This object contains the shipment options and is embedded in Shipment.options and ReturnShipment.options.
package_type
Data type: package_type
Required: yes
The package type. For international shipment only package-type 1 (package) (package) is allowed.
delivery_type
Data type: delivery_type
Required: Yes if delivery_date has been specified.
The delivery name for the package.
delivery_date
Data type: timestamp
Required: Yes if delivery name has been specified.
The delivery date time for this shipment.
only_recipient
Data type: boolean
Required: No.
Deliver the package to the recipient only.
signature
Data type: boolean
Required: No.
Package must be signed for.
return
Data type: boolean
Required: No.
Return the package if the recipient is not home.
insurance
Data type: price
Required: No.
Insurance price for the package.
large_format
Data type: boolean
Required: No.
Large format package.
cooled_delivery
Data type: boolean
Required: No.
Cooled_delivery is only valid for cc=NL and with shipment_type 1 or 3.
label_description
Data type: string
Required: No.
This description will appear on the shipment label. Note: This will be overridden for return shipment by the following: Retour – 3SMYPAMYPAXXXXXX
age_check
Data type: boolean
Required: No.
The recipient must sign for the package and must be at least 18 years old.
7.C.2 Example
Parcel with only_recipient, signature, return, age_check and €100,– insurance
Package with signature and €100,– insurance
Package with only_recipient, signature, return and €500,– insurance
Package with only_recipient, signature, and return
Package with pickup and signature
7.D ShipmentGeneralSettings Object Definition
7.D.1 Overview
You can specify shipment general settings with this object. It is embedded in the Shipment .general_settings column.
save_recipient_address
Data type: boolean
Required: No
When this setting is true the recipient address will be saved in the address book. Only for valid for POST request.
delivery_notification
Data type: boolean
Required: No.
When this setting is true the Merchant will receive an email notification when the package has been delivered.
disable_auto_detect_pickup
Data type: boolean
Required: No.
When this setting is true MyParcel do not auto detect pickup addresses.
delivery_notification_email
Data type: array of string
Required: No.
This email addresses that will receive a delivery notification.
printer_identifier
Data type: [printer_identifier] of string
Required: No.
In this field you can enter your printer identifier. This field is also sent with the webhook shipment_label_created. You are responsible for controlling your own printer based on a printer identifier.
7.D.2 Example
All options used
7.E CustomsDeclaration Object Definition
7.E.1 Overview
This object is embedded in the Shipment object for global shipments and is mandatory for non-EU shipments.
contents
Data type: package_contents
Required: Yes.
The name of contents in the package.
invoice
Data type: string
Required: Yes for commercial goods, commercial samples and return shipment package contents.
The invoice number for the commercial goods or samples of package contents .
weight
Data type: integer
Required: Yes.
The total weight for all items in whole grams.
eori_number
Data type: string
Required: Depending on the carrier and recipient country.
The eori number of the sender.
vat_number
Data type: string
Required: Depending on the carrier and recipient country.
The vat number of the sender.
vat_number_uk
Data type: string
Required: Depending on the carrier and recipient country.
The uk vat number of the sender.
items
Data type: array of CustomsItem objects
Required: Yes.
An array containing CustomsItem objects with description for each item in the package.
7.E.2 Example
POST example A
POST example B
7.F CustomsItem Object Definition
7.F.1 Overview
This object contains a declaration for an item in the CustomsDeclaration object.
description
Data type: string
Required: Yes.
The description of the item.
amount
Data type: integer
Required: Yes.
The amount of this item in the package. The minimum amount is 1.
weight
Data type: integer
Required: Yes.
The total weight for these items in whole grams. Between 0 and 20000 grams.
item_value
Data type: price
Required: Yes.
Item value
classification
Data type: isic_code
Required: Yes.
The International Standard Industry Classification code for this item.
country
Data type: country_code
Required: Yes.
The country of origin for this item.
7.F.2 Example
POST example A
POST example B
POST example C
POST example D
7.G ShipmentIds Object Definition
Overview
This object contains an array of ShipmentId objects.
ids
Data type: array of ShipmentId objects.
Required: n/a.
array of ShipmentId objects.
7.H ShipmentId Object Definition
Overview
id
Data type: integer
Required: n/a.
7.I ReturnShipment Object Definition
7.I.1 Overview
You can create a return shipment with this object.
shop_id
Data type: integer
Required: no.
The shop id to which this shipment belongs.
parent
Data type: integer
Required: Yes.
The parent shipment that was initially sent to the consumer.
carrier
Data type: carrier
Required: Yes.
The carrier that will deliver the package.
email
Data type: string
Required: no.
The email address to send the return shipment email to.
name
Data type: string
Required: Yes.
The name to include in the email.
options
Data type: ShipmentOptions
Required: no.
The shipment options. If this is not provided then the default shop return shipment options are used.
general_settings
Data type: ShipmentGeneralSettings
Required: no
You can specify general settings for the shipment with this object. For return shipments only the [printer_identifier] property is accepted.
7.I.2 Example
POST example
7.J UnrelatedReturnShipment Object Definition
7.J.1 Overview
You can create an unrelated return shipment with this object.
shop_id
Data type: integer
Required: No.
The shop id to which this shipment belongs.
carrier
Data type: carrier
Required: Yes.
The carrier that will deliver the package.
email
Data type: string
Required: Yes.
The email to send the return shipment email to.
name
Data type: string
Required: Yes.
The name to include in the email.
sender
Data type: Address
Required: No.
The sender where the package comes from.
options
Data type: ShipmentOptions
Required: No.
The shipment options. If this is not provided then the default shop returnshipment options are used.
general_settings
Data type: ShipmentGeneralSettings
Required: no
You can specify general settings for the shipment with this object. For return shipments only the [printer_identifier] property is accepted.
7.J.2 Example
POST example
7.K DownloadUrl Object Definition
7.K.1 Overview
This is the download URL object.
link
Data type: string
Required: Yes.
The URL to generate an unrelated return shipment
7.K.2 Example
POST example
7.L TrackTrace Object Definition
7.L.1 Overview
This is the Track & Trace object.
shipment_id
Data type: integer
code
Data type: string
description
Data type: description
time
Data type: time
link_consumer_portal
Data type: string
URL for custom Track & Trace page. More information about this service is found here . If the consumer portal is turned off, the carrier tracking page is used. You can also pass a language parameter: ?lang=en_GB .
link_tracktrace
Data type: string
Carrier tracking page
recipient
Data type: Address
sender
Data type: Address
options
Data type: ShipmentOptions
pickup
Data type: PickupLocation
delayed
Data type: boolean
Indicates whether the current event code means the shipment has been delayed.
location
Data type: TrackTraceLocation
status
Data type: TrackTraceStatus
history
Data type: TrackTraceHistory
delivery_moment_type
Data type: string
Depending on the status of the shipment `expected` or `estimated`
delivery_moment
Data type: DeliveryMoment
7.L.2 Example
GET example
7.M TrackTraceHistory Object Definition
7.M.1 Overview
This is the tracktrace history object.
code
Data type: string
Required: n/a.
description
Data type: string
Required: n/a.
time
Data type: time
Required: n/a.
delayed
Data type: boolean
Indicates whether the current event code means the shipment has been delayed.
location
Data type: TrackTraceLocation
7.M.2 Example
GET example
7.N PhysicalProperties Object Definition
7.N.1 Overview
This is the physical properties object, which is required for non-EU and digital stamp shipments. Note: Weight is the only available property for digital stamps ( package_type 4)
carrier_height
Data type: integer
Required: n/a.
carrier_width
Data type: integer
Required: n/a.
carrier_weight
Data type: integer
Required: n/a.
carrier_length
Data type: integer
Required: n/a.
carrier_volume
Data type: integer
Required: n/a.
height
Data type: integer
Required: n/a.
width
Data type: integer
Required: n/a.
length
Data type: integer
Required: n/a.
volume
Data type: integer
Required: n/a.
weight
Data type: integer
Required: n/a.
7.N.2 Example
POST example
7.O PickupLocation Object Definition
7.O.1 Overview
This is the pickup location object.
city
Data type: string
Required: n/a.
location_name
Data type: string
Required: n/a.
number
Data type: string
Required: n/a.
postal_code
Data type: string
Required: n/a.
street
Data type: string
Required: n/a.
location_code
Data type: string
Required: n/a.
retail_network_id
Data type: string
Required: n/a.
7.O.2 Example
POST example for NL pickup location
POST example for BE pickup location
7.P PaymentInstructions Object Definition
7.P.1 Overview
This is the payment instruction object.
id
Data type: string
Required: n/a.
hash
Data type: string
Required: n/a.
invoices
Data type: Invoice
Required: n/a.
name
Data type: integer
Required: n/a.
notification_hash
Data type: string
Required: n/a.
original_notification_hash
Data type: string
Required: n/a.
payment_url
Data type: string
Required: n/a.
paid
Data type: boolean
Required: n/a.
price
Data type: price
Required: n/a.
7.P.2 Example
Example
7.Q Invoice Object Definition
7.Q.1 Overview
This is the invoice object.
id
Data type: integer
Required: n/a.
number
Data type: string
Required: n/a.
status
Data type: integer
Required: n/a.
7.Q.2 Example
Example
7.R ShipmentLabelDownloadLink Object Definition
7.R.1 Overview
This is the shipment label download link object.
url
Data type: string
Required: n/a.
7.R.2 Example
Example
7.S TrackTraceStatus Object Definition
7.S.1 Overview
An object with a current status, main and final.
current
Data type: shipment_status
main
Data type: main
final
Data type: boolean
When `true` no new statuses are expected
7.S.2 Example
Example
7.T DeliveryMoment Object Definition
7.T.1 Overview
An object with a start and end DateTime.
start
Data type: DateTimeStartEnd
end
Data type: DateTimeStartEnd
7.T.2 Example
Example
7.U DateTimeStartEnd Object Definition
7.U.1 Overview
An object with a date, timezone_type and timezone.
date
Data type: timestamp
timezone_type
Data type: integer
timezone
Data type: string
7.U.2 Example
Example
7.V TrackTraceLocation Object Definition
7.V.1 Overview
An object with a location where the Track & Trace event took place. This data is only available when it has been provided by the carrier of the shipment.
name
Data type: string
nullable: false
cc
Data type: string
nullable: true
city
Data type: string
nullable: true
postal_code
Data type: string
nullable: true
street
Data type: string
nullable: true
number
Data type: string
nullable: true
number_suffix
Data type: string
nullable: true
longitude
Data type: float
nullable: true
latitude
Data type: float
nullable: true