> For the complete documentation index, see [llms.txt](https://developer.esw.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.esw.com/order-api/resources/postman-collection/order-lifecycle.md).

# Order Lifecycle

### <img src="/files/3Hzf3CWYWyHDFskuSRKJ" alt="" data-size="line"> What This Collection Does

This Postman collection covers the **Order Lifecycle** — the sequence of API calls that takes a new retail order from creation through confirmation, allocation, and internal annotation.

{% hint style="info" %}
You need [**Postman**](https://postman.com/) to use this collection
{% endhint %}

{% file src="/files/SU9tMpIviwcbiwr52S4T" %}

The five steps represent the core path every order follows:

```ruby
Create → Retrieve → Inspect Transaction → Allocate → Comment
```

It uses the **ESW Order Transaction API v2** and is designed to be run in order, with each step building on the previous one through shared collection variables that are automatically populated as you go.

***

### Import the Collection

{% stepper %}
{% step %}

#### Open Postman&#x20;

{% endstep %}

{% step %}

#### Click the three dots <i class="fa-ellipsis">:ellipsis:</i>

Click **Import** from the three dots in the top left corner
{% endstep %}

{% step %}

#### Upload file <i class="fa-file-code">:file-code:</i>

Drag and drop `ESW_Order_Lifecycle.postman_collection.json` into the import window, or click **Upload Files** and select it
{% endstep %}

{% step %}

#### Confirm

Click **Import** to confirm

{% hint style="info" %}
The collection will appear in your left sidebar under **Collections** as:

{% code expandable="true" %}

```ruby
ESW Order Transaction API — Order Lifecycle
```

{% endcode %}

Expand it to see all ten requests listed in step order.
{% endhint %}
{% endstep %}
{% endstepper %}

***

### Set Up Variables

The collection uses variables. Set them once and every request picks them up automatically.

**To set them:**

1. Click the collection name in the sidebar
2. Click the **Variables** tab at the top of the right panel

<figure><img src="/files/BxAYyK1cWJMHZSnQlmD4" alt=""><figcaption></figcaption></figure>

Fill in the column

| Variable               | What to enter                                          | Example                                                |
| ---------------------- | ------------------------------------------------------ | ------------------------------------------------------ |
| `baseUrl`              | The API base URL                                       | `https://order-transaction-api.sandbox.eshopworld.com` |
| `token`                | Your Bearer JWT                                        | `eyJhbGci...`                                          |
| `tenantCode`           | Your retailer's tenant code                            | `ACME`                                                 |
| `brandOrderReference`  | Leave as default — auto-generated by Step 1            | `ORD-2024-00001`                                       |
| `transactionReference` | Leave as default — auto-populated from Step 1 response | `TXN-2024-00001`                                       |
| `allocationId`         | Your warehouse allocation ID, or leave blank           | `ALLOC-2024-00001`                                     |

**Step 3** — Click **Save** (`Cmd + S` on Mac / `Ctrl + S` on Windows)

#### How variables are auto-managed

`brandOrderReference` and `transactionReference` are managed automatically by the collection scripts:

* **Before Step 1 runs**, the pre-request script checks if `brandOrderReference` is still set to the default `ORD-2024-00001`. If so, it generates a unique value using the current timestamp (e.g. `ORD-1714556400123`) and sets both `brandOrderReference` and `transactionReference` automatically.
* **After Step 1 completes**, the test script reads the `transactionReference` returned in the API response and saves it to the variable, overwriting the pre-generated value with the one the API actually used.

This means you can run Steps 2 through 5 immediately after Step 1 without touching any variables.

***

### Authentication

The collection is configured with **Bearer Token** authentication at the collection level, so every request automatically includes:

```ruby
Authorization: Bearer {{token}}
```

**To verify it's in place:**

1. Click the collection name in the sidebar
2. Click the **Authorization** tab in the right panel
3. The **Auth Type** dropdown should show **Bearer Token**
4. The **Token** field should show `{{token}}`

You do not need to set auth on individual requests — they all inherit from the collection. In the current Postman UI, this is shown as **Inherit auth from parent** when you open any individual request's Authorization tab.

***

### Order Lifecycle Flow

{% code expandable="true" %}

```ruby
┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│  Step 1 — Create Order                   POST                  │
│  Submit the order with line items,                              │
│  contact details, delivery and payment   → 202 Accepted        │
│                          │                                      │
│                          ▼  (async — wait for processing)      │
│  Step 2 — Retrieve Order                 GET                   │
│  Poll to confirm the order was created                          │
│  and check its status                    → 200 OK              │
│                          │                                      │
│                          ▼                                      │
│  Step 3 — Retrieve Transaction           GET                   │
│  Inspect the OrderCreate transaction                            │
│  to confirm it processed successfully    → 200 OK              │
│                          │                                      │
│                          ▼                                      │
│  Step 4 — Allocate Order                 POST                  │
│  Confirm stock and readiness                                    │
│  for fulfilment                          → 202 Accepted        │
│                          │                                      │
│                          ▼                                      │
│  Step 5 — Add Comment                    POST                  │
│  Attach an internal note to the                                 │
│  order for audit and tracking            → 200 OK              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

{% endcode %}

**Async vs sync:**

| Step                          | Processing | What the response means                          |
| ----------------------------- | ---------- | ------------------------------------------------ |
| Step 1 — Create               | Async      | `202` = queued, not yet created                  |
| Step 2 — Retrieve             | Sync       | `200` = current state of the order               |
| Step 3 — Retrieve Transaction | Sync       | `200` = current state of the transaction         |
| Step 4 — Allocate             | Async      | `202` = queued, or `200` = immediately processed |
| Step 5 — Comment              | Sync       | `200` = saved immediately                        |

For async steps, use **Step 2 (Retrieve Order)** to poll until the order reflects the expected state before moving forward.

***

### Step 1 — Create Order

**Method:** `POST` **URL:** `{{baseUrl}}/v2/{{tenantCode}}/Order`

#### What it does

Submits a new order to ESW. The sample body includes two line items, a German delivery address, standard delivery, credit card payment, a retailer invoice, origin details, and two metadata items.

#### Opening the request in Postman

Click **Step 1 — Create Order** in the sidebar. The request opens in a new tab showing four main tabs across the top: **Params**, **Authorization**, **Headers**, **Body**.

#### The request body

Click the **Body** tab, then confirm **raw** and **JSON** are selected in the dropdowns.

The body is pre-filled with sample data. Before sending for a real order, replace the sample values with the actual order data:

{% code expandable="true" %}

```json
{
  "brandOrderReference": "{{brandOrderReference}}",
  "orderType": "Checkout",
  "transactionReference": "{{transactionReference}}",
  "transactionDateTime": "2024-05-01T10:00:00Z",
  "actionedBy": "Retailer",
  "actionedByUser": "system@acmefashion.com",
  "shopperCurrencyIso": "EUR",
  "retailerCurrencyIso": "EUR",
  "deliveryCountryIso": "DE",
  "shopperExperience": {
    "shopperCultureLanguageIso": "de-DE",
    "registeredProfileId": "SHOPPER-98765"
  },
  "contactDetails": [ ... ],
  "lineItems": [ ... ],
  "deliveryOption": { ... },
  "payment": { ... }
}
```

{% endcode %}

#### Pre-request script — auto-generating references

Before the request is sent, Postman runs a script that checks `brandOrderReference`. If it's still the default placeholder value (`ORD-2024-00001`), the script generates a unique pair of references using the current timestamp:

```
brandOrderReference  →  ORD-1714556400123
transactionReference →  TXN-1714556400123
```

These are written to the collection variables automatically. The `{{brandOrderReference}}` and `{{transactionReference}}` placeholders in the request body are then resolved to these generated values at send time.

**To use a specific order reference instead of the auto-generated one:**

Update the **Current Value** of `brandOrderReference` in the Variables tab to your desired value before running Step 1. The script only generates a new one if the value is the default.

#### Sending the request

Click the blue **Send** button. The request fires and the response appears in the bottom panel.

#### Expected response — 202 Accepted

```json
{
  "transactionReference": "TXN-2024-00001"
}
```

The response body contains the `transactionReference` that ESW assigned to this operation. The test script saves this value to the `transactionReference` collection variable automatically, replacing any pre-generated value.

#### Saved example responses

Click **Examples** (the dropdown next to **Send**) to see the saved responses:

| Example                              | When it applies                                     |
| ------------------------------------ | --------------------------------------------------- |
| `202 Accepted — Order Queued`        | Normal success case — order received and queued     |
| `400 Bad Request — Validation Error` | A required field is missing or has an invalid value |

#### Test results

After sending, click the **Test Results** tab in the response panel:

| Test                                     | What it checks                          |
| ---------------------------------------- | --------------------------------------- |
| `Order accepted (202)`                   | Status code is 202                      |
| `Response contains transactionReference` | Body has a `transactionReference` field |

Both should be green before proceeding to Step 2.

#### Console output

Open the **Postman Console** (`View → Postman Console` or `Cmd/Ctrl + Alt + C`) to see:

```ruby
Generated brandOrderReference: ORD-1714556400123
Generated transactionReference: TXN-1714556400123
✓ Order queued. transactionReference: TXN-1714556400123
Run Step 2 to retrieve the order and confirm processing.
```

***

### Step 2 — Retrieve Order

**Method:** `GET` **URL:** `{{baseUrl}}/v2/{{tenantCode}}/Order/{{brandOrderReference}}`

#### What it does

Fetches the current state of the order. Run this after Step 1 to confirm the order exists in ESW and to monitor its processing status. Also use it as a polling step after any write operation (Step 4 Allocate, or any operation from the Cancellation or Modifications collections) to confirm the update has been applied.

#### No body required

This is a GET request. There is nothing to edit in the Body tab. The `brandOrderReference` in the URL path is resolved from the collection variable set in Step 1.

#### Sending the request

Click **Send**. The response returns immediately with the full order record.

#### Expected response — 200 OK

{% code expandable="true" %}

```json
{
  "orderType": "Checkout",
  "orderGuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "Received",
  "brandOrderReference": "ORD-1714556400123",
  "eShopWorldOrderNumber": "ESW-987654321",
  "shopperCurrencyIso": "EUR",
  "deliveryCountryIso": "DE",
  "orderDate": "2024-05-01T10:00:00Z",
  "lineItems": [ ... ],
  "transactions": [
    {
      "transactionReference": "TXN-1714556400123",
      "type": "OrderCreate",
      "status": "Processed"
    }
  ]
}
```

{% endcode %}

**Key fields to check:**

| Field                   | What to look for                                                      |
| ----------------------- | --------------------------------------------------------------------- |
| `status`                | `Received` = order is live. `Cancelled` = order has been cancelled.   |
| `eShopWorldOrderNumber` | ESW's internal reference. `null` or missing = still processing.       |
| `transactions[].status` | `Processed` = done. `InProgress` = still running. `Failed` = problem. |

#### Test results

| Test                               | What it checks                    |
| ---------------------------------- | --------------------------------- |
| `Order retrieved (200)`            | Status code is 200                |
| `Response has brandOrderReference` | Body contains the order reference |
| `Response has status field`        | Body contains the order status    |

#### Console output

```ruby
Order status: Received
ESW order number: ESW-987654321
Line items: 2
Transactions: 1
OrderCreate transaction status: Processed
✓ Order successfully processed. Safe to proceed with Step 3 or 4.
```

**If you see** `⏳ Order still processing` — wait 30–60 seconds and re-run Step 2. Do not move to Step 3 or 4 until the `OrderCreate` transaction shows `Processed`.

***

### Step 3 — Retrieve Order Transaction

**Method:** `GET` **URL:** `{{baseUrl}}/v2/{{tenantCode}}/Order/{{brandOrderReference}}/Transaction/{{transactionReference}}`

#### What it does

Fetches the details of a single transaction within the order. While Step 2 shows the full order including a summary of all transactions, Step 3 gives you the deep detail on one specific transaction — status, actioned by, timestamps, and refund amounts if applicable.

At this point in the lifecycle, it's used to inspect the `OrderCreate` transaction from Step 1 in detail.

#### No body required

All three path parameters — `tenantCode`, `brandOrderReference`, `transactionReference` — are resolved from collection variables.

#### Expected response — 200 OK

{% code expandable="true" %}

```json
{
  "type": "OrderCreate",
  "transactionReference": "TXN-1714556400123",
  "status": "Processed",
  "transactionDateTime": "2024-05-01T10:00:00Z",
  "actionedBy": "Retailer",
  "actionedByUser": "system@acmefashion.com",
  "reasonCode": null,
  "lastUpdateTime": "2024-05-01T10:00:45Z",
  "creationTime": "2024-05-01T10:00:01Z",
  "refundAmounts": [],
  "refundAmountsInRetailerCurrency": []
}
```

{% endcode %}

**Transaction status values:**

| Status        | Meaning                | What to do                                                        |
| ------------- | ---------------------- | ----------------------------------------------------------------- |
| `Processed`   | Completed successfully | Proceed to Step 4                                                 |
| `InProgress`  | Still running          | Wait and re-run Step 3                                            |
| `Unprocessed` | Queued but not started | Wait and re-run Step 3                                            |
| `Failed`      | Something went wrong   | Check the transaction details and retry the originating operation |

#### Test results

| Test                           | What it checks                      |
| ------------------------------ | ----------------------------------- |
| `Transaction retrieved (200)`  | Status code is 200                  |
| `Response has type and status` | Body has `type` and `status` fields |

#### Console output

```ruby
Transaction type:   OrderCreate
Transaction status: Processed
Actioned by:        Retailer
Created:            2024-05-01T10:00:01Z
Last updated:       2024-05-01T10:00:45Z
✓ Transaction successfully processed.
```

#### Using Step 3 for other transaction types

Later in the order lifecycle — after running an allocation, cancellation, or appeasement — you can reuse Step 3 to inspect those transactions. Before sending:

1. Go to the collection **Variables** tab
2. Update `transactionReference` to the reference returned by the operation you want to inspect
3. Run Step 3

***

### Step 4 — Allocate Order

**Method:** `POST` **URL:** `{{baseUrl}}/v2/{{tenantCode}}/Order/{{brandOrderReference}}/Allocation`

#### What it does

Allocates one or more line items within the order, confirming that stock is available and the order is ready for fulfilment. This signals to ESW that the warehouse has committed to fulfilling the items.

Partial allocation is supported — you can allocate a subset of line items and run Step 4 again for the rest.

#### The request body

{% code expandable="true" %}

```json
{
  "transactionReference": "TXN-ALLOC-{{$timestamp}}",
  "transactionDateTime": "{{$isoTimestamp}}",
  "actionedBy": "Retailer",
  "actionedByUser": "warehouse@acmefashion.com",
  "allocationId": "{{allocationId}}",
  "lineItems": [
    {
      "lineItemId": "LI-001",
      "productCode": "WMN-DRESS-001",
      "quantity": 1
    },
    {
      "lineItemId": "LI-002",
      "productCode": "KID-SNEAKER-07",
      "quantity": 2
    }
  ]
}
```

{% endcode %}

**Dynamic variables used in this request:**

The body uses two of Postman's built-in dynamic variables:

| Variable            | What it generates                    | Example                    |
| ------------------- | ------------------------------------ | -------------------------- |
| `{{$timestamp}}`    | Unix timestamp (seconds since epoch) | `1714556400`               |
| `{{$isoTimestamp}}` | ISO 8601 UTC datetime                | `2024-05-01T10:00:00.000Z` |

These ensure every allocation request has a unique `transactionReference` without you needing to manually change it each time. Postman resolves them automatically at send time.

**Before sending:**

* Confirm `lineItemId` and `productCode` values match what was submitted in Step 1
* If allocating a subset of items, remove the line items not being allocated in this call
* Set `allocationId` in the Variables tab if your warehouse system provides an allocation reference, or leave it as the placeholder — it's optional

#### Test results

| Test                                            | What it checks                          |
| ----------------------------------------------- | --------------------------------------- |
| `Allocation accepted or processed (202 or 200)` | Status is 202 or 200                    |
| `Response contains transactionReference`        | Body has a `transactionReference` field |

#### Console output

If 202:

```ruby
✓ Allocation queued. transactionReference: TXN-ALLOC-1714556400
Wait a moment, then run Step 2 to confirm the order is allocated.
```

If 200:

```ruby
✓ Allocation processed immediately. transactionReference: TXN-ALLOC-1714556400
```

**After getting 202:** Run Step 2 after 1–2 minutes and look for an `OrderAllocated` or `OrderPartiallyAllocated` transaction in the `transactions` array with `status: Processed`.

***

### Step 5 — Add Comment to Order

**Method:** `POST` **URL:** `{{baseUrl}}/v2/{{tenantCode}}/Order/{{brandOrderReference}}/Comment`

#### What it does

Attaches a free-text comment to the order record. Use this for internal notes, customer service actions, warehouse confirmations, or any audit trail entry that doesn't map to a formal transaction type.

Unlike Steps 1 and 4, this is **synchronous** — `200 OK` means the comment was saved immediately, not queued.

#### The request body

```json
{
  "comment": "Order allocated and confirmed by warehouse team. Ready for dispatch on 2024-05-02.",
  "user": "warehouse@acmefashion.com"
}
```

**Fields:**

| Field     | Required | Description                                                    |
| --------- | -------- | -------------------------------------------------------------- |
| `comment` | Yes      | The text of the comment. No length limit specified in the API. |
| `user`    | No       | Who added the comment. Some integrations leave this null.      |

Replace the sample comment and user with the relevant values before sending.

#### Expected response — 200 OK

```json
{
  "user": "warehouse@acmefashion.com",
  "time": "2024-05-01T10:15:00Z"
}
```

#### Test results

| Test                         | What it checks                              |
| ---------------------------- | ------------------------------------------- |
| `Comment added (200)`        | Status code is 200                          |
| `Response has user and time` | Body contains both `user` and `time` fields |

#### Console output

Step 5 prints a lifecycle summary to the console on completion:

```ruby
✓ Comment saved.
  User: warehouse@acmefashion.com
  Time: 2024-05-01T10:15:00Z

=== Order Lifecycle Complete ===
Order reference:       ORD-1714556400123
Transaction reference: TXN-1714556400123
Steps completed: Create → Retrieve → Transaction → Allocate → Comment
```

***

### Run Collection

The Collection Runner executes all five steps automatically in sequence. This is useful for testing the full lifecycle end-to-end or for verifying the pipeline after an API change.

#### Opening the Collection Runner

In the current Postman UI:

1. Hover over the collection name in the left sidebar
2. Click the **⋯** (three dots) menu that appears to the right
3. Select **Run**

#### Recommended settings

| Setting                             | Recommended value | Where to find it                                                                |
| ----------------------------------- | ----------------- | ------------------------------------------------------------------------------- |
| **Iterations**                      | `1`               | Run configuration section                                                       |
| **Delay**                           | `2000` ms         | Run configuration — gives async operations time to queue                        |
| **Persist responses for a session** | ✓ On              | Advanced Settings — lets you review each response after the run                 |
| **Stop run if an error occurs**     | ✓ On              | Advanced Settings — stops if a step fails rather than continuing with bad state |
| **Keep variable values**            | ✓ On              | Advanced Settings — ensures variables set in Step 1 carry through to Steps 2–5  |

> **Important:** Set Delay to at least `2000` ms. Steps 1 and 4 are asynchronous — without a delay, Step 2 may fire before the order has been registered on the ESW side, causing a `404 Not Found`.

#### Which requests to include

All five steps are included by default. Use the toggle to the left of each request name to disable any you want to skip. Common adjustments:

* **Leave all five enabled** for a full end-to-end lifecycle run
* **Disable Step 4** if you're testing in an environment where allocation is not required
* **Disable Step 5** if you don't want to attach a comment during automated runs

#### Starting the run

Click the orange **Run ESW Order Transaction API — Order Lifecycle** button at the bottom of the runner panel.

#### Reviewing the results

After the run completes, the runner shows each request with a pass/fail indicator:

* **Green** — all tests passed, request completed as expected
* **Red** — one or more tests failed

Click any request row to expand it and see the individual test outcomes, the response body, and any console output for that step.

***

### Reading Test Results and Console Output

#### Test Results tab

After sending any individual request, the **Test Results** tab appears in the response panel (next to Body, Cookies, Headers). It shows each test with a green tick or red cross.

**All tests across the collection:**

| Step   | Test name                                       | Passes when                            |
| ------ | ----------------------------------------------- | -------------------------------------- |
| Step 1 | `Order accepted (202)`                          | Response status is 202                 |
| Step 1 | `Response contains transactionReference`        | Body has `transactionReference` key    |
| Step 2 | `Order retrieved (200)`                         | Response status is 200                 |
| Step 2 | `Response has brandOrderReference`              | Body has `brandOrderReference` key     |
| Step 2 | `Response has status field`                     | Body has `status` key                  |
| Step 3 | `Transaction retrieved (200)`                   | Response status is 200                 |
| Step 3 | `Response has type and status`                  | Body has both `type` and `status` keys |
| Step 4 | `Allocation accepted or processed (202 or 200)` | Response status is 202 or 200          |
| Step 4 | `Response contains transactionReference`        | Body has `transactionReference` key    |
| Step 5 | `Comment added (200)`                           | Response status is 200                 |
| Step 5 | `Response has user and time`                    | Body has `user` and `time` keys        |

#### Postman Console

The Console shows richer diagnostic output that doesn't appear in the Test Results tab. Open it via:

* **View → Postman Console** in the menu bar
* Keyboard shortcut: `Cmd + Alt + C` on Mac, `Ctrl + Alt + C` on Windows/Linux

> Open the Console **before** running requests — Postman does not retain console output from requests sent before the Console was open.

**What the Console shows for each step:**

| Step               | Console output                                                                                              |
| ------------------ | ----------------------------------------------------------------------------------------------------------- |
| Step 1 pre-request | Auto-generated `brandOrderReference` and `transactionReference` if defaults were used                       |
| Step 1 post-send   | Confirmation of `transactionReference` received from API                                                    |
| Step 2             | Order status, ESW order number, line item count, transaction count, and `OrderCreate` processing status     |
| Step 3             | Transaction type, status, actioned by, creation time, last updated time                                     |
| Step 4             | Whether allocation was queued (202) or processed immediately (200) and the allocation transaction reference |
| Step 5             | Comment confirmation with user and timestamp, followed by the full lifecycle summary                        |

***

### Order Create — Field Reference

The body for Step 1 supports the following fields. Replace sample values with real data before sending for a live order.

#### Required fields

Every order must include these fields or the API returns `400 Bad Request`:

| Field                  | Type   | Description                               | Example                  |
| ---------------------- | ------ | ----------------------------------------- | ------------------------ |
| `brandOrderReference`  | string | The brand's unique order number           | `"ORD-2024-00001"`       |
| `orderType`            | enum   | Type of order                             | `"Checkout"`             |
| `transactionReference` | string | Unique reference for this transaction     | `"TXN-2024-00001"`       |
| `transactionDateTime`  | string | UTC datetime of order creation (ISO 8601) | `"2024-05-01T10:00:00Z"` |
| `actionedBy`           | enum   | Who initiated the order                   | `"Retailer"`             |
| `shopperCurrencyIso`   | string | ISO 4217 shopper currency                 | `"EUR"`                  |
| `retailerCurrencyIso`  | string | ISO 4217 retailer currency                | `"EUR"`                  |
| `deliveryCountryIso`   | string | ISO 3166 two-letter delivery country      | `"DE"`                   |
| `shopperExperience`    | object | Language and profile info                 | see below                |
| `contactDetails`       | array  | Delivery/billing addresses                | see below                |
| `lineItems`            | array  | Items in the order                        | see below                |
| `deliveryOption`       | object | Delivery method and pricing               | see below                |

#### Enum values reference

**`orderType`**

```
Checkout              Standard eShopWorld checkout order
Offline               Order placed outside eShopWorld checkout
NonCheckoutEcommerce  E-commerce order not using eShopWorld checkout
```

**`actionedBy`**

```
Retailer    ThirdParty    Shopper    EShopWorld
```

**`deliveryOption.eshopDeliveryOptionCode`**

```
DEFAULT    POST    EXP1    EXP2    RussiaExpress    Standard    PUDO
```

**`deliveryOption.type`**

```
NA    Home    Store    PUDO    Digital
```

**`weight.weightUnit`**

```
KG    LB
```

**`originDetails.originType`**

```
None    Store
```

#### `shopperExperience` object

```json
{
  "shopperCultureLanguageIso": "de-DE",
  "registeredProfileId": "SHOPPER-98765"
}
```

`shopperCultureLanguageIso` is required — use ISO 639-1 language code + ISO 3166 country code (e.g. `en-US`, `fr-FR`, `de-DE`).

#### `contactDetails` array

Each entry represents one contact record (delivery or billing):

{% code expandable="true" %}

```json
{
  "type": "Delivery",
  "firstName": "Anna",
  "lastName": "Müller",
  "address1": "Hauptstraße 12",
  "city": "Berlin",
  "postalCode": "10115",
  "region": "BE",
  "country": "DE",
  "email": "anna.muller@example.com",
  "telephone": "+4930123456789"
}
```

{% endcode %}

#### `lineItems` array

Each entry is one SKU in the order:

{% code expandable="true" %}

```json
{
  "lineItemId": "LI-001",
  "productCode": "WMN-DRESS-001",
  "description": "Floral Wrap Dress - Size M",
  "quantity": 1,
  "unitPrice": {
    "price": {
      "currency": "EUR",
      "amount": "89.99"
    }
  },
  "hsCode": "620442",
  "countryOfOrigin": "IE",
  "weight": {
    "weightTotal": 0.35,
    "weightUnit": "KG"
  }
}
```

{% endcode %}

`lineItemId` must be unique within the order and is used to reference specific items in later operations (cancellation, allocation, replacement).

#### Optional top-level fields

| Field                       | Description                                                                                     |
| --------------------------- | ----------------------------------------------------------------------------------------------- |
| `parentBrandOrderReference` | For replacement orders — reference to the original order                                        |
| `externalOrderId`           | An external system's order identifier                                                           |
| `actionedByUser`            | Email or name of the person who initiated the action                                            |
| `weight`                    | Total order weight (`weightTotal` + `weightUnit`)                                               |
| `retailerInvoice`           | Invoice number and date (`number`, `date` in `yyyy-MM-dd` format)                               |
| `payment`                   | Payment method, last 4 digits, payment reference, price info, status                            |
| `originDetails`             | Dispatch origin address — required fields: `address1`, `city`, `country`, `email`, `originType` |
| `metadataItems`             | Array of `{ "key": "...", "value": "..." }` pairs for custom data                               |
| `channelType`               | Sales channel (e.g. `"Web"`, `"Mobile"`)                                                        |

***

### Common Scenarios

#### "Running the lifecycle for a real order"

1. Update `tenantCode` in Variables to your retailer's code
2. Open Step 1, go to Body, replace the sample product codes, line item IDs, contact details, and amounts with the real order data
3. Run Steps 1 through 5 in sequence
4. After Step 4, re-run Step 2 to confirm the order shows an `OrderAllocated` transaction

***

#### "Testing with a fresh order reference each run"

Leave `brandOrderReference` set to the default `ORD-2024-00001`. The pre-request script on Step 1 will auto-generate a unique reference using a timestamp on every run. No manual changes needed.

***

#### "Inspecting a specific transaction after an allocation"

1. Run Step 4 and note the `transactionReference` in the response (also logged in the Console)
2. Go to the collection **Variables** tab and update `transactionReference` to the allocation reference
3. Run Step 3 — it will now return the allocation transaction details rather than the create transaction

***

#### "Partially allocating an order"

In Step 4, edit the `lineItems` array to include only the items being allocated:

```json
"lineItems": [
  {
    "lineItemId": "LI-001",
    "productCode": "WMN-DRESS-001",
    "quantity": 1
  }
]
```

Send. Then run Step 2 and check for `OrderPartiallyAllocated` in the transactions array. Run Step 4 again for the remaining item when it's ready.

***

#### "The order isn't appearing after Step 1"

Step 1 is asynchronous. The order may still be processing. Wait 30–60 seconds and re-run Step 2. Check the Console output for the `OrderCreate` transaction status — `InProgress` means it's still running, `Processed` means it's done.

***

### Troubleshooting

**`401 Unauthorized` on any request** The JWT token has expired. Get a new one and update the `token` variable in the Variables tab. Click Save.

***

**`400 Bad Request` on Step 1** A required field is missing or has an invalid value. The response body under the **Body** tab will contain a `detail` message identifying the field. Common causes:

* `deliveryCountryIso` — must be exactly 2 uppercase letters (`DE`, not `Germany` or `de`)
* `shopperCurrencyIso` / `retailerCurrencyIso` — must be 3-letter ISO 4217 codes (`EUR`, not `Euro`)
* `orderType` — must be one of `Checkout`, `Offline`, `NonCheckoutEcommerce` exactly
* `transactionReference` — must be unique; if you're re-running Step 1 without auto-generation, change this value
* `shopperExperience.shopperCultureLanguageIso` — must be in `language-COUNTRY` format (`de-DE`, not `de` or `German`)

***

**`404 Not Found` on Step 2 immediately after Step 1** The order hasn't been registered yet — Step 1 is asynchronous. Wait 30–60 seconds and re-run Step 2.

***

**`404 Not Found` on Step 3** Either the `transactionReference` variable has been manually changed, or the transaction hasn't been created yet. Check the Variables tab to confirm `transactionReference` matches the value returned in the Step 1 response.

***

**Step 4 returns `404 Not Found`** The order doesn't exist or the `brandOrderReference` is wrong. Confirm the variable is set correctly by opening the Variables tab. Also confirm Step 2 returned `200 OK` before running Step 4.

***

**`{{brandOrderReference}}` appears literally in the request URL** The variable is not set. Open the Variables tab, confirm `brandOrderReference` has a **Current Value**, and click Save. If the auto-generation script ran, check the Console — the generated value should be logged there.

***

**Console shows nothing** The Postman Console must be open before the request is sent — it does not capture output from previous runs. Open it with `Cmd + Alt + C` (Mac) or `Ctrl + Alt + C` (Windows/Linux), then re-run the request.

***

**Collection Runner stops at Step 2 with `404`** The Delay is set too low. Stop the run, go back to the runner settings, increase Delay to `2000` ms or higher, and start again. The 2-second gap gives the ESW platform time to register the order before Step 2 tries to retrieve it.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://developer.esw.com/order-api/resources/postman-collection/order-lifecycle.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.