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 |
| 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. |
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_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. |
| goods_value_currency | No | string | EUR | The currency of the shipment value. Accepting 3 letter currency codes. |
| cod_reference | No | string | 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
- Get shipment by ID GET /shipments/{id}
- Get shipments collection GET /shipments - retrieve multiple shipments that has previously been imported
- Update shipment PUT /shipments/{id} - update an existing shipment
- Delete a shipment DELETE /shipments/{id}
Note: the given ID within the response when creating a shipment is needed to update or delete it later.