> For the complete documentation index, see [llms.txt](https://m-board.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://m-board.gitbook.io/docs/orders-api-webhook.md).

# Orders API (Webhook)

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

{% hint style="info" %}
An **API Key** (Password) is required to communicate with the webhook. \
The credentials can be obtained from [support@michelberger.digital](email:support@michelberger.digital).
{% endhint %}

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:

<table><thead><tr><th width="301.3333333333333">Field</th><th width="150">Data Type</th><th width="123">Manadory</th><th width="200">Description</th></tr></thead><tbody><tr><td><code>source</code></td><td>String</td><td>required</td><td>Name of the source system.  Description of source can be found in “Source Description” section</td></tr><tr><td><code>channel</code></td><td>String</td><td>optional</td><td>Name of the channel. Description of channel can be found in “Channel Description” section</td></tr><tr><td><code>event_id</code></td><td>String</td><td>required</td><td>Unique id of the event</td></tr><tr><td><code>order_id</code></td><td>String</td><td>required</td><td>Order id of channel</td></tr><tr><td><code>order_number</code></td><td>String</td><td>required</td><td>Order number displayed to customer </td></tr><tr><td><code>state</code></td><td>String</td><td>required</td><td>Allowed values: <code>assigned</code>, <code>fulfilled</code>, <code>returned</code> and <code>cancelled</code></td></tr><tr><td><code>store_id</code></td><td>String</td><td>required</td><td>Store id</td></tr><tr><td><code>timestamp</code></td><td>String</td><td>required</td><td>ISO 8061 timestamp</td></tr><tr><td><code>delivery_details</code></td><td>JSON Object</td><td></td><td>Delivery and return tracking information</td></tr><tr><td><code>customer_billing_address</code></td><td>JSON Object</td><td></td><td>Name and billing address of the customer</td></tr><tr><td><code>items</code></td><td>Array</td><td>required</td><td><p>Items that were affected by the state transition</p><ul><li>for fulfilled order the list of items that were shipped excluding cancelled items</li><li>for cancelled order the list of items that were cancelled (i.e. all items of the order)</li><li>for routed order all items of the order</li><li>for assigned order all items of the order</li><li>for returned order the list of items that were returned at this particular moment by the customer</li></ul></td></tr><tr><td><code>cancelled_items</code></td><td>Array</td><td></td><td><p>Items that were cancelled in the partially fulfilled order</p><ul><li>will only contain cancelled items when a fulfilled order has both shipped and cancelled items</li><li>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</li></ul></td></tr><tr><td><code>is_giftcard</code></td><td>Boolean</td><td></td><td>Specifies if the order is a gift card.<br>Default: <code>false</code></td></tr><tr><td><code>is_pickup</code></td><td>Boolean</td><td></td><td>A Click &#x26; Collect order where the customer picks up items at a physical store.<br><br>Default: <code>false</code></td></tr></tbody></table>

Item has the following schema:

<table><thead><tr><th width="301.3333333333333">Field</th><th width="150">Data Type</th><th width="114">Manadory</th><th width="200">Description</th><th>Example</th></tr></thead><tbody><tr><td><code>item_id</code></td><td>String</td><td>required</td><td>Item id of channel</td><td><code>15c3aa83-3f73-4ad6-a326-e1a10a89dd52</code></td></tr><tr><td><code>ean</code></td><td>String</td><td>required</td><td>EAN of the article</td><td><code>4059701022541</code></td></tr><tr><td><code>price</code></td><td>Number</td><td>required</td><td>Price of the article</td><td><code>99.95</code> or <code>12</code></td></tr><tr><td><code>currency</code></td><td>String</td><td>required</td><td>ISO-4217 currency code</td><td><code>EUR</code></td></tr><tr><td><code>article_number</code></td><td>String</td><td>required</td><td>Article number (SKU)</td><td><code>31.832.34-6,5</code></td></tr><tr><td><code>channel_article_number</code></td><td>String</td><td></td><td>Article number of channel</td><td><code>DU341A00M-1020375000</code></td></tr><tr><td><code>article_location</code></td><td>String</td><td></td><td>Location of the article</td><td><code>213</code></td></tr><tr><td><code>return_reason_code</code></td><td>Number</td><td></td><td>Reason number associated to return reason, description of code can be found in “Return Reason Code Description” section</td><td><code>1</code></td></tr><tr><td><code>return_location</code></td><td>String</td><td></td><td>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"</td><td>Allowed values:<br><code>STORE</code> or <code>WAREHOUSE</code></td></tr><tr><td><code>cancellation_reason</code></td><td>String</td><td></td><td>The "Cancellation Reason Description" section contains the item's cancellation reason and a description of the values</td><td><code>OUT_OF_STOCK</code></td></tr></tbody></table>

`delivery_details` has the following schema:

<table><thead><tr><th width="301.3333333333333">Field</th><th width="150">Data Type</th><th width="115">Manadory</th><th width="200">Description</th><th>Examples</th></tr></thead><tbody><tr><td><code>delivery_tracking_number</code></td><td>String</td><td></td><td>delivery tracking number</td><td><code>003404342888680268172</code></td></tr><tr><td><code>delivery_carrier_name</code></td><td>String</td><td></td><td>delivery carrier name</td><td><code>DHL</code></td></tr><tr><td><code>return_tracking_number</code></td><td>Number</td><td></td><td>return tracking number</td><td><code>35141263178</code></td></tr><tr><td><code>return_carrier_name</code></td><td>String</td><td></td><td>return carrier name</td><td><code>DHL</code></td></tr></tbody></table>

customer\_billing\_address has the following schema:

<table><thead><tr><th width="301.3333333333333">Field</th><th width="150">Data Type</th><th>Manadory</th><th width="200">Description</th></tr></thead><tbody><tr><td><code>first_name</code></td><td>String</td><td>required</td><td>first name of the customer</td></tr><tr><td><code>last_name</code></td><td>String</td><td>required</td><td>last name of the customer</td></tr><tr><td><code>address_line_1</code></td><td>String</td><td>required</td><td>first line of the billing address</td></tr><tr><td><code>address_line_2</code></td><td>String</td><td></td><td>additional information about the billing address, e.g. NIP for Poland, More detailed description of address and addressee or additional instructions</td></tr><tr><td><code>address_line_3</code></td><td>String</td><td></td><td>further additional information about the billing address</td></tr><tr><td><code>zip_code</code></td><td>String</td><td>required</td><td>billing address zip code</td></tr><tr><td><code>city</code></td><td>String</td><td>required</td><td>billing address city</td></tr><tr><td><code>country_code</code></td><td>String</td><td>required</td><td>billing address country code</td></tr></tbody></table>

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

{% hint style="info" %}
Source system missing? Contact us [support@michelberger.digital](mail:support@michelberger.digital)
{% endhint %}

#### Channel description

| Channel      | Description                                                                         |
| ------------ | ----------------------------------------------------------------------------------- |
| `zalando_de` | [zalando.de](https://zalando.de)                                                    |
| `zalando_ch` | [zalando.ch](https://zalando.ch)                                                    |
| `zalando_at` | [zalando.at](https://zalando.at)                                                    |
| `zalando_it` | [zalando.it](https://zalando.it)                                                    |
| `amazon_de`  | [amazon.de](https://amazon.de)                                                      |
| `amazon_ch`  | [amazon.ch](https://amazon.ch)                                                      |
| `amazon_at`  | [amazon.at](https://amazon.at)                                                      |
| `amazon_it`  | [amazon.it](https://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 |
| ...          | ...                                                                                 |

{% hint style="info" %}
Channel missing? Contact us [support@michelberger.digital](mail:support@michelberger.digital)
{% endhint %}

### Examples of events

#### Assigned event

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

```json
{
 "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:

```javascript
{
 "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:

```javascript
{
 "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:

```javascript
{
 "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"
   }
 ]
}
```