> 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/customs-catalog-api/fulfillment-api/use-cases.md).

# Use Cases

Seven end-to-end scenarios showing how the Fulfillment API could be used.

{% hint style="warning" icon="boxes-stacked" %}

#### USE CASE 1

{% endhint %}

## New Season Stock Onboarding

A retailer confirms new season collection arriving at the Dublin fulfillment centre. The 3PL system must register expected stock, then confirm receipt and activate each SKU once goods are put away.

#### `Inventory/Sync` — 3PL Integration

\
APIs: `POST /v1/Inventory/Sync`\
Outcome: Stock available to fulfil orders

{% stepper %}
{% step %}

#### Pre-announce arriving stock with Expected status

When the retailer confirms an inbound delivery, the 3PL system calls `Inventory/Sync` with `articleStatus:Expected` and the anticipated quantities. This lets ESW's order routing know stock is inbound and earmarks it for pending orders before physical arrival.

{% code expandable="true" %}

```json
POST /v1/Inventory/Sync
Authorization: Bearer {token}
Content-Type: application/json

{
  "tenantCode":          "ACMTEN",
  "fulfillmentCentreId": "FC-DUB-01",
  "provider":            "XPO-LOGISTICS",
  "items": [
    {
      "sku":               "ACM-SS25-DRESS-BLK-S",
      "variantProductCode": "DRESS-BLK-S",
      "ean":               "5901234123457",
      "size":              "S",
      "color":             "BLACK",
      "articleStatus":     "Expected",
      "quantity":          200
    },
    {
      "sku":               "ACM-SS25-DRESS-BLK-M",
      "variantProductCode": "DRESS-BLK-M",
      "ean":               "5901234123464",
      "size":              "M",
      "color":             "BLACK",
      "articleStatus":     "Expected",
      "quantity":          350
    },
    {
      "sku":               "ACM-SS25-DRESS-BLK-L",
      "variantProductCode": "DRESS-BLK-L",
      "ean":               "5901234123471",
      "size":              "L",
      "color":             "BLACK",
      "articleStatus":     "Expected",
      "quantity":          275
    }
  ]
}
```

{% endcode %}

Response: <mark style="color:$success;">`202`</mark> Accepted — no body

{% code expandable="true" %}

```json
HTTP/1.1 202 Accepted
// No response body. The platform has queued the sync for processing.
// Do not call again immediately — allow for async processing.
```

{% endcode %}
{% endstep %}

{% step %}

#### Physical goods arrive — Receiving and Putaway

The inbound delivery arrives at the dock. The 3PL team scans every carton against the purchase order, verifies quantities and condition, and puts stock away into pick locations. This is a physical warehouse operation — no API call is made at this moment.
{% endstep %}

{% step %}

#### Activate received SKUs

Once putaway is complete, the 3PL system calls `Inventory/Sync` again with `articleStatus:Active` and the actual verified quantities. This unlocks the stock for order fulfillment.&#x20;

&#x20;`POST /v1/Inventory/Sync` — Activate Received Stock

{% code expandable="true" %}

```json
{
  "tenantCode":          "ACMTEN",
  "fulfillmentCentreId": "FC-DUB-01",
  "provider":            "XPO-LOGISTICS",
  "items": [
    {
      "sku":           "ACM-SS25-DRESS-BLK-S",
      "ean":           "5901234123457",
      "articleStatus": "Active",
      "quantity":      198    // 2 units short-delivered vs Expected 200
    },
    {
      "sku":           "ACM-SS25-DRESS-BLK-M",
      "ean":           "5901234123464",
      "articleStatus": "Active",
      "quantity":      350
    },
    {
      "sku":           "ACM-SS25-DRESS-BLK-L",
      "ean":           "5901234123471",
      "articleStatus": "Active",
      "quantity":      275
    }
  ]
}
```

{% endcode %}
{% endstep %}
{% endstepper %}


---

# 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/customs-catalog-api/fulfillment-api/use-cases.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.