Support Portal

Welcome
Login

Delivery and Return Portal

This section covers all information needed to connect Seven Senders via API when using the Seven Sender Delivery Service in combination with Order Item, Product, and the optional Seven Senders Portal.

 

TABLE OF CONTENTS

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 Product endpoint (Post/product).

Definitions

ParameterTypeExampleDescriptionMandatory
skuString"QA_SKU_2020-07-31_091254"SKU of product in the warehouse. Unique ID on a product level.Yes
customs_descriptionString"Customs Description"The description of the product which is used to custom clearanceNo
customs_item_valueString"500"The value of the productNo
customs_tariff_code_
sending_country
String"Germany "Set by the shopNo
customs_tariff_code_
receiving_country
String"United Kingdom "Set by the shopNo
customs_origin_country_iso2String"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 

ParameterTypeExampleDescriptionMandatory
skuString"QA_SKU_2020-07-31_091254"SKU of shop in the warehouse. Unique ID on a product level.yes
attachmentStringNAThe base64 encoded data of the image file(PEG and PNG are allowedyes
filenameString"TestImage.png"The name of the imageyes


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).



  1. The order_id is the Order number required to enter the return portal.
  2. The "order_url" is the localisation. It has to be added to the Localisations in Seven Sender's portal and then can be found under Settings -> Localisations.

Definitions

ParameterTypeExampleDescriptionMandatory
order_idString"QA_order_2020_07_31_091340"The order reference inside your systemYes
order_urlStringhttp://7s.comOn which website the order was submitted. Used to map an order to localizeRecommended
order_dateString (dd.mm.yyyy.hh:mm:ss)

"2020-07-31T07:00:00+0000">

The date when the order was created in your systemYes
boarding_completeboolean
[true of false]
"False"Information indicating (if an order consists of multiple parcels) that all shipments of an order have been importedNo
LanguageArray [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_tagsArray [string]{"tag 1":"test" }Tags/Properties to allow you to segment your ordersNo
promised_delivery_dateString"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 tableRecommended

- 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 accurate.


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

ParameterType  ExampleDescription MandatoryApplicability to consumer-facing return portal
order_idString"QA_order_2020_07_31_091340"Used to map the order item to a particular order IDYesYes
skuString"QA_SKU_2020-07-31_091254"SKU of Product. Unique ID on a product level.YesNo
shipment_idString"123456789"Use to map order items in a particular shipment. This ID is in API response of create Shipment endpoint
No
warehouse_addressString"Schleißheimer Str. 506\n80933 München"The address of the warehouse
No
warehouseString"Warehouse 1"The name of the warehouseNoNo
shop_product_urlString"https://www.sevensenders.com"Be able to forward the consumer to the original shop page  NoNo
nameString“Shirt”Name of the item displayed in the return portal. Saved on the order item level since we need to display the correct languageYesYes
descriptionString"Shirt description"Describes product briefly. Saved on order item level to show the correct language in front-end.  YesYes
sales_priceFloat"19.99"Price for which the consumer bought the product. Displayed on the return portal page.YesYes
currencyString"EUR"Currency of the sales price YesYew
sizeString"Medium"Size the itemYesYes
weightFloat"5"In kgYesNo
appearance String"White"Attribute to describe the appearanceNoNo
returnableBoolean"True"Yes/no - depending of it consumer can select in the return portal to return the itemYesYes
bundle_itemString"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.NoNo


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

ParameterTypeExampleDescriptionMandatory
tracking_codestring"tracking 123456789"The shipment tracking number given by the carrierYes
reference_numberstring"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_selectedboolean
( true or false)
"false"It is the pickup point addressed by consumer (i.e. postal shop, retail shop,ect)No
planned_pickup_datetimedate:
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 warehouseYes
commentstring"Please be careful"Comment regarding this shipment left by the customer or for your internal use.No
warehouse_addressstring"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_tagobject{"sku":"shirt2020"}Tags/Properties to allow you to segment your shipments.No
recipient_addressstring"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_parcelboolean
( true or false)
"false"Indicates whether the shipment is a return from the customerNo
trackableboolean
( 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_idstring"QA_order_2020-07-31_091340"

The order reference inside your system.


Alternatively, you can provide us a unique ID


Yes
carriercarrier:{carrier_name: "dpd"; carrier_country: "DE"}Provide Seven Senders carrier and carrier countryNo
carrier.carrire_name

choice:


See the list of choice below

"dpd"
Selected carrier to ship the parcel
Yes
carrier.carrier_countrychoice:


See the list of choice below

"DE"A country where the parcel is handed over to 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_namestring"John"Customer's first nameYes
recipient_last_namestring"Doe"Customer's last name Yes
recipient_company_namestring"Seven Senders"Customer's company name if he/she choose to be delivered at his/her company.No
recipient_emailEmail"qa@sevensenders.com"

Customer's email address to send 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. cs@yourcompany.de)

Yes
recipient_zipstring"SW1A0AA"Customer's zip codeYes
recipient_citystring"London"Customer's cityYes
recipient_countrystring"GB"Customer's country. Use ISO 3166-1 alpha-2Yes
recipient_phoneuse+for the country code (see example)"+4915223455981"Customer's phone number.No
recipient_address_detailsstring"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
weightnumber"5"Shipment weight in KGYes

Available Carriers

The table below contains the currently available carriers (subject to change). All currently available carrier are applicable by applying the GET/carriers operation.

Carrier_countryCarrier_name
ATpostat, dpd, ups, dhl
BEbpost, dpd, kiala, mondialrelay, ups, dhl
CHswisspost, dpd, ups, dhl
CZceskaposta, dpd, ups
DEdhlexpress, dhl, deutschepost, gls, ups, hermes, dpd, tnt
DKpostnord, ups, dhl, dpd
EScorreos, seur,seur_international,asm, mrw, ups, dhl
FIposti, postnord, ups, dhl, dpd
FRcolissimo, chronopost, tnt, dpd, mondialrelay, colisprive, gls, dhl, ups
GBroyalmail, yodel, parcelforce, hermes, dpd, dhl
ITbrt, tnt, gls, ups, dhl, nexive, posteitaliane, SDAposteitaliane
LUdhl, ups, kiala, dpd
NLpostnl, kiala, dpd, mondialrelay, tnt, ups, dhl
NOpostnord, ups, dhl, dpd
PLdpd, gls, ups, dhl, poczta-polska
SEpostnord, ups, dhl
SKceskaposta, dpd, ups, dhl


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

ParameterTypeExampleDescriptionMandatory
IDString"23234234"
Yes
datetimeString"2020-08-14T07:01:09.720Z"Timestamp of the event in UTC Yes
EventStringRefunded"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)
201Created (The object you specified has been created)
202Accepted (The object you specified has been accepted for processing)
204No Content (OK, but nothing to return)
400Bad Request (Often missing a required parameter)
401Unauthorized (Authentication failed. See Authentication)
402Request Failed (Parameters were valid, but request failed)
403Forbidden (Trial account has expired)
404Not Found (The requested item doesn't exist)
422Unprocessable Entity (Your request has semantic errors)
429Too many requests (You have exceeded our rate limits)
500,502,503,504Server 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.