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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://m-board.gitbook.io/docs/orders-api-webhook.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.