{"info":{"_postman_id":"64f3071e-392e-4a83-8396-dd24da34b8d6","name":"Merkana - returns processing API v1","description":"

Introduction

API documentation on how do we exchange data with our fulfillment partners (return centers).

Overview

This is a short summary of the steps of API communication to build proper and accurate data exchange between Mediapost Hit Mail/ Mercoria platform and our partner fulfillment warehouses (hereinafter referred to as return centers) that process the parcel returns of ecommerce customers.

All steps described below are available and applicable only after we register and authorize the return center (RC) in the Mercoria back-end.

The roles in the process described below are as follows:

Shipping return center (SRC) – any business partner of ours that is able to provide a local return address in one or more countries and is willing to:
a. accept in their warehouse returned parcels of ecommerce merchants who ship their parcels from one country to another (cross-border);
b. process the returned parcels – in other words validate the owner of the parcel (ecommerce merchant), open the parcel, check its content against the information we provide about it (number of items in the parcel shipped by the ecommerce merchant, initial number of items in the parcel, specific products and some of their characteristics etc.), report the check result, report if the parcel itself or one or more items in it are damaged or not, close the parcel.
c. prepare all returned parcels for a particular country in a consolidated shipment (Master box (Mbox) or pallet) and send it to a receiving return center in this country based on information we provide (name of the receiving return center, address, contact person etc.).
\n
Receiving return center (RRC) – any business partner of ours that is able to receive a consolidated shipment (Mbox or pallet) from a shipping return center from another country and is willing to:
a. open and check the content of the consolidated shipment against the information our platform provides (ID of the shipment, no. of parcels inside, data about each parcel etc.)
b. report the check result back to the platform in accordance to the data exchange protocol described below
c. based on the ecommerce merchant instructions, either prepare the items in the returned parcel for re-stock, destroy the items or else.
\n
Ecommerce merchant – any business entity that wants to use the parcel return management service provided by us or any of our business partners in any of the countries within the scope of our network, who accepts B2B or B2C orders from customers in other countries (cross-border) and ships the orders accordingly to the address provided by the customer.
\n

Authentication

All integrated return centers will get an unique authorization token and must use it when sending request to our platform.
This is a key-value pair on header (api-token - 123456789).

Error Codes

We use JSON with:
status - true/false
ID - id of the record created
message - some user-friendly message
or return data.

Rate limit

There is still no limit. However, such might be imposed upon reaching certain volumes of data exchange.

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Introduction","slug":"introduction"},{"content":"Overview","slug":"overview"},{"content":"Authentication","slug":"authentication"},{"content":"Error Codes","slug":"error-codes"},{"content":"Rate limit","slug":"rate-limit"}],"owner":"25353905","collectionId":"64f3071e-392e-4a83-8396-dd24da34b8d6","publishedId":"2s8ZDbWLNa","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"publishDate":"2023-01-24T09:43:20.000Z"},"item":[{"name":"Find Order","item":[{"name":"Find Order by oid or awb","event":[{"listen":"test","script":{"id":"ccde1474-6faf-43fa-a462-7409392af33a","exec":[""],"type":"text/javascript"}}],"id":"55c9aa68-1e19-4290-af3f-c2ce6481a1cd","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"url":"https://r.mercoria.com/v1/orders?order_id=16516","description":"

URL expect awb or oid (OrderID).

AWB of the returned parcel provided by the ecommerce merchant after they agree with the end customer that there will be returned product(s). This parameter is used if the merchant has this data.
Oid is the original order id from the ecommerce merchant (external for our platform). It is usually provided in a return form used by the end customer, where they should specify the order ID based on which they send back to the ecommerce merchant one or more of the ordered items in an identified parcel.

In both cases, we return an array of orders because, theoretically, these fields are not unique for us.

\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"api-token"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"64f3071e-392e-4a83-8396-dd24da34b8d6","id":"64f3071e-392e-4a83-8396-dd24da34b8d6","name":"Merkana - returns processing API v1","type":"collection"}},"urlObject":{"protocol":"https","path":["v1","orders"],"host":["r","mercoria","com"],"query":[{"key":"order_id","value":"16516"},{"disabled":true,"key":"awb","value":"6193602"}],"variable":[]}},"response":[{"id":"e6203278-63d4-4c31-9f1c-db086fbfb342","name":"Find Order by order_id","originalRequest":{"method":"POST","header":[],"url":{"raw":"https://r.mercoria.com/v1/orders?order_id=289828718","protocol":"https","host":["r","mercoria","com"],"path":["v1","orders"],"query":[{"key":"order_id","value":"289828718"},{"key":"awb","value":"61979199594","disabled":true}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Server","value":"nginx/1.18.0 (Ubuntu)"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Date","value":"Wed, 30 Nov 2022 16:12:56 GMT"}],"cookie":[],"responseTime":null,"body":"[\n {\n \"order_id\": 289828718,\n \"int_order_id\": 2360,\n \"order_awb\": \"61979199594\",\n \"receiver_id\": 1,\n \"receiver_name\": \"Metrica\",\n \"receiver_country\": \"Bulgaria\",\n \"receiver_country_code\": \"BG\",\n \"return_process_type\": 2,\n \"total\": \"115.84\",\n \"currency\": \"RON\",\n \"payment_method\": \"onlinecardpayment\",\n \"customer_note\": \"\",\n \"shipping\": {\n \"shipping_contact\": \"Nagy Tünde\",\n \"shipping_phone\": \"0753925848\",\n \"shipping_country\": \"RO\",\n \"shipping_suburb\": \"Cluj\",\n \"shipping_city\": \"Cluj-Napoca\",\n \"shipping_street\": \"str. I. C. Brătianu, nr. 43, ap. 20\",\n \"shipping_postal_code\": \"\",\n \"shipping_locality_id\": \"5480\",\n \"shipping_instructions\": \"\",\n \"shipping_courier\": \"\",\n \"shipping_method\": \"\",\n \"shipping_courier_office\": \"\",\n \"company\": \"Tünde Nagy\",\n \"email\": \"\"\n },\n \"order_items\": [\n {\n \"order_items_id\": 2442,\n \"sku\": \"ACCA-WCB6-S-CH\",\n \"title\": \"Suport de lemn pentru sitcle de bere, din lemn, pentru 6 sticle, maro\",\n \"quantity\": 1,\n \"total\": \"84.03\",\n \"vat\": \"20.00\"\n }\n ]\n }\n]"},{"id":"e0ee4cc0-e906-4a5e-9675-22b314417767","name":"Find Order by awb","originalRequest":{"method":"POST","header":[],"url":{"raw":"https://r.mercoria.com/v1/orders?awb=61979199594","protocol":"https","host":["r","mercoria","com"],"path":["v1","orders"],"query":[{"key":"order_id","value":"289828718","disabled":true},{"key":"awb","value":"61979199594"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Server","value":"nginx/1.18.0 (Ubuntu)"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Date","value":"Wed, 30 Nov 2022 16:33:53 GMT"}],"cookie":[],"responseTime":null,"body":"[\n {\n \"order_id\": 289828718,\n \"int_order_id\": 2360,\n \"order_awb\": \"61979199594\",\n \"receiver_id\": 1,\n \"receiver_name\": \"Metrica\",\n \"receiver_country\": \"Bulgaria\",\n \"receiver_country_code\": \"BG\",\n \"return_process_type\": 2,\n \"total\": \"115.84\",\n \"currency\": \"RON\",\n \"payment_method\": \"onlinecardpayment\",\n \"customer_note\": \"\",\n \"shipping\": {\n \"shipping_contact\": \"Nagy Tünde\",\n \"shipping_phone\": \"0753925848\",\n \"shipping_country\": \"RO\",\n \"shipping_suburb\": \"Cluj\",\n \"shipping_city\": \"Cluj-Napoca\",\n \"shipping_street\": \"str. I. C. Brătianu, nr. 43, ap. 20\",\n \"shipping_postal_code\": \"\",\n \"shipping_locality_id\": \"5480\",\n \"shipping_instructions\": \"\",\n \"shipping_courier\": \"\",\n \"shipping_method\": \"\",\n \"shipping_courier_office\": \"\",\n \"company\": \"Tünde Nagy\",\n \"email\": \"\"\n },\n \"order_items\": [\n {\n \"order_items_id\": 2442,\n \"sku\": \"ACCA-WCB6-S-CH\",\n \"title\": \"Suport de lemn pentru sitcle de bere, din lemn, pentru 6 sticle, maro\",\n \"quantity\": 1,\n \"total\": \"84.03\",\n \"vat\": \"20.00\"\n }\n ]\n }\n]"}],"_postman_id":"55c9aa68-1e19-4290-af3f-c2ce6481a1cd"}],"id":"c92cab50-4638-4b2c-a83d-5176cbf08d34","_postman_id":"c92cab50-4638-4b2c-a83d-5176cbf08d34","description":"","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"api-token"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"64f3071e-392e-4a83-8396-dd24da34b8d6","id":"64f3071e-392e-4a83-8396-dd24da34b8d6","name":"Merkana - returns processing API v1","type":"collection"}}},{"name":"Return","item":[{"name":"Create Return","id":"3580304f-d682-45a3-86fb-9c64799755cb","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"int_order_id\": 1913,\r\n \"return_awb\":\"147258369\",\r\n \"info_id\":1,\r\n \"returned_items\": [\r\n {\r\n \"order_item_id\": 1759,\r\n \"qty\": 1,\r\n \"status_id\": 1\r\n },\r\n {\r\n \"order_item_id\": 1760,\r\n \"qty\": 1,\r\n \"status_id\": 2\r\n }\r\n ]\r\n}","options":{"raw":{"language":"json"}}},"url":"https://r.mercoria.com/v1/returns","description":"

To create a new return the shipping return center must post JSON with:

int_order_id - id is internal for Mercoria for any specific order that we send with order details;
return_awb - last used AWB from a client if the return can stay in this package (and this will stay visible) or a self-generated number that the SRC will print and place on the consolidated Master box (a.k.a. Mbox). This is required for easier and more accurate processing of the master box from the RRC.
info_id - general info for return: 1-normal, 2-damaged, 3-partial

returned_items - an array for return items
order_item_id - our internal id (from order details)
qty - quantity
status_id - 1-ok, 2-damaged

To create a new return the shipping return center must post JSON with:

returned_items - an array for return items
order_item_id - our internal id (from order details)
qty - quantity
status_id - 1-ok, 2-damaged

Used when a returned parcel is being put in a master box (Mbox) from the SRC.

mbox_is is required, you can get it from mbox listing for a specific RRC.

This is used when a return is being processed from a RRC.

Return id specified in URL comes from Mbox content information when the RRC checks the Mbox AWB (or a unique identifier/ barcode is placed on it in case the consolidated shipment is a pallet and not Mbox).

status_id - general for return: 4-received ok, 5-missing items, 6-damaged/damaged items

returned_items - array for returned items
order_item_id - our internal id (from return details)
qty - quantity (can be different from initial)
status_id - 1-ok, 2-missing items, 3-damaged/damaged items
note - to specify some notes to merchant

This method provides the SRC with all created and open (not placed in Mbox) returns.

If all param is added a list of all returns will be provided.

Get all return information for a particular AWB or another identifier generated and provided by the SRC.

In the example, you can see:
\"id\": 3,
\"order_id\": 1913,
\"receiver_id\": 1,
\"return_awb\": \"147258369\",
\"info_id\": 1,
\"status_id\": 1,
\"mbox_id\": 1,
\"returned_items\": [ ...] - for each item return_item_id, title, sku, barcode, qty, status_id

To create a new Mbox the SRC needs to specify only a receiver_id. This information is on order JSON and it is based on the order's initial fulfillment center (where parcels have been shipped from initially).

On Mbox update, the SRC has two options:

print a self-generated barcode, put the barcode on the Mbox and place the Mbox on a pallet associated with an AWB
generate an AWB and put it directly on the Mbox

status_is is mandatory - 2 closed, 3-shipped
When Mbox final processing by the RRC is complete, the RRC sends the:
status_id - 4-received ok, 5-damaged, 6-missing returns

Used to get information for open (created) Mboxes.

In examples:

get open mboxes for the specific RRC - receiver_id
get all open mboxes
get all created by this SRC - all

\n","auth":{"type":"apikey","apikey":{"basicConfig":[{"key":"key","value":"api-token"},{"key":"value","value":""}]},"isInherited":true,"source":{"_postman_id":"64f3071e-392e-4a83-8396-dd24da34b8d6","id":"64f3071e-392e-4a83-8396-dd24da34b8d6","name":"Merkana - returns processing API v1","type":"collection"}},"urlObject":{"protocol":"https","path":["v1","mboxes"],"host":["r","mercoria","com"],"query":[{"disabled":true,"key":"all","value":""},{"disabled":true,"key":"receiver_id","value":"1"}],"variable":[]}},"response":[{"id":"cfc796bd-944b-49ec-ba53-67cbd8a0362d","name":"Get return center created (open) Mboxes for receiver_id","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://r.mercoria.com/v1/mboxes?receiver_id=1","protocol":"https","host":["r","mercoria","com"],"path":["v1","mboxes"],"query":[{"key":"all","value":"","disabled":true},{"key":"receiver_id","value":"1"}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Server","value":"nginx/1.18.0 (Ubuntu)"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Date","value":"Sun, 04 Dec 2022 21:20:32 GMT"}],"cookie":[],"responseTime":null,"body":"[\n {\n \"id\": 1,\n \"receiver_id\": 1,\n \"receiver_title\": \"Metrica\",\n \"receiver_country\": \"Bulgaria\",\n \"receiver_country_code\": \"BG\",\n \"status_id\": 1,\n \"pallet_id\": null,\n \"awb\": \"223344\",\n \"awb_url\": null,\n \"created_at\": \"2022-11-26T12:29:57.000000Z\",\n \"updated_at\": \"2022-12-04T22:06:23.000000Z\"\n }\n]"},{"id":"87efac5c-46e4-4046-af59-d66b86569ab0","name":"Get return center all created (open) Mboxes","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://r.mercoria.com/v1/mboxes","protocol":"https","host":["r","mercoria","com"],"path":["v1","mboxes"],"query":[{"key":"all","value":"","disabled":true},{"key":"receiver_id","value":"1","disabled":true}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Server","value":"nginx/1.18.0 (Ubuntu)"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Date","value":"Sun, 04 Dec 2022 21:22:14 GMT"}],"cookie":[],"responseTime":null,"body":"[\n {\n \"id\": 1,\n \"receiver_id\": 1,\n \"receiver_title\": \"Metrica\",\n \"receiver_country\": \"Bulgaria\",\n \"receiver_country_code\": \"BG\",\n \"status_id\": 1,\n \"pallet_id\": null,\n \"awb\": \"223344\",\n \"awb_url\": null,\n \"created_at\": \"2022-11-26T12:29:57.000000Z\",\n \"updated_at\": \"2022-12-04T22:06:23.000000Z\"\n }\n]"},{"id":"dfd995de-2549-4b32-a47e-aa7ed73403b4","name":"Get return center all Mboxes","originalRequest":{"method":"GET","header":[],"url":{"raw":"https://r.mercoria.com/v1/mboxes?all","protocol":"https","host":["r","mercoria","com"],"path":["v1","mboxes"],"query":[{"key":"all","value":null}]}},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Server","value":"nginx/1.18.0 (Ubuntu)"},{"key":"Content-Type","value":"application/json"},{"key":"Transfer-Encoding","value":"chunked"},{"key":"Connection","value":"keep-alive"},{"key":"Cache-Control","value":"no-cache, private"},{"key":"Date","value":"Sun, 04 Dec 2022 09:34:10 GMT"}],"cookie":[],"responseTime":null,"body":"[\n {\n \"id\": 1,\n \"receiver_id\": 1,\n \"receiver_title\": \"Metrica\",\n \"receiver_country\": \"Bulgaria\",\n \"receiver_country_code\": \"BG\",\n \"status_id\": 2,\n \"pallet_id\": null,\n \"awb\": null,\n \"awb_url\": null,\n \"created_at\": \"2022-11-26T12:29:57.000000Z\",\n \"updated_at\": \"2022-12-03T21:37:39.000000Z\"\n }\n]"}],"_postman_id":"48e88350-cb25-4433-b4ff-840b304ed3a2"},{"name":"Get return center Mbox info","id":"828c88ae-0dd8-4f96-b206-e422c4b52da9","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"https://r.mercoria.com/v1/mboxes/223344","description":"

To get information about a particular Mbox, an AWB or a printed barcode placed on the Mbox must be used by the RRC.

The platform returns a JSON array with information for Mboxes found. We always do checks and you can see info (or update it) for any parcel, Mbox or pallet only if you are the SRC or RRC, but theoretically, AWB or self-generated codes aren’t unique.

In the returns array part of JSON, you will find all the required information to identify returns when Mbox processing starts.

return_id - from our platform, you will use it when processing the return
return_awb - AWB or printed code on the return
order_id - original order id from a merchant

To create a new pallet the SRC that ships the Mbox to a RRC needs to specify only a receiver_id. This information is provided by the order JSON and it is based on the order's initial fulfillment center (where the parcel has been shipped from initially). Alternatively, it is based on the already prepared Mbox for the same RRC.

Upon updating a pallet, the SRC generates an AWB and reports

status_id - 2 closed, 3-shipped
AWB and/or awb_url (optional)

When Pallet is processed, the RRC reports
status_id - 4-received ok, 5-damaged, 6-missing mboxes

Used to get information for open (created) pallets by the SRC.
In examples:

get open pallets for the specific RRC - receiver_id
get all open pallets
get all pallets created by the SRC - all

To get pallet information the AWB of the pallet must be used.
The platform returns a JSON array with information for found pallets.
In the mboxes array part of JSON, you will find all the required information to identify an Mbox when Mbox processing starts.
mbox_id - from our platform, you will use it when processing the mbox
mbox_awb - AWB or printed code on the Mbox will be used to get Mbox content information