This section covers all information needed to connect to Seven Senders via API when using the Seven Senders Delivery Service in combination with My7S Labels and the optional Seven Senders Portal.
- In General - Workflows
- Create an Order
- Update the state of an order
- Create a My7S Labels
- Update an order to provide us with the “boarding complete” information
- Additional Operations
In General - Workflows
After providing 7S with the above-mentioned data, 7S is retrieving the shipment updates from the carriers and update them.
The minimum workflow is only recommended when using solely our Delivery service!
By applying the minimum workflow the data is not sufficient to utilize all features of Seven Senders Portal such as monitoring data on order-level, sending customer notifications (email/sms) based on order-events etc.
In the following, the optimum workflow is described step-by-step. Head directly to Create a My7S Labels if you provide 7S with shipment information only.
Create an Order
Orders are created by using the POST operation of the 'order' endpoint (POST/order).
Parameters
Parameter | Mandatory | Type | Example | Description |
order_id | Yes | String | "order123456" | The order reference inside your system |
order_url | Recommended | String | At which website the order was submitted | |
order_date | Yes | String (dd.mm.yyyy hh:mm:ss) | "2017-08-15T16:53:07+01:00" | The Date when the order was created inside your system |
boarding_complete | No | boolean [true or false] | “False” | Information indicating (if an order consists of multiple parcels) that all shipments of an order have been imported |
boarding_complete | No | boolean [true or false] | “False” | Information indicating (if an order consists of multiple parcels) that all shipments of an order have been imported (cf. for this 'Update an order to provide us with the boarding complete information') |
language | Recommended | Array[string] | “en” | What is the language of the customer for this order or the language for the shop_order_url defined. If you intent to send mails/sms notifications to your customers, we recommend that you provide this information for each order. The reason is that a notification can only be send if the shop_order_url and the Language are defined on the order |
order_tags | No | Array[string] | “SKU 1234” | Tags/Properties to allow you to segment your orders |
promised_delivery_date | Recommended | String | "2017-08-15T16:53:07+01:00" | The delivery date you’ve promised the customer. The promised_delivery_date is an important parameter* (cf. comment below the table) |
*Promised_delivery_date: Fundamental information since it’s used as input to calculate various KPI’s within Seven Senders Portal. Therefore, we highly advise you to provide this information in an acceptable accuracy.
Available Languages
| Languages | For short |
| bg | |
| Czech | cs |
| da | |
| German | de |
| el | |
| English | en |
| Spanish | es |
| et | |
| Finnish | fi |
| French | fr |
| ga | |
| hr | |
| Hungarian | hu |
| Italian | it |
| lt | |
| lv | |
| mt | |
| Polish | pl |
| pt | |
| ro | |
| Russian | ru |
| sk | |
| Slovak | sl |
| sv | |
| uk |
bg; cs; da; de; el; en; es; et; fi; fr; ga; hr; hu; it; lt; lv; mt; pl; pt; ro; ru; sk; sl; sv & uk
Further Order Operations Available
- GET/orders/{id} → retrieve a single order that has previously been imported
- GET/orders → retrieve multiple orders that have previously been imported
- PUT/orders/{id} → updates (partially) an existing order
DELETE/orders/{id} → delete one or multiple existing order/orders (Operation coming soon)
Note: the given ID within the response when creating an order is needed to update or delete an order.
Update the state of an order
You’re able to update the state of an order via the POST/order-states (Operation coming soon) operation.
Parameters
Parameter | Mandatory | Type | Example | Description |
order_id | Yes | String | "order123456" | The order reference inside your system |
state | Yes | Choice: See tabel below | “paid” | The current state of the order |
datetime | Yes | String (dd.mm.yyyy hh:mm:ss) | "2017-08-15T16:53:07+01:00" | The date and time |
location | No | String | "Schwedter strasse 36A 10435 Berlin" | The physical location of the order |
Order-states
The table below contains the different available order-states.
Status | Description |
new | Status when the order is imported |
paid | Order was paid by the customer |
in_production | This status is useful if you need to produce/made the item ordered by the customer |
In_preparation | The order is processed inside your warehouse |
Create a My7S Label
My7S Labels are created by using the POST operation of the 'label' endpoint (Post/labels).
Parameters
Parameter | Mandatory | Type | Example | Description |
order_id | Yes | String | "order123456" | The order reference inside your system. The shipment will be link to this order. Alternatively, you can provide us an unique Id (in case you’re applying the minimum workflow = solely providing shipment data) |
carrier: | ||||
carrier.carrier_name | yes | choice: See the list of choice below | “7S” | For My7S Label, please always put “7S” as carrier.carrier_name |
carrier.carrier_country | yes | choice: See the list of choice below | “DE” | For My7S Label, please always provide here the recipients country |
recipient_first_name | Yes | String | “David” | Customer’s first name |
recipient_last_name | Yes | String | “Hasselhoff” | Customer’s last name |
recipient_email | Yes | "d.hasselhoff@sevensenders.com" | Customer’s email address Send email notifications to you customer through Seven Senders Portal Without this information, no mail notification can be send. In case you’re only using our delivery product, you can provide a “default” email-address (e.g. cs@yourcompany.de) | |
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 | “de” | Customer’s country. Use ISO 3166-1 alpha-2 |
recipient_phone | No | phone: Use + for the country code (see example) | "+4915224565981" | Customer’s phone number. Use this field to send sms notifications to your customer through Seven Senders Portal Without this information, no sms notification can be send. Note: this is a paid feature. If you’re interested in sending sms to your customers - please get in contact with us |
recipient_company_name | No | String | “Seven Senders” | Customer’s company name if he/she choose to be delivered at his/her company. |
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. Use ISO 3166-1 alpha-2 |
sender_phone | No | phone: Use + for the country code (see example) | "+4917621253654" | Sender's phone number |
sender_email | No | “p.lustig@abcb.de | Sender’s email address | |
return_parcel | No | boolean [true or false] | “false” | Indicates whether the shipment is a return from the customer |
weight | Yes | number | 1.12 | Shipment weight in KG (including packaging) |
The response of posting a shipment contains the My7S Label!
Shipment statuses
After creating a label, a shipment is automatically created inside your account. Seven Senders will then update the status of the shipment's based on information received from the carrier. A shipment can have the following status:
Status | Description |
New | The shipment has been created inside your Seven Senders account |
Info | The carrier has received the shipment information into his system |
Pickup | The shipment has been picked up by the carrier at your warehouse |
Hub scan at LMC | The Last Mile Carrier has scanned your shipment inside his hub |
Out for delivery | The Last Mile Carrier went to deliver the shipment to the customer |
Delivered to pickup point | The shipment has been delivery to a third party |
Delivered | The shipment was succesfully delivered to the customer |
Lost | The shipment has been lost |
Further Shipment Operations Available
- GET/shipments/{id] → retrieve a single shipment that has previously been imported
- GET/shipments → retrieve multiple shipments that has previously been imported
- PUT/shipments/{id} → updates completely or partially an existing shipment
- DELETE/shipments → delete one or multiple existing shipments (operation coming soon)
Note: the given ID within the response when creating an shipment is needed to update or delete an order.
Update an Order to Provide the 'boarding complete' Information
Whenever all items of an order have been shipped and the corresponding shipments were created inside the Seven Senders Portal account, you need to provide us this information by using the PUT/orders/{id} operation. Through the PUT/orders/{id} operation you have to update the 'boarding_complete' parameter. The parameter value needs to be changed from 'False' (not all items shipped”) to 'True' (all items shipped).
Note: updating the “boarding_complete” parameter is important since this information is required to transfer an order (once all shipments have been delivered) to the state 'Completed':
- If boarding complete = true (or null) and all shipments are delivered → order completed
- If boarding complete = true (or null) and 1 shipment is delivered → order NOT completed
- If boarding complete = false and 1 shipment created in delivered → order NOT completed
- If boarding complete = false and all shipment created in delivered → order NOT completed
Additional Operations
The following operations, provide you further information.
- GET/carriers → retrieve all carriers available to create shipments in the Seven Senders system
- GET/shipments/{id}tracking_history→ retrieve all events for a given shipment inside your Seven Senders account.
- GET/warehouse → manage you warehouses used inside your Seven Senders account (operation coming soon)