> 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/inventory/inventory-api/use-cases.md).
# Use Cases
Four end-to-end scenarios showing how to use the Inventory API to keep availability in sync, check selected SKUs for a delivery market, and handle failures safely.
Four scenarios showing how the Inventory API could be used. SKU values, quantities and the `FR` delivery country are illustrative.
## Quick Reference
The API has two endpoints on the same path. The method decides whether you receive every applicable SKU or only the SKUs you ask for.
| Method | Endpoint | Purpose |
| ------ | --------------------------------------------------- | ----------------------------------------------------------------------------- |
| `GET` | `/inventory/v1/{identifier}/inventory-availability` | Retrieve ATS quantities for all applicable SKUs |
| `POST` | `/inventory/v1/{identifier}/inventory-availability` | Retrieve ATS quantities for a list of SKUs, optionally for a delivery country |
{% hint style="warning" icon="boxes-stacked" %}
#### USE CASE 1
{% endhint %}
## Full Inventory Availability Feed
A commerce platform integration keeps a local availability store aligned with ESW. It needs the current Available-to-Sell (ATS) quantity for every applicable SKU, without maintaining a SKU list.
API: `GET /inventory/v1/{identifier}/inventory-availability`
Outcome: Local availability reflects ESW ATS for all applicable SKUs
{% stepper %}
{% step %}
#### Authenticate
Obtain an access token and send it as `Authorization: Bearer {access_token}`. See [Authentication](/inventory/inventory-api/authentication.md).
{% endstep %}
{% step %}
#### Request the complete availability set
Call the GET endpoint with your retailer identifier. No request body and no SKU list are required.
{% code expandable="true" %}
```bash
curl --request GET 'https://api.sandbox.esw.com/inventory/v1/{identifier}/inventory-availability' \
--header 'Authorization: Bearer {access_token}'
```
{% endcode %}
Response: `200` OK
{% code expandable="true" %}
```json
[
{ "sku": "SKU123", "quantity": 57 },
{ "sku": "SKU456", "quantity": 12 }
]
```
{% endcode %}
{% endstep %}
{% step %}
#### Update the local store
Write each returned `quantity` against its `sku`. Quantities are integers that are always zero or greater. Apply a `0` as a genuine zero-ATS position only because it arrived in a successful response.
{% endstep %}
{% endstepper %}
Sequence summary: `GET /inventory-availability` → update local availability per SKU
{% hint style="warning" icon="truck-front" %}
#### USE CASE 2
{% endhint %}
## Availability for Selected SKUs in a Delivery Market
A storefront is rendering a basket for a shopper delivering to France. It needs ATS for just the SKUs in the basket, for that market.
API: `POST /inventory/v1/{identifier}/inventory-availability`
Outcome: Availability for the basket SKUs, based on the fulfillment centers that serve France
{% stepper %}
{% step %}
#### Send the SKU list with the delivery country
`skus` is required. `deliveryCountryIso` is optional; supply the shopper's two-character ISO delivery country code so ESW can determine the inventory applicable to that market. You do not need to identify the fulfillment locations.
{% code expandable="true" %}
```bash
curl --request POST 'https://api.sandbox.esw.com/inventory/v1/{identifier}/inventory-availability' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
--data '{
"deliveryCountryIso": "FR",
"skus": ["SKU123", "SKU456"]
}'
```
{% endcode %}
{% endstep %}
{% step %}
#### Use the aggregated quantities
Each quantity is aggregated across the fulfillment centers applicable to the supplied delivery country.
Response: `200` OK
{% code expandable="true" %}
```json
[
{ "sku": "SKU123", "quantity": 57 },
{ "sku": "SKU456", "quantity": 8 }
]
```
{% endcode %}
{% endstep %}
{% endstepper %}
Sequence summary: `POST /inventory-availability` (`skus` + `deliveryCountryIso`) → use quantities for the basket
{% hint style="warning" icon="arrow-progress" %}
#### USE CASE 3
{% endhint %}
## Why Quantities Can Differ Between Calls
Compares the GET feed with a POST for France and sees two different quantities for the same SKU.
In the examples above, `SKU456` is `12` in the GET response and `8` in the POST response for `FR`. This is expected: inventory availability can vary by delivery destination. A SKU may be stocked across several fulfillment locations while only some of them serve shoppers in France, so a delivery-country request counts only the applicable locations.
{% hint style="info" %}
Both APIs return ATS, which is inventory available for new demand after inventory controls and existing commitments. Neither returns physical On Hand stock. See [Available-to-Sell (ATS)](/inventory/inventory-api/concepts/available-to-sell-ats.md).
{% endhint %}
{% hint style="warning" icon="clock-three" %}
#### USE CASE 4
{% endhint %}
## Handling Failed Requests Safely
A request fails. The integration must decide what to show shoppers and what to write to its availability store.
{% hint style="danger" %}
A failed API request must not be interpreted as zero inventory. Treat a quantity of `0` as a valid zero-ATS position only when it is returned in a successful response.
{% endhint %}
| Outcome | What it means | What to do |
| ------------------------ | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| `200` with `quantity: 0` | A valid zero-ATS position | Record zero availability |
| `400` | The request is invalid | Check the identifier, the SKU list and `deliveryCountryIso`; fix the request, do not retry as-is |
| `401` / `403` | Unauthorized or forbidden | Handle explicitly: check the token and permissions; do not write zero |
| `404` / `409` | ESW fulfillment configuration not found or in conflict | Contact ESW so the configuration can be reviewed; do not write zero |
| `500` | Internal server error | Apply the agreed retry approach for temporary failures; avoid uncontrolled retries |
In every failure case, do not write zero to your availability store.
See [Response Codes](/inventory/inventory-api/response-codes.md) for the full list.
---
# 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 by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://developer.esw.com/inventory/inventory-api/use-cases.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
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.