Support Portal

Welcome
Login
  1. Solution home
  2. API Data Integration
  3. API Endpoints

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"
}		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
'[email protected]'
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
'[email protected]'
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



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.


Did you find it helpful? Yes No