Orders API (Webhook)

M-board provides a webhook URL to import all order notifications related to your marketplace business.

Webhook URL and API Key

The webhook url accepts HTTP(s) POST requests and uses an API Key for basic authentication. The API key should be sent in the HTTP header x-api-key.

POST https://webhook.m-board.io The media type of the request should be set to application/json and be communicated in the Content-Type-header. The event must be sent in the request body as a JSON string.

An API Key (Password) is required to communicate with the webhook. The credentials can be obtained from [e-mail].

Important: The webhook acknowledges every notification of any type with an [200] response.

Notification Structure

Order event is a JSON object with the following schema:

Field	Data Type	Manadory	Description
source	String	required	Name of the source system. Description of source can be found in “Source Description” section
channel	String	optional	Name of the channel. Description of channel can be found in “Channel Description” section
event_id	String	required	Unique id of the event
order_id	String	required	Order id of channel
order_number	String	required	Order number displayed to customer
state	String	required	Allowed values: assigned, fulfilled, returned and cancelled
store_id	String	required	Store id
timestamp	String	required	ISO 8061 timestamp
delivery_details	JSON Object		Delivery and return tracking information
customer_billing_address	JSON Object		Name and billing address of the customer
items	Array	required	Items that were affected by the state transition for fulfilled order the list of items that were shipped excluding cancelled items for cancelled order the list of items that were cancelled (i.e. all items of the order) for routed order all items of the order for assigned order all items of the order for returned order the list of items that were returned at this particular moment by the customer
cancelled_items	Array		Items that were cancelled in the partially fulfilled order will only contain cancelled items when a fulfilled order has both shipped and cancelled items if all the items in the order were cancelled and order is cancelled, this field will be empty while cancelled items will be included in the "items" field instead
is_giftcard	Boolean		Specifies if the order is a gift card. Default: false
is_pickup	Boolean		A Click & Collect order where the customer picks up items at a physical store. Default: false

Item has the following schema:

Field	Data Type	Manadory	Description	Example
item_id	String	required	Item id of channel	15c3aa83-3f73-4ad6-a326-e1a10a89dd52
ean	String	required	EAN of the article	4059701022541
price	Number	required	Price of the article	99.95 or 12
currency	String	required	ISO-4217 currency code	EUR
article_number	String	required	Article number (SKU)	31.832.34-6,5
channel_article_number	String		Article number of channel	DU341A00M-1020375000
article_location	String		Location of the article	213
return_reason_code	Number		Reason number associated to return reason, description of code can be found in “Return Reason Code Description” section	1
return_location	String		The location of the item's return when the order was fulfilled by a store. If the item was returned to a store, the value is "STORE," and if it was returned to a warehouse, the value is "WAREHOUSE"	Allowed values: STORE or WAREHOUSE
cancellation_reason	String		The "Cancellation Reason Description" section contains the item's cancellation reason and a description of the values	OUT_OF_STOCK

delivery_details has the following schema:

Field	Data Type	Manadory	Description	Examples
delivery_tracking_number	String		delivery tracking number	003404342888680268172
delivery_carrier_name	String		delivery carrier name	DHL
return_tracking_number	Number		return tracking number	35141263178
return_carrier_name	String		return carrier name	DHL

customer_billing_address has the following schema:

Field	Data Type	Manadory	Description
first_name	String	required	first name of the customer
last_name	String	required	last name of the customer
address_line_1	String	required	first line of the billing address
address_line_2	String		additional information about the billing address, e.g. NIP for Poland, More detailed description of address and addressee or additional instructions
address_line_3	String		further additional information about the billing address
zip_code	String	required	billing address zip code
city	String	required	billing address city
country_code	String	required	billing address country code

Return reason description

Return Reason Code	Reason
1	It doesn't suit me
2	Too big
3	Too small
4	Insufficient quality
5	Arrived too late
6	Not as expected
7	Incorrect article
8	Faulty
9	No reason available
10	Delivery failed
-1	Unknown reason

Cancellation reason description

Cancellation reason	Description
ITEM_BROKEN	Item is broken
ITEM_MISSING	Item is in stock in the inventory system, but in fact it is missing in the store
OUT_OF_STOCK	Item is not in stock in the inventory system
UNKNOWN_REASON	Unknown reason

Source description

Source	Description
amazon	Amazon Marketplace
otto	OTTO.market
zcr	Zalando Connected Retail
zpp	Zalando Partner Program
cys	Connect Your Store
outfits24	Outfits 24 (The Platform Group)
webshop	Merchant's own webshop
store	Merchant's own retail store
...	...

Source system missing? Contact us [e-mail]

Channel description

Channel	Description
zalando_de	zalando.de
zalando_ch	zalando.ch
zalando_at	zalando.at
zalando_it	zalando.it
amazon_de	amazon.de
amazon_ch	amazon.ch
amazon_at	amazon.at
amazon_it	amazon.it
webshop_de	Merchant's webshop in DE
store_123	Merchant's own retail store with store id 123, if available store's GLN can be used
...	...

Channel missing? Contact us [e-mail]

Examples of events

Assigned event

The following shows an example assigned event for Zalando Connected Retail:

{
 "source": "zcr",
 "channel": "zalando_de",
 "event_id": "782d1ec3-8441-44db-a081-76df6b2de18f",
 "order_id": "61e2d090-0d53-451f-9031-413559d34732",
 "order_number": "10105000000000",
 "state": "assigned",
 "store_id": "11",
 "timestamp": "2020-01-28T07:41:23.384Z",
 "items": [
   {
     "item_id": "15c3aa83-3f73-4ad6-a326-e1a10a89dd52",
     "ean": "4059701022541",
     "price": 99.95,
     "currency": "EUR",
     "article_number": "31.832.34-6,5",
     "article_location": "213"
   },
   {
     "item_id": "101610aa-71b1-4f52-b3ab-4d6cbc4e8adb",
     "ean": "4059701214472",
     "price": 99.95,
     "currency": "EUR",
     "article_number": "33.731.54-7",
     "article_location": "213"
   }
 ]
}

Fulfilled event

The following shows an example fulfilled event for Zalando Connected Retail:

{
 "source": "zcr",
 "channel": "zalando_de",
 "event_id": "3aa445e7-550a-442b-93e1-0cf84183e507",
 "order_id": "61e2d090-0d53-451f-9031-413559d34732",
 "order_number": "10105000000000",
 "state": "fulfilled",
 "store_id": "11",
 "timestamp": "2020-01-28T07:41:24.927Z",
 "delivery_details": {
    "delivery_tracking_number": "003404342888680268172",
    "delivery_carrier_name": "DHL",
    "return_tracking_number": "35141263178",
    "return_carrier_name": "DHL"
 },
 "customer_billing_address": {
    "first_name": "Max",
    "last_name": "Mustermann",
    "address_line_1": "Musterstraße 12 34",
    "zip_code": "12345",
    "city": "Berlin",
    "country_code": "DE"
 },
 "items": [
   {
     "item_id": "15c3aa83-3f73-4ad6-a326-e1a10a89dd52",
     "ean": "4059701022541",
     "price": 99.95,
     "currency": "EUR",
     "article_number": "31.832.34-6,5",
     "article_location": "213"
   }
 ],
 "cancelled_items": [
   {
     "item_id": "1db07d36-9ea2-4af6-b169-63f0594cf7c0",
     "ean": "9780141026626",
     "price": 29.95,
     "currency": "EUR",
     "article_number": "11.454.14-2,4",
     "article_location": "113",
     "cancellation_reason": "OUT_OF_STOCK" 
   }
 ]
}

Cancelled event

The following shows an example cancelled event for Zalando Connected Retail:

{
 "source": "zcr",
 "channel": "zalando_de",
 "event_id": "1827ca7e-daa5-4ccd-af7c-10582010ad44",
 "order_id": "61e2d090-0d53-451f-9031-413559d34732",
 "order_number": "10105000000000",
 "state": "cancelled",
 "store_id": "11",
 "timestamp": "2020-01-28T07:41:28.824Z",
 "items": [
   {
     "item_id": "15c3aa83-3f73-4ad6-a326-e1a10a89dd52",
     "ean": "4059701022541",
     "price": 99.95,
     "currency": "EUR",
     "article_number": "31.832.34-6,5",
     "article_location": "213",
     "cancellation_reason": "OUT_OF_STOCK"
   }
 ]
}

Returned event

The following shows an example returned event for Zalando Connected Retail:

{
 "source": "zcr",
 "channel": "zalando_de",
 "event_id": "48a1e2b7-74e9-4790-b324-1e6fa22e1ca7",
 "order_id": "61e2d090-0d53-451f-9031-413559d34732",
 "order_number": "10105000000000",
 "state": "returned",
 "store_id": "11",
 "timestamp": "2020-01-28T07:41:31.947Z",
 "delivery_details": {
    "delivery_tracking_number": "003404342888680268172",
    "delivery_carrier_name": "DHL",
    "return_tracking_number": "35141263178",
    "return_carrier_name": "DHL"
 },
 "customer_billing_address": {
    "first_name": "Max",
    "last_name": "Mustermann",
    "address_line_1": "Musterstraße 12 34",
    "zip_code": "12345",
    "city": "Berlin",
    "country_code": "DE"
 },
 "items": [
   {
     "item_id": "15c3aa83-3f73-4ad6-a326-e1a10a89dd52",
     "ean": "4059701022541",
     "price": 99.95,
     "currency": "EUR",
     "article_number": "31.832.34-6,5",
     "article_location": "213",
     "return_reason_code": 1,
     "return_location": "STORE"
   }
 ]
}