HomeAPI Reference7. 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.

sender
Data type: Address
Required: n/a.
The sender of the package. This field is never set.

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.

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.

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.

7.B.2 Examples

Dutch recipient

Street and number in one field

With company

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.

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.

Shipment .id

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

7.V.2 Example

Example

Edit this page
Last updated: 
Contributors Richard Perdaan