This endpoint allows you to manage your shipments inside your Seven Senders account.
Endpoint
https://api.sevensenders.com/v2/docs.html#/Shipment/postShipmentCollection
Headers
| Parameter | Mandatory | Description |
| API-KEY | YES | Your authorization key to access Seven Senders API |
Methods
GET
Filters
| Parameter | Mandatory | Type | Example | Description |
limit | NO | number | 20 | How many shipments to return |
offset | NO | number | - | Offset from which to start listing shipments |
order_by | NO | array of fields | - | Order by fields |
Request
Curl example
curl -X "GET" -H "Accept:\ application/json" -H "Content-type:\ application/x-www-form-urlencoded" -H "API-KEY:\ <API-KEY>" http://api.sevensenders.com/v2/shipments.json?limit=20
Response
The API will respond with an array of shipments, each element inside the array has the following properties
| Field | Type | Example | Description | ||
shop_order_id | string | "123456789" | The order reference inside your system | ||
carrier_service | string | "standard" | The service level provided by the carrier | ||
warehouse_address | string | "Kochhannstrasse 38 10249 Berlin" | Your warehouse address | ||
id | number | 987654321 | The shipment id inside Seven Senders system | ||
tracking_code | string | "trackingNumber123" | The tracking number given by the carrier for the shipment | ||
customer_first_name | string | "David" | Customer first name | ||
customer_last_name | string | "Hasselhoff" | Customer last name | ||
customer_name | string | "David Hasselhoff" | Fusion of the customer first and last name | ||
customer_email | email address | "david.hasselhoff@sevensenders.com" | Customer email address | ||
customer_address | string | "Schwedter Str. 36 A" | Customer address | ||
customer_company | string | "Seven Senders" | Customer company name for the delivery | ||
customer_address_zip_code | string | "10435" | Customer ZIP code | ||
customer_address_city | string | "Berlin" | Customer city | ||
customer_phone | string | "+4917680102975" | Customer phone number | ||
return_parcel | boolean | false | Is this shipment a return or not ? | ||
| trackable | boolean | true | Indicates if a shipment is trackable. By default set to true. Setting this parameter is prerequisite for displaying information on the Tracking Page and/or Embedded Widget in case of non-trackable shipments | ||
pickup_point_selected | boolean | false | Is the customer address a pick point address ? | ||
weight | number | 1.12 | Shipment weight in kg | ||
planned_pickup_datetime | date: dd.mm.yyyy hh:mm:ss | "2017-08-19T15:47:00+0000" | The date and time when the carrier is supposed to pick up the shipment at your warehouse | ||
comment | string | "There are many children out there that wish to meet me." | Customer comment regarding the shipment delivery | ||
carrier | object | Carrier object
| Information regarding the carrier responsible for delivering the shipment | ||
carrier.name | string | "dhl" | Carrier name | ||
carrier.country | object | Country object
| Carrier country information | ||
carrier.country.name | string | "Germany" | Country name | ||
carrier.country.iso2 | string | "de" | Country ISO 2 code | ||
customer_address_country | object | Customer address country object
| |||
customer_address_country.name | string | "Germany" | Country name | ||
customer_address_country.iso2 | string | "de" | Country ISO 2 code | ||
warehouse | object | Warehouse object
| Warehouse information that handled the shipment | ||
warehouse.name | string | "warehouse" | Warehouse name | ||
warehouse.country | object | Country object
| Warehouse country information | ||
warehouse.country.name | string | "Germany" | Country name | ||
warehouse.country.iso2 | string | "de" | Country ISO 2 code | ||
shipment_tag | array of tag object | {"tag1":"value1","tag2":"value2"} See tag object | List of all tags for the shipment | ||
reference_number | string | "referenceNumber123456" | Reference number for the shipment. This information is used when the carrier doesn't provide a tracking number at the beginning (like BRT carrier in Italy). It is normally your internal reference for this shipment inside your IT system. | ||
shipment_status_history | array of status object | See status object | List of all past status of the shipment |
Status object
| Field | Type | Example | Description |
date_time | date: dd.mm.yyyy hh:mm:ss | "2017-08-16T09:01:00+0000" | Date and time when the shipment status changed |
name | string | "Delivered" | Status name |
Location | string | "Kochhannstrasse 38 10249 Berlin" | Where did the shipment status changed |
Tag object
| Field | Type | Example | Description |
value | string | "VIP" | Tag value |
name | string | "tag1" | Tag name |
Response
Response to a GET shipments call
[{
"shop_order_id": "123",
"carrier_service": "standard",
"warehouse_address": "Kochhannstrasse 38 10249 Berlin",
"id": 4635805,
"tracking_code": "trackingCode2",
"customer_first_name": "David",
"customer_last_name": "Hasselhoff",
"customer_name": "David Hasselhoff",
"customer_email": "d.hasselhoff@sevensenders.com",
"customer_address": "Hohenschönhauser Str. 22",
"customer_address_zip_code": "10369",
"customer_address_city": Berlin,
"customer_phone": "+4917680102975",
"return_parcel": false,
"pickup_point_selected": false,
"weight": 1,
"planned_pickup_datetime": "2017-08-19T15:47:00+0000",
"comment": "Please be careful!",
"carrier": {
"name": "dhl",
"country": {
"name": "Germany",
"iso2": "de"
}
},
"customer_address_country": {
"name": "Germany",
"iso2": "de"
},
"warehouse": {
"name": "warehouse",
"country": {
"name": "Germany",
"iso2": "de"
}
},
"shipment_tag": [],
"reference_number": null,
"customer_company": null,
"shipment_status_history": [{
"date_time": "2017-08-19T15:47:00+0000",
"name": "Pickup",
"location": ""
}]
}]POST
Parameters
| Parameter | Mandatory | Type | Example | Description |
customer_first_name | YES | string | "David" | Customer first name |
customer_last_name | YES | string | "Hasselhoff" | Customer last name |
customer_email | YES | "d.hasselhoff@sevensenders.com" | Customer email address. Use this field to send email notifications to you customer through Analytics Without this information, no mail notification can be send | |
customer_phone | NO | phone: Use + for the country code (see example) | "+4915224565981" | Customer phone. Use this field to send sms notifications to your customer through Analytics Without this information, no sms notification can be send |
customer_address | YES | string | "Schwedter str. 36A" | Customer address. Do not use line breaks. |
customer_address_zip_code | YES | string | "10435" | Customer ZIP code |
customer_address_city | YES | string | "Berlin" | Customer city |
customer_address_country | YES | string | "de" | Customer country. Use ISO 3166-1 alpha-2 |
carrier_service | NO | choice: "standard" "express" "other" | "express" | Service / Product / Tariff used by the carrier |
return_parcel | NO | boolean: 0 = false 1 = true | 0 | Indicates whether the shipment is a return from the customer |
pickup_point_selected | NO | boolean: 0 = false 1 = true | 0 | Is the customer address a pickup point ? |
weight | YES | number | 1.12 | Shipment weight in KG |
planned_pickup_datetime | YES | date: dd.mm.yyyy hh:mm:ss | "2017-08-19T15:47:00+0000" | Date and time agreed with the carrier to pick-up the shipment at your warehouse - this timestamp triggers the start of the delivery lead time |
comment | NO | string | "Please be careful" | Comment regarding this shipment left by the customer or for your internal usage |
warehouse_address | NO | string | "Kochhannstr. 38 10247 Berlin" | Warehouse full address. Do not use line breaks. |
shop_order_id | YES | string | "order123456" | The order reference inside your system. The shipment will be link to this order. |
warehouse | YES | choice: List of all warehouse defined inside your account | "warehouse" | Warehouse name defined inside your account. |
shipment_tag | NO | object | {"sku":"nikeAir2017"} | Tags/Properties to allow you to segment your shipments |
tracking_code | MAYBE | string | "tracking123456789" | The shipment tracking number given by the carrier. Mandatory if no reference number is provided |
carrier | MAYBE | choice: See the list of choice below | "dhl" | Selected carrier to ship the parcel. Mandatory if a tracking number is provided |
carrier_country | MAYBE | choice: See the list of choice below | "de" | Country where the parcel is handed over to selected carrier / scanned for the first time by the selected carrier. Mandatory if a tracking number is provided |
reference_number | MAYBE | string | "ref123456" | Reference number for the shipment. This information is used when the carrier doesn't provide a tracking number at the beginning (like BRT carrier in Italy). It is normally your internal reference for this shipment inside your IT system. Mandatory if no tracking code is provided |
customer_company | NO | string | "Seven Senders" | Customer company if he/she choose to be delivered at his/her company |
How to define the carrier in case of cross border shipment?
You want to deliver products to a customer in France and your warehouse is in Germany. You will hand your shipment to DHL DE that will at the border handover those shipments to DHL FR.
In this scenario, you need to define on those shipments the carrier dhl and the carrier country de.
Carriers by country available
| Country | Carrier |
| at | postat, dpd, ups, dhl |
| be | bpost, dpd, kiala, mondialrelay, ups, dhl |
| ch | swisspost, dpd, ups, dhl |
| cz | ceskaposta, dpd, ups |
| de | dhl, deutschepost, gls, ups, hermes, dpd, tnt |
| dk | postnord, ups, dhl, dpd |
| es | correos, seur,seur_international,asm, mrw, ups, dhl |
| fi | posti, postnord, ups, dhl, dpd |
| fr | colissimo, chronopost, tnt, dpd, mondialrelay, colisprive, gls, dhl, ups |
| gb | royalmail, yodel, parcelforce, hermes, dpd, dhl |
| it | brt, tnt, gls, ups, dhl |
| lu | dhl, ups, kiala, dpd |
| nl | postnl, kiala, dpd, mondialrelay, tnt, ups, dhl |
| no | postnord, ups, dhl, dpd |
| pl | dpd, gls, ups, dhl |
| se | postnord, ups, dhl |
| sk | ceskaposta, dpd, ups, dhl |
Request
Curl example
curl -X POST \ http://api.sevensenders.com/v2/shipments.json \ -H 'api-key: <API-KEY>' \ -H 'cache-control: no-cache' \ -H 'content-type: application/x-www-form-urlencoded' \ -H 'postman-token: b7c7dfed-1b2c-428e-c66a-ac54da0accca' \ -d 'tracking_code=trackingCode2&shop_order_id=200&customer_first_name=Babar&customer_last_name=Terminator&customer_email=l.laakmann%40sevensenders.com&customer_phone=+4917680102975&customer_address=Hohensch%C3%B6nhauser%20Str.%2022%2010369%20Berlin&customer_address_zip_code=10369&customer_address_country=DE&carrier_service=standard&return_parcel=0&pickup_point_selected=0&weight=1&planned_pickup_datetime=2017-08-19T16%3A47%3A00%2B01%3A00&comment=Please%20be%20careful!&warehouse_address=Kochhannstrasse%2038%2010249%20Berlin&carrier=dhl&carrier_country=DE&warehouse=warehouse'
Response
Response headers
201 success status: 201 date: Wed, 30 Aug 2017 07:27:25 GMT cache-control: no-cache, private server: nginx location: /v2/shipments/4417096 content-type: application/json