Support Portal

Welcome
Login

1.3. Create and download label

TABLE OF CONTENTS

Create a label

Carrier Labels are created by using the POST labels method.

Parameters


Parameter

Mandatory

Type

Example

Description

order_id
Yes*
string
'123456000001'
The ID of the related existing order. Parameter to be used when order is being created with a separate order post
order
Yes*

JSON

{
"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"
}

// For the Zalando SLA calculation via Analytics, please refer to the information in section 'Zalando SLA calculation via Analytics'
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.


format
No
string | choice ('pdf', 'zpl', 'zpl300')
'pdf'
The expected label format
carrier
Yes
JSON
{
"name": "dhl",
"country": "DE"
}

Selected carrier/country to ship the parcel.
recipient_first_name
Yes
string
'David'
Customer’s first name [1]
recipient_last_name
Yes
string
'Hasselhoff'
Customer’s last name [1]
recipient_email
Yes
string
'mail@example.com'
Customer's email address [1]
recipient_street
Yes
string
'Schwedter Str.'
Customer’s street. Do not use line breaks [1]
recipient_house_no
No
string
'36A'
Separate field for house number of customer sending address. [1]
recipient_zip
Yes
string
'10435'
Customer’s ZIP code [1]
recipient_city
Yes
string
'Berlin'
Customer’s city [1]
recipient_country
Yes
string
'DE'
Customer’s country in ISO2 format [1]
recipient_phone
No
string | phone
'+49000000000'
Customer’s phone number [1]
recipient_company_name
No
string
'Seven Senders'
Customer’s company name [1]
recipient_address_details




sender_first_name
No
string
'Peter'
Sender’s first name
sender_last_name
No
string
'Lustig'
Sender’s last name
sender_company_name
No
string
'ABC GmbH'
Sender’s company
sender_street
No
string
'Keplerstr.'
Sender’s street
sender_house_no
No
string
'47B'
Sender’s house number
sender_zip
No
string
'68165'
Sender’s ZIP code
sender_city
No
string
'Mannheim'
Sender’s city
sender_country
No
string
"DE"
Sender's country in ISO2 format.

sender_phone
No

string | phone
'+49000000000'
Sender' phone number

sender_email
No
string | email
'p.lustig@abcd.de'
Sender's email address
return_parcel
No
string | choice (outbound,  return, both)

'outbound'
The field shows whether a return label or a combination  is requested
weight
Yes
float
1.12
Shipment weight in kg (including packaging)
reference_number
Yes
string
'Order Reference 1234'
Unique reference number per parcel (shown on the outbound label)
reference_number_2
No
string
"ref654321"
The second reference number that can represent additional shipment or order data from your system. Can be both unique or not.
local_delivery
No
boolean
false
Indicates 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_value
No
number
10.5
The shipment value. Accepting numbers with 2 decimals.
planned_pickup_datetime
No
datetime
2017-05-18T22:13:18.933Z
Date and time agreed with the carrier to pick up the shipment at your warehouse
goods_value_currency
No
string
EUR
The currency of the shipment value. Accepting 3 letter currency codes.
warehouse
No
string | choice List of all warehouses 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.
warehouse_address
No
string
"Kochhannstr.38 10247 Berlin"
Warehouse full address. Do not use line breaks.
shipment_tag
No
JSON
{ "tag1": "value1", "tag2": "value2" }
Tags/Properties to allow you to segment your shiop
carrier_service
Yes
string
'standard'
field to indicate carrier services. Please set it to 'standard' if not other option advised by Seven Senders
cod
Yes
boolean
false
The indicator of cash on delivery payment to be collected via this shipment
cod_value
No
float
13.65
COD value to be collected by carrier on parcel delivery. In case field 'cod' is set to true, this field must be filled with a value >0
cod_currency    
No
string
'EUR'
The currency in which COD value has to be collected
cod_reference    
No
string
'12345'
Reference for shipments which are delivered with service cash on delivery.
collection_point_name1
No
string
Royal Mail
Address parameter to specify the naming of a specific carrier "PickUpPoint" location    
collection_point_name2
No
string
Post Office Ltd
Address parameter to specify the naming of a specific carrier "PickUpPoint" location    
collection_point_name3
No
string
Sheffield South Delivery Office
Address parameter to specify the naming of a specific carrier "PickUpPoint" location    
collection_point_
membership_id
No
string
12345678
Carrier specific parameter (e.g. DHL DE)
collection_point_street
No
string
Woodseats Rd
Address parameter to specify "PickUpPoint" street
collection_point_house
_no
No
string
61
Address parameter to specify "PickUpPoint" house number (can also be provided in collection_point_street)
collection_point_country
No
string
GB
Address parameter to specify "PickUpPoint" country
collection_point_zip
No
string

S80 PG
Address parameter to specify "PickUpPoint" zip code
collection_point_city
No
string

Sheffield
Address parameter to specify "PickUpPoint" city
dimensions
No
JSON
{
"height": 50,
"length": 40,
"width": 30
}
Parcel dimensions in cm
carrier_service_id
No*
string
UUID
This parameter is only required for specific carriers:
  • If the carrier in scope only supports one delivery service, then the "carrier_service_id": needs to be sent with null, since we have configured a default
  • If the carrier in scope supports N delivery services, then the required service needs to be specified by providing the "carrier_service_id" (will be provided by our integration team)
service_parameters
No
JSON
{
"destination": "string", "speed": "string", "service_group": "string", "enhancements": ["string"]
}
This parameter is currently not in use, please provide as null

pudo_id
No
string
'1000001'
The ID of a PUDO point selected by the customer

[1] When creating a stand-alone return label, the recipient parameters need to be filled in with the sender of the return shipment, since 7S will automatically switch the address at the point of label creation.

Format

The format of the result label file. Supported values are: 'pdf', 'zpl', 'zpl300'. The 'zpl' option returns a 203 DPI ZPL, while 'zpl300' returns a 300 DPI ZPL file. The recommended format is zpl.

Order ID

The order should be created via API before generating a label.

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.

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

Recipient Email

This field is required for last-mile carriers and also to enable the Notifications and Claims service.

Recipient Phone

Typically, this field is not mandatory. Depending on the selected carrier services, this might be relevant.

Sender Address

Senders address fields are not mandatory, by default this data is stored in the configuration on Seven Senders side.

Return Parcel

The field may contain one of the following options: 

  • 'outbound' - to generate an outbound label. 
  • 'return' - to generate a return label only. 
  • 'both' - both outbound and matching return labels are generated. The response will contain an array in this case.

Cash on delivery (COD)

If set to true, fields cod_value (amount) and cod_currency (currency code) fields become mandatory.

Pickup/Drop-off Point (PUDO)

In the case of delivery to a PUDO (pick up - drop off) point, it depends on the carrier whether the full collection point addresses + pudo_id or just the PUDO ID needs to be provided.

For certain carriers, we have to possibility to automatically select the nearest PUDO point based on the provided address parameters. For more information, please refer to the table below:


Carrier
Required PUDO parameters
Full collection point address required
PUDO ID required
PUDO "auto-select" available
Post Nord
NO
YES
YES
Bring
YES
YES
NO
Mondial Relay
NO
YES
YES
Royal Mail 
YES
NO
NO
Inpost
NO
YES
NO
SEUR
NO
YES
YES
Post NL 
NO
YES
YES
BRT
NO
YES
NO


Dangerous Goods Labels

When using Dangeorus Goods Services, certain carriers require supplementary details regarding the SKUs and the nature of the dangerous goods. In these instances, the following parameters must be provided.


ParameterMandatoryTypeExampleDescription
parcelyesobject

parcel.descriptionnostring'B2C
Parcel'
description of the parcel
parcel.skusyesarray
with object


parcel.skus.
arrival_country_description
yesstring'silicone case
for mobile phone'
SKU description
parcel.skus.qtyyesnumber3quantity of SKUs in the parcel
parcel.skus.
total_net_weight
Cfloat3.4total net weight of all SKUS in the parcel
parcel.skus.total_gross_weightCfloat

parcel.skus.dangerous_goodsyesarray
with object


skus.dangerous_goods.
un_number
yesstring'2037'UN Numbers standartize the identification of dangerous goods
skus.dangerous_goods.
technical_name
depends on the carrierstring'liquid silicone
polymer'
When a UN number like "UN1993, Flammable liquid, n.o.s." is used, the technical name (e.g., "Toluene and Benzene mixture")
skus.dangerous_goods.
hazard_class
depends on the carrierstring'2.2'Hazard Class determines the primary risk associated with the substance
skus.dangerous_goods.
additional_hazard_id
depends on the carrier
string
'B4'Subsidiary hazards are often indicated by subsidiary risk labels and can influence handling, stowage, and emergency response procedures.
skus.dangerous_goods.
packing_group
depends on the carrierstring'III'The Packing Group determines the type and performance level of packaging required for safe transport.
skus.dangerous_goods.
packing_instruction_code
depends on the carrierstring'P1965_
SECTION
_IA'
Packing Instructions specify authorized packaging types (e.g., drums, boxes, IBCs) and any additional packaging requirements based on the UN Number and Packing Group.
skus.dangerous_goods.
flash_point
depends on
the carrier
string'-20'Flash point is a key property for classifying flammable liquids and determining appropriate handling, storage, and transport precautions.
skus.dangerous_goods.
tunnel_code
nostring'(E)'This code (e.g., B/D, C, E) must be considered by drivers and shippers to ensure they do not enter tunnels where the transport of their specific dangerous goods is prohibited.
skus.dangerous_goods.
liqiud_volume
depends on the carrierobject

skus.dangerous_goods.
liqiud_volume.unit
depends on the carrierstring'FL_OZ'
The unit of the quantity of a liquid dangerous good being transported. Liters (L) or milliliters (mL).
skus.dangerous_goods.
liqiud_volume.value
depends
on the
carrier
float3.0The quantity of a liquid dangerous good being transported, typically measured in liters (L) or

If a label is required for a DG shipment, these parameters (depending on the carrier) must be transferred to the Seven Senders API. These parameters are added to the parameters described above.

Download a label

Once a label was requested, you can download it using GET label-download method with label ID as a parameter received after the label creation. The method with return a file in PDF or ZPL format.


Delete label

In case a label is no longer needed you can use the Delete Label request with a label ID as parameter. This method will delete the label and automatically delete the shipment behind the label.


Zalando SLA calculation via Analytics

To visualise Zalando SLAs via Analytics, the delivery country for the order must be included in the order tags. To achieve this, please use the order tag outlined in the 'Create a Label' section and enter the relevant order data as follows:

"order_tags": 
{ "7S_destination:": "pl" }, 

The tag name is always '7S_Destination' and the value should be the ISO 2 country code.

Tag nameExampleDescription
7S_destination'pl'ISO2 Country Code of the order destination

The complete order tag would look like this - example:

{
"order_id": "1234567",
"order_url": "https://www.example.com",
"order_date": "2022-07-14T08:36:53.353Z",
"boarding_complete": true,
"language": "en",
"order_tags": {
"7S_destination": "pl",
"tag2": "value2"
},
"promised_delivery_date": "2022-07-14T08:47:48.787Z"
}

Did you find it helpful? Yes No