Support Portal

Welcome
Login

1.2. Create shipment

TABLE OF CONTENTS

A shipment resource represents a physical parcel with carrier information and recipient address. It is the primary object that receives tracking updates.

With POST shipments method, you can create a new shipment. 

Parameters

Parameter

Mandatory

Type

Example

Description

order_id 

Yes

string

"1234560001"

The ID of related order

OrderYesJSON{
"order_id": "1234567",
"order_url": "https://www.example.com",
"order_date": "2022-07-14T08:36:53.353Z",
"boarding_complete": true,
"language": "en",
"order_tags": {
  "tag1": "value1",
  "tag2": "value2"
},
"promised_delivery_date": "2022-07-14T08:47:48.787Z"
}
With this order object, an order containing all order information can be created during the label creation process.

Please note: 

"promised_delivery_date" is mandatory if "local_delivery" parameter is true.


tracking_code 

Yes, if reference number is not provided

string

"tracking123456789"

The unique shipment track and trace code given by the carrier

reference_number 

Yes, if tracking code is not provided

string

"ref123456"

The unique reference number that  represents  internal shipment reference in your system.

reference_number_2Nostring"ref654321"The second reference number that can represent additional shipment or order data from your system. Can be both unique or not.  
local_delivery
Noboolean
falseIndicates whether the package is for the special same day or next day delivery service operated by Seven Senders. Please contact us in case you would like to start using it.

If true, "promised_delivery_date" parameter for the order must be provided.


goods_valueNonumber
10.5The shipment value. Accepting numbers with 2 decimals. 
goods_value_currencyNostringEURThe currency of the shipment value. Accepting 3 letter currency codes. 
cod_referenceNostring 12345
Reference for shipments which are delivered with service cash on delivery. 

carrier

Yes

JSON


{

  "name": "dhl",

  "country": "DE"

}


Selected carrier/country to ship the parcel

carrier_service 

No

string | choice:

"standard"

"express"

"other"

"standard"


Service used by the carrier

recipient_first_name 

Yes

string

“David”

Customer’s first name

recipient_last_name 

Yes

string

“Hasselhoff”

Customer’s last name

recipient_email 

Yes

string | email

"d.hasselhoff@example.com"


Customer's email address.


recipient_address 

Yes

string

"Schwedter str. 36A"


Customer’s address. Do not use line breaks. 


If a DHL “Packstation” has been chosen, please state “Packstation” and number (e.g “Packstation 123”)

recipient_zip 

Yes

string

"10435"


Customer’s ZIP code

recipient_city 

Yes

string

“Berlin”

Customer’s city

recipient_country 

Yes

string | country

“DE”

Customer’s country in ISO2 format

recipient_phone 

No

string | phone:

Use + for the country code (see example)

"+490000000001"


Customer's phone number

recipient_company_name 

No

string

“Seven Senders”

Customer’s company name if he/she choose to be delivered at his/her company

return_parcel 

No

boolean

false

Indicates whether the shipment is a return from the customer

pickup_point_selected 

No

boolean


false

A flag to show whether the  customer address is a pickup point (i.e. postal shop, retail shop etc.)

weight 

Yes

number

1.12

Shipment weight in KG (including packaging)

trackable

No

boolean

true

Indicates if a shipment can be  tracked by carriers

planned_pickup_datetime

Yes for outbound, No for return 

datetime


"2017-05-18T22:13:18.933Z"


Date and time agreed with the carrier to pick up the shipment at your warehouse

comment 

No

string

“Please be careful”

Comment regarding this shipment left by the customer or for your internal usage

warehouse_address 

Yes

string

"Kochhannstr. 38 10247 Berlin"


Warehouse full address. Do not use line breaks

warehouse 

Yes

string. | choice:

List of all warehouse

defined inside your account


"warehouse1"


The Warehouse name defined inside your account. Important: the provided warehouse name needs to be identical to the one(s) defined in your Seven Senders Portal account 

shipment_tag 

No

JSON


{ "tag1": "value1", "tag2": "value2" }


Tags/Properties to allow you to segment your shipments

Order Object 

With this order object, an order containing all order information can be created during the label creation process. When we perform request validation we will check:

  • If order_id is defined and valid, we will accept this value and accept the request. Else, 
  • If order_id is not defined, then we will check if the order_id is defined under the order object and has valid fields. If yes accept the request and take the value from here, else
  • If none of them are defined or invalid we will throw a validation exception as it is today.

Tracking Code

For most cases, a tracking code is always provided in advance by a carrier. We require this data to track a shipment. In exceptional cases, this code can be skipped from a request and substituted with a reference number.

Reference Number

As mentioned above, a reference number can be an addition or substitute to a tracking code, depending on a carrier.

Carrier

The carrier parameter contains a pair of carrier name and country. These values are predefined. You can receive them via GET carrier API request. Learn more here: Available carriers page

Recipient Email

The recipient email is mandatory. This data is required to enable the Notifications and Claims service.

Trackable

This flag helps to mark shipments that cannot receive tracking events. For these, the tracking timeline in Notifications and Tracking pages must get built differently. Please see: Displaying non-trackable shipments on the Tracking Page

Planned Pickup Datetime

This timestamp triggers the start of the delivery lead time.

It is an essential data point to be used to calculate various KPIs within Seven Senders Analytics. We highly advise you to provide it, taking into account cut-off times, weekends, etc. When using Seven Senders delivery, state the with Seven Senders agreed on pickup time.

Warehouse and warehouse address

These fields should contain existing values from our system. To use the correct values, please request the list of defined warehouses using GET warehouses endpoint. 


Other shipment operations

Note: the given ID within the response when creating a shipment is needed to update or delete it later.


Did you find it helpful? Yes No