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
| '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 |
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.
