Support Portal


Return Portal Pro implementation

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


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


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 for custom clearanceNo
customs_item_valueString"500"The value of the productNo
String"Germany "Set by the shopNo
String"United Kingdom "Set by the shopNo

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.


skuString"QA_SKU_2020-07-31_091254"SKU of the 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.


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 (


The date when the order was created in your systemYes
[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 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)


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 endpointNoNo
warehouse_addressString"Schleißheimer Str. 506\n80933 München"The address of the warehouseNoNo
warehouseString"Warehouse 1"The name of the warehouseNoNo
shop_product_urlString""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.


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
( true or false)
"false"It is the pickup point addressed by consumer (i.e. postal shop, retail shop,ect)No
"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


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"

( true or false)
"false"Indicates whether the shipment is a return from the customerNo
( 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

The order reference inside your system.

Alternatively, you can provide us with a unique ID

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


See the list of choice below

Selected carrier to ship the parcel

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






Service/Product/Tariff used by the carrier


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

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.

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"

weightnumber"5"Shipment weight in KGYes

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.

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

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


datetimeString"2020-08-14T07:01:09.720Z"Timestamp of the event in UTC Yes
EventStringRefunded"Acceptable values -
"Refunded" and "Returned to warehouse"

API Response Codes

The Seven Sender's API will communicate responses using standard HTTP codes.

200OK (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 the 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.

Did you find it helpful? Yes No