Support Portal

Welcome
Login

Shipments

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
1
2
3
4
5
6
7
"carrier": {  
    "name""dhl",  
    "country": {    
        "name""Germany",    
        "iso2""de"  
    }
}
Information regarding the carrier responsible for delivering the shipment
carrier.name
string
"dhl"
Carrier name
carrier.country
object
Country object
1
2
3
4
"country": {  
    "name""Germany",  
    "iso2""de"
}
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
1
2
3
4
"customer_address_country": {  
    "name""Germany",  
    "iso2""de"
}

customer_address_country.name
string
"Germany"
Country name
customer_address_country.iso2
string
"de"
Country ISO 2 code
warehouse
object
Warehouse object
1
2
3
4
5
6
7
"warehouse": {  
    "name""warehouse",  
    "country": {    
        "name""Germany",    
        "iso2""de"  
    }
}
Warehouse information that handled the shipment
warehouse.name
string
"warehouse"
Warehouse name
warehouse.country
object
Country object
1
2
3
4
"country": {  
    "name""Germany",  
    "iso2""de"
}
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
email
"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