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 |
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" | 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 | "mail@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 warehouses defined in 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 account in Seven Senders Portal |
shipment_tag | No | JSON | { "tag1": "value1", "tag2": "value2" } | Tags/Properties to allow you to segment your shipments |
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
A reference number is required when a tracking code can not be provided, 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: Available carriers page
Recipient Email
The recipient email is mandatory. This data is required to enable Claims service.
Trackable
This flag helps to mark shipments that cannot receive tracking events. By default, it's set to true.
Planned Pickup Datetime
This timestamp triggers the start of the delivery lead time. When using Seven Senders delivery, please set the pickup time from your agreement.
Warehouse and warehouse address
These fields should contain existing values from our system. 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.