This section covers all information needed to connect to the Seven Senders API when using the Seven Senders Delivery Service in combination with with Return Portal Pro, Order Items and Products.
For information about how to connect to the Seven Senders API when using the Seven Senders Delivery Service in combination with the Return Portal, which only requires the standard Seven Senders integration, please see the support articles under API data integration.
TABLE OF CONTENTS
- Supported Workflows:
- Create Product Library
- Create an Order
- Create Order Items
- Create a Shipment
- Update Order Item with Shipment_id
- Push Shipment Event
- API Response Codes
Supported Workflows:
For the return portal, the customer needs to push the order items belonging to one order and will be later updated to one shipment. If the order items are delivered, the consumer can select the order item for return. Before that, the customer needs to push the product, resource and product image so that the product library can be created in the system. Each order item is linked to one product that contained the master data.
Create Product Library
Post a Product
Product is created by using the POST operation of the Product endpoint (POST/Product).
Definitions
| Parameter | Type | Example | Description | Mandatory |
| sku | String | "QA_SKU_2020-07-31_091254" | SKU of product in the warehouse. Unique ID on a product level. | Yes |
| customs_description | String | "Customs Description" | The description of the product which is used for custom clearance | No |
| customs_item_value | String | "500" | The value of the product | No |
| customs_tariff_code_ sending_country | String | "Germany " | Set by the shop | No |
| customs_tariff_code_ receiving_country | String | "United Kingdom " | Set by the shop | No |
| customs_origin_country_iso2 | String | "de" | No |
Update Product Image
Product image is created by using the PUT operation of ProductImage endpoint (PUT/ProductImage)
 The product image attachment has to be Base64 form. Convert the product image into Base64 and then fill in the table. |
Definitions
| Parameter | Type | Example | Description | Mandatory |
| sku | String | "QA_SKU_2020-07-31_091254" | SKU of the shop in the warehouse. Unique ID on a product level. | yes |
| attachment | String | NA | The base64 encoded data of the image file(PEG and PNG are allowed | yes |
| filename | String | "TestImage.png" | The name of the image | yes |
 If the product "SKU" is not existing in the Seven Senders’ database, the product image will not display in the consumer-facing return portal page. Seven Senders creates a new "SKU" in this case. |
The ideal size of the image is as displayed below:
Create an Order
Orders are created by using the POST operation of the Order endpoint (POST /Order).
|
Definitions
| Parameter | Type | Example | Description | Mandatory |
| order_id | String | "QA_order_2020_07_31_091340" | The order reference inside your system | Yes |
| order_url | String | http://7s.com | On which website the order was submitted. Used to map an order to localize | Recommended |
| order_date | String (dd.mm.yyyy.hh:mm:ss) | "2020-07-31T07:00:00+0000"> | The date when the order was created in your system | Yes |
| boarding_complete | boolean [true of false] | "False" | Information indicating (if an order consists of multiple parcels) that all shipments of an order have been imported | No |
| Language | Array [string] | "en" | The language of the customer in this order of the language for the shop_order_url defined. If you intend to send mails/SMS notifications to your consumers, we recommend that you provide this information for each other. The reason is that a notification can only be sent if the shop_order_url and the Language are defined in the order. | Recommended |
| order_tags | Array [string] | {"tag 1":"test" } | Tags/Properties to allow you to segment your orders | No |
| promised_delivery_date | String | "2020-08-05T07:00:00+0000" | The delivery date you've promised the customer. The promised_delivery_date is an important parameter* (cf.comment below the table | Recommended |
- Promised_delivery_date: Fundamental information since it’s used as input to calculate various metrics within Seven Senders Portal. Therefore, we highly advise you to provide this information in an acceptable accuracy.
Available Language
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
Note: Language is a LOWERCASE two-letter ISO2 Code |
Create Order Items
Order items are created by using the POST operation of Order Item endpoint (POST/OrderItem)
Definitions
| Parameter | Type | Example | Description | Mandatory | Applicability to consumer-facing return portal |
| order_id | String | "QA_order_2020_07_31_091340" | Used to map the order item to a particular order ID | Yes | Yes |
| sku | String | "QA_SKU_2020-07-31_091254" | SKU of Product. Unique ID on a product level. | Yes | No |
| shipment_id | String | "123456789" | Use to map order items in a particular shipment. This ID is in API response of create Shipment endpoint | No | No |
| warehouse_address | String | "Schleißheimer Str. 506\n80933 München" | The address of the warehouse | No | No |
| warehouse | String | "Warehouse 1" | The name of the warehouse | No | No |
| shop_product_url | String | "https://www.sevensenders.com" | Be able to forward the consumer to the original shop page | No | No |
| name | String | “Shirt” | Name of the item displayed in the return portal. Saved on the order item level since we need to display the correct language | Yes | Yes |
| description | String | "Shirt description" | Describes product briefly. Saved on order item level to show the correct language in front-end. | Yes | Yes |
| sales_price | Float | "19.99" | Price for which the consumer bought the product. Displayed on the return portal page. | Yes | Yes |
| currency | String | "EUR" | Currency of the sales price | Yes | Yew |
| size | String | "Medium" | Size the item | Yes | Yes |
| weight | Float | "5" | In kg | Yes | No |
| appearance | String | "White" | Attribute to describe the appearance | No | No |
| returnable | Boolean | "True" | Yes/no - depending of it consumer can select in the return portal to return the item | Yes | Yes |
| bundle_item | String | "3456 " | Unique identifier set by the shop that combines order items to one bundle. If an order item is part of the bundle, all order items need to be returned together. | No | No |
Create a Shipment
Shipments are created by using the POST operation of the Shipment endpoint (POST/Shipment)
The "customer_email" is the email address of the consumer. It is required to enter the return portal. |
Definitions
| Parameter | Type | Example | Description | Mandatory |
| tracking_code | string | "tracking 123456789" | The shipment tracking number given by the carrier | Yes |
| reference_number | string | "ref123456" | The reference_number represents your internal reference for this shipment inside your IT system. The reference_number has to be unique | No |
| pickup_point_selected | boolean ( true or false) | "false" | It is the pickup point addressed by consumer (i.e. postal shop, retail shop,ect) | No |
| planned_pickup_datetime | date: yyyy-mm-ddThh:mm:ss+nnnn | "2020-08-15T09:00:00+0000" | The date and time agreed with Seven Senders to pick-up the shipment at your warehouse | Yes |
| comment | string | "Please be careful" | Comment regarding this shipment left by the customer or for your internal use. | No |
| warehouse_address | string | "Schleißheimer Str. 506\n80933 München" | Warehouse full address. Do not use line breaks. | Yes |
| warehouse | choice: List of all warehouse defined inside your account | "warehouse 1" | This value is static per warehouse you ship from and will be provided by Seven Senders during implementation. | Yes |
| shipment_tag | object | {"sku":"shirt2020"} | Tags/Properties to allow you to segment your shipments. | No |
| recipient_address | string | "Westminster 128,SW1A 0AA London, United Kingdom" | Consumer's address. Do not use line breaks. If a DHL "Packstation" has been chosen, please state "Packstation" and number (e.g "Packstation 123" | Yes |
| return_parcel | boolean ( true or false) | "false" | Indicates whether the shipment is a return from the customer | No |
| trackable | boolean ( true or false) | "true" | Indicates if a shipment is trackable. By default set to true. Setting this parameter is a prerequisite for displaying information on the "Tracking Page" and/or "Embedded Widget" in case of non-trackable shipments. | No |
| order_id | string | "QA_order_2020-07-31_091340" | The order reference inside your system. Alternatively, you can provide us with a unique ID | Yes |
| carrier | carrier: | {carrier_name: "dpd"; carrier_country: "DE"} | Provide Seven Senders carrier and carrier country | No |
| carrier.carrire_name | choice: See the list of choice below | "dpd" | Selected carrier to ship the parcel | Yes |
| carrier.carrier_country | choice: See the list of choice below | "DE" | A country where the parcel is handed over to the selected carrier/scanned for the first time by the selected carrier. | Yes |
| carrier_service | choice: "standard" "express" "other" | "express" | Service/Product/Tariff used by the carrier "other" | No |
| recipient_first_name | string | "John" | Customer's first name | Yes |
| recipient_last_name | string | "Doe" | Customer's last name | Yes |
| recipient_company_name | string | "Seven Senders" | Customer's company name if he/she choose to be delivered at his/her company. | No |
| recipient_email | "[email protected]" | Customer's email address to send an email notification to your customer through Seven Senders Portal. Without this information, no email notification can be sent. In case you're only using our delivery product, you can provide a "default" email address (e.g. [email protected]) | Yes | |
| recipient_zip | string | "SW1A0AA" | Customer's zip code | Yes |
| recipient_city | string | "London" | Customer's city | Yes |
| recipient_country | string | "GB" | Customer's country. Use ISO 3166-1 alpha-2 | Yes |
| recipient_phone | use+for the country code (see example) | "+4915223455981" | Customer's phone number. | No |
| recipient_address_details | string | "Westminster 128" | Customer's address. Do not use line breaks. If a DHL "Packstation" has been chosen, please state "Packstation" and number (e.g "Packstation 123" | Yes |
| weight | number | "5" | Shipment weight in KG | Yes |
Available Carriers
The table below contains the currently available carriers (subject to change). All currently available carriers are applicable by applying the GET/carriers operation.
| Carrier_country | Carrier_name |
| AT | postat, dpd, ups, dhl |
| BE | bpost, dpd, kiala, mondialrelay, ups, dhl |
| CH | swisspost, dpd, ups, dhl |
| CZ | ceskaposta, dpd, ups |
| DE | dhlexpress, 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, nexive, posteitaliane, SDAposteitaliane |
| LU | dhl, ups, kiala, dpd |
| NL | postnl, kiala, dpd, mondialrelay, tnt, ups, dhl |
| NO | postnord, ups, dhl, dpd |
| PL | dpd, gls, ups, dhl, poczta-polska |
| SE | postnord, ups, dhl |
| SK | ceskaposta, dpd, ups, dhl |
Update Order Item with Shipment_id
Update order item with shipment_id is conducted by using the PUT operation of the OrderItem endpoint (PUT/OrderItem)
This is an optional step. Updating the order_item with shipment_id connects the order_item with the shipment, which ensures the data completeness. |
Push Shipment Event
Shipment events are created by using the POST operation of the 'shipment' endpoint (POST/ShipmentEvent). Please send us the following events:
- Refunded - When you have processed the refund for the order
- Returned to warehouse - When the return parcel has reached the final warehouse
Definition
| Parameter | Type | Example | Description | Mandatory |
| ID | String | "23234234" | Yes | |
| datetime | String | "2020-08-14T07:01:09.720Z" | Timestamp of the event in UTC | Yes |
| Event | String | Refunded" | Acceptable values - "Refunded" and "Returned to warehouse" | Yes |
API Response Codes
The Seven Sender's API will communicate responses using standard HTTP codes.
| 200 | OK (Everything worked as expected) | |
| 201 | Created (The object you specified has been created) | |
| 202 | Accepted (The object you specified has been accepted for processing) | |
| 204 | No Content (OK, but nothing to return) | |
| 400 | Bad Request (Often missing a required parameter) | |
| 401 | Unauthorized (Authentication failed. See Authentication) | |
| 402 | Request Failed (Parameters were valid, but the request failed) | |
| 403 | Forbidden (Trial account has expired) | |
| 404 | Not Found (The requested item doesn't exist) | |
| 422 | Unprocessable Entity (Your request has semantic errors) | |
| 429 | Too many requests (You have exceeded our rate limits) | |
| 500,502,503,504 | Server Errors (Something went wrong on Seven Senders API endpoint) | |
Additionally, error messages will be included in responses wherever possible to help you identify the source of a problem.