> 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/package-management/package-management-api/use-cases.md).
# Use Cases
## Standard package creation & label retrieval
Maria's leather jacket has just been picked and packed in the warehouse. Before it can leave, ESW needs a package record and a label.
{% hint style="info" icon="box-open" %}
### 1A Package create
{% endhint %}
{% stepper %}
{% step %}
#### Create Package
Maria's jacket is boxed and the WMS has everything on hand — weight, dimensions, her address, even the customs details.
`POST /packagemanagement/v1/acmefashion/orders/ORD-100245/packages`
{% code expandable="true" %}
```json
{
"packageReference": "PKG-100245-01",
"weight": {
"weight": 1.85,
"weightUnit": "kg"
},
"shippingStatus": "Complete",
"goodsDescription": "Women's leather jacket, size M",
"serviceLevel": "EXP2",
"eswCarrierIdentifier": "DHL-EXPRESS",
"carrierReference": "RETAILER-BOOKING-REF-4471",
"originFulfillmentCentreCode": "FC-DUB01",
"shippingInfo": {
"amount": 12.50,
"currency": "EUR"
},
"dimensionInfo": {
"length": 35,
"width": 25,
"height": 10,
"measurementUnit": "cm"
},
"consigneeAddress": {
"firstName": "Maria",
"lastName": "Novak",
"address1": "12 Wenceslas Square",
"city": "Prague",
"postalCode": "11000",
"countryIso": "CZ",
"email": "maria.novak@example.com",
"telephone": "+420123456789"
},
"packageItems": [
{
"productCode": "SKU-8842-M",
"quantity": 1,
"productDescription": "Leather Jacket - Black - M",
"productCustomsDescription": "Women's leather outerwear jacket",
"countryOfOriginIso": "IT",
"weight": {
"weight": 1.8,
"weightUnit": "kg"
},
"unitPriceInfo": {
"amount": 189.99,
"currency": "EUR"
},
"hsCode": "4203.10"
}
]
}
```
{% endcode %}
Response `201`:
{% code expandable="true" %}
```json
{
"outcome": "PackageAndLabelCreated",
"status": "LabelGenerated",
"package": {
"tenantCode": "acmefashion",
"orderReference": "ORD-100245",
"packageReference": "PKG-100245-01",
"eShopPackageReference": "ESW-PKG-98213",
"eswCarrierIdentifier": "DHL-EXPRESS",
"carrierReference": "RETAILER-BOOKING-REF-4471",
"parcelCarrierReference": "JD0123456789CZ",
"weight": {
"weight": 1.85,
"weightUnit": "kg"
},
"shippingStatus": "Complete",
"serviceLevel": "EXP2",
"dangerousGoods": false,
"holdReleaseStatus": "Release",
"trackingUrl": "https://track.dhl.com/JD0123456789CZ",
"shippingDocumentation": [
{
"type": "ShippingLabel",
"format": "Pdf",
"link": "https://docs.sandbox.esw.com/labels/ESW-PKG-98213.pdf",
"documentStatus": "Created"
}
]
}
}
```
{% endcode %}
{% endstep %}
{% step %}
#### Confirm (optional)
`GET /packagemanagement/v1/acmefashion/orders/ORD-100245/packages/PKG-100245-01` → `200`, same `package` object.
{% endstep %}
{% step %}
#### Pull the label (optional)
Useful when a different system, e.g. a print server, only has the `eShopPackageReference` and needs the label independently of the create response.
`GET /packagemanagement/v1/acmefashion/documentation/ESW-PKG-98213`
```json
[
{
"type": "ShippingLabel",
"format": "Pdf",
"link": "https://docs.sandbox.esw.com/labels/ESW-PKG-98213.pdf",
"documentStatus": "Created"
}
]
```
{% hint style="info" %}
Not needed, if `shippingDocumentation` from step 1 is sufficient for your flow.
{% endhint %}
{% endstep %}
{% endstepper %}
{% hint style="info" icon="gem" %}
### 1B High-value item
{% endhint %}
Julien in Paris just bought an 18k gold pendant. Before it ships, its value needs declaring for the carrier's insurance and for customs.
`POST /packagemanagement/v1/acmefashion/orders/ORD-100247/packages`
{% code expandable="true" %}
```json
{
"packageReference": "PKG-100247-01",
"weight": {
"weight": 0.3,
"weightUnit": "kg"
},
"serviceLevel": "EXP2",
"eswCarrierIdentifier": "DHL-EXPRESS",
"goodsDescription": "18k gold pendant necklace",
"shippingInfo": {
"amount": 22.00,
"currency": "EUR"
},
"insuranceInfo": {
"amount": 2400.00,
"currency": "EUR"
},
"consigneeAddress": {
"firstName": "Julien",
"lastName": "Dubois",
"address1": "8 Rue de Rivoli",
"city": "Paris",
"postalCode": "75004",
"countryIso": "FR",
"email": "julien.dubois@example.com",
"telephone": "+33612345678"
},
"packageItems": [
{
"productCode": "SKU-9910-GOLD",
"quantity": 1,
"productDescription": "18k Gold Pendant Necklace",
"unitPriceInfo": {
"amount": 2400.00,
"currency": "EUR"
},
"hsCode": "7113.19"
}
]
}
```
{% endcode %}
Response `201`:
{% code expandable="true" %}
```json
{
"outcome": "PackageAndLabelCreated",
"status": "LabelGenerated",
"package": {
"packageReference": "PKG-100247-01",
"eShopPackageReference": "ESW-PKG-98247",
"shippingInfo": {
"amount": 22.00,
"currency": "EUR"
},
"shippingStatus": "Complete",
"shippingDocumentation": [
{
"type": "ShippingLabel",
"format": "Pdf",
"link": "https://docs.sandbox.esw.com/labels/ESW-PKG-98247.pdf",
"documentStatus": "Created"
},
{
"type": "SupportingDocumentation",
"format": "Pdf",
"link": "https://docs.sandbox.esw.com/docs/ESW-PKG-98247-customs-invoice.pdf",
"documentStatus": "Created"
}
]
}
}
```
{% endcode %}
{% hint style="info" %}
A separate documentation call is only needed if a different downstream system wants to pull it independently.
{% endhint %}
***
## Multi-package (split) shipment for a single order
Tomás in Madrid ordered a standing desk and a cable organiser (too much for one box). His order needs to become two packages, each tracked independently.
{% hint style="info" icon="boxes-stacked" %}
#### 2A Two packages created together
{% endhint %}
The desk and the cable organizer get boxed at the same pack station, minutes apart — two packages, created back to back.
#### Standing Desk
`POST /packagemanagement/v1/acmefashion/orders/ORD-100310/packages`
{% code title="Standing Desk" expandable="true" %}
```json
{
"packageReference": "PKG-100310-01",
"weight": {
"weight": 3.2,
"weightUnit": "kg"
},
"shippingStatus": "Complete",
"originFulfillmentCentreCode": "FC-DUB01",
"dimensionInfo": {
"length": 40,
"width": 30,
"height": 20,
"measurementUnit": "cm"
},
"consigneeAddress": {
"firstName": "Tomás",
"lastName": "Herrera",
"address1": "Calle Mayor 8",
"city": "Madrid",
"postalCode": "28013",
"countryIso": "ES",
"email": "tomas.herrera@example.com",
"telephone": "+34600123456"
},
"packageItems": [
{
"productCode": "SKU-2210",
"quantity": 1,
"productDescription": "Standing Desk",
"weight": {
"weight": 3.0,
"weightUnit": "kg"
}
}
]
}
```
{% endcode %}
Response `201` (key fields):
```json
{{
"outcome": "PackageAndLabelCreated",
"package": {
"packageReference": "PKG-100310-01",
"eShopPackageReference": "ESW-PKG-98301"
}
}
```
#### Desk Cable Organizer
`POST /packagemanagement/v1/acmefashion/orders/ORD-100310/package`
{% code title="Desk Cable Organizer" expandable="true" %}
```json
{
"packageReference": "PKG-100310-02",
"weight": {
"weight": 0.6,
"weightUnit": "kg"
},
"shippingStatus": "Complete",
"originFulfillmentCentreCode": "FC-DUB01",
"dimensionInfo": {
"length": 20,
"width": 15,
"height": 10,
"measurementUnit": "cm"
},
"consigneeAddress": {
"firstName": "Tomás",
"lastName": "Herrera",
"address1": "Calle Mayor 8",
"city": "Madrid",
"postalCode": "28013",
"countryIso": "ES",
"email": "tomas.herrera@example.com",
"telephone": "+34600123456"
},
"packageItems": [
{
"productCode": "SKU-2211",
"quantity": 1,
"productDescription": "Desk Cable Organiser",
"weight": {
"weight": 0.5,
"weightUnit": "kg"
}
}
]
}
```
{% endcode %}
Response `201` (key fields):
```json
{
"outcome": "PackageAndLabelCreated",
"package": {
"packageReference": "PKG-100310-02",
"eShopPackageReference": "ESW-PKG-98302"
}
}
```
Verify and pull labels in a loop
```hurl
GET /packagemanagement/v1/acmefashion/orders/ORD-100310/packages/PKG-100310-01
GET /packagemanagement/v1/acmefashion/orders/ORD-100310/packages/PKG-100310-02
GET /packagemanagement/v1/acmefashion/documentation/ESW-PKG-98301
GET /packagemanagement/v1/acmefashion/documentation/ESW-PKG-98302
```
{% hint style="info" icon="box-isometric-tape" %}
#### 2B Delayed second package (backorder / partial fulfilment)
{% endhint %}
Priya's mouse ships today. Her keyboard is on backorder and won't be boxed until it's back in stock, next week.
#### Day 1 `POST /packagemanagement/v1/acmefashion/orders/ORD-100311/packages`
{% code title="Wireless Mouse" expandable="true" %}
```json
{
"packageReference": "PKG-100311-01",
"weight": {
"weight": 0.4,
"weightUnit": "kg"
},
"shippingStatus": "Complete",
"consigneeAddress": {
"firstName": "Priya",
"lastName": "Shah",
"address1": "22 Baker Street",
"city": "London",
"postalCode": "W1U 3BW",
"countryIso": "GB",
"email": "priya.shah@example.com",
"telephone": "+447911123456"
},
"packageItems": [
{
"productCode": "SKU-4410",
"lineItemId": 1,
"quantity": 1,
"productDescription": "Wireless Mouse"
}
]
}
```
{% endcode %}
Response `201`: `package.packageReference: "PKG-100311-01"`, `package.eShopPackageReference: "ESW-PKG-98411-A"`, ships day 1 as normal.
#### Day 6, once the backordered item is back in stock — `POST /packagemanagement/v1/acmefashion/orders/ORD-100311/packages`
{% code title="Keyboard" expandable="true" %}
```json
{
"packageReference": "PKG-100311-02",
"weight": {
"weight": 0.7,
"weightUnit": "kg"
},
"shippingStatus": "Complete",
"consigneeAddress": {
"firstName": "Priya",
"lastName": "Shah",
"address1": "22 Baker Street",
"city": "London",
"postalCode": "W1U 3BW",
"countryIso": "GB",
"email": "priya.shah@example.com",
"telephone": "+447911123456"
},
"packageItems": [
{
"productCode": "SKU-4411",
"lineItemId": 2,
"quantity": 1,
"productDescription": "Mechanical Keyboard"
}
]
}
```
{% endcode %}
Response `201`: `package.packageReference: "PKG-100311-02"`, `package.eShopPackageReference: "ESW-PKG-98411-B"`, same `orderReference`, new `packageReference`.
{% hint style="info" icon="pallet-boxes" %}
#### 2C Bulk/pallet shipment (`palletIdentifier`)
{% endhint %}
A wholesale partner just ordered 40 mugs in one go — a full case, headed out on a pallet, not through a courier.
`POST /packagemanagement/v1/acmefashion/orders/ORD-100312/packages`
{% code expandable="true" %}
```json
{
"packageReference": "PKG-100312-01",
"weight": {
"weight": 18.0,
"weightUnit": "kg"
},
"shippingStatus": "Complete",
"serviceLevel": "POST",
"originFulfillmentCentreCode": "FC-DUB01",
"consigneeAddress": {
"firstName": "Warehouse",
"lastName": "Manager",
"address1": "Unit 4, Ballymount Industrial Estate",
"city": "Dublin",
"postalCode": "D12",
"countryIso": "IE",
"email": "receiving@example-wholesale.com",
"telephone": "+35318765432"
},
"packageItems": [
{
"productCode": "SKU-BULK-330",
"quantity": 40,
"productDescription": "Ceramic Mug - Case of 40"
}
]
}
```
{% endcode %}
Response `201`:
{% code expandable="true" %}
```json
{
"outcome": "PackageAndLabelCreated",
"status": "LabelGenerated",
"package": {
"packageReference": "PKG-100312-01",
"eShopPackageReference": "ESW-PKG-98312",
"palletIdentifier": "PLT-55210",
"shippingStatus": "Complete",
"shippingDocumentation": [
{
"type": "ShippingLabel",
"format": "Pdf",
"link": "https://docs.sandbox.esw.com/labels/ESW-PKG-98312.pdf",
"documentStatus": "Created"
},
{
"type": "HubHandlingLabel",
"format": "Pdf",
"link": "https://docs.sandbox.esw.com/labels/ESW-PKG-98312-hub.pdf",
"documentStatus": "Created"
}
]
}
}
```
{% endcode %}
`palletIdentifier` identifies the physical pallet assigned to a package.
ESW or the carrier assigns it during downstream logistics handling. Your integration receives it in the package response.
Use it to:
* Associate a package with its pallet during warehouse processing.
* Reconcile hub handling and pallet-level documentation.
* Trace bulk or freight shipments across downstream systems.
{% hint style="info" %}
You cannot send or update `palletIdentifier` in package requests.
{% endhint %}
***
## Dangerous goods shipment (full lifecycle)
Anna in Warsaw ordered a Class 3 flammable liquid under IATA rules. Depending on the carrier, that either ships straight through, gets held for review, or gets refused outright. This scenario walks through all four ways it can go.
{% hint style="info" icon="radiation" %}
#### 3A. DG item accepted immediately (carrier supports the classification)
{% endhint %}
Anna's aerosol ships by ground post — the carrier's fine with small quantities of Class 3 goods, so the label prints immediately.
`POST /packagemanagement/v1/acmefashion/orders/ORD-100410/packages`
{% code expandable="true" %}
```json
{
"packageReference": "PKG-100410-01",
"weight": {
"weight": 0.4,
"weightUnit": "kg"
},
"serviceLevel": "POST",
"eswCarrierIdentifier": "ANPOST-STD",
"dimensionInfo": {
"length": 15,
"width": 10,
"height": 8,
"measurementUnit": "cm"
},
"consigneeAddress": {
"firstName": "Anna",
"lastName": "Kowalski",
"address1": "ul. Długa 5",
"city": "Warsaw",
"postalCode": "00-238",
"countryIso": "PL",
"email": "anna.kowalski@example.com",
"telephone": "+48123456789"
},
"dangerousGoodsInfo": {
"dangerousGoods": true,
"dangerousGoodsClassificationCode": "3",
"dangerousGoodsUnNumber": "UN1993",
"dangerousGoodsContentId": "PERFUME-100ML"
},
"packageItems": [
{
"productCode": "SKU-5591",
"quantity": 1,
"productDescription": "Eau de Parfum 100ml",
"dangerousGoods": true,
"hsCode": "3303.00"
}
]
}
```
{% endcode %}
Response `201` — this carrier/service (ground post, Class 3 flammable liquid under the small-quantity exemption) supports the declared class, so the label generates immediately with no hold:
{
"outcome": "PackageAndLabelCreated",
"status": "LabelGenerated",
"package": {
"packageReference": "PKG-100410-01",
"eShopPackageReference": "ESW-PKG-98410",
"dangerousGoods": true,
"shippingStatus": "Complete",
"holdReleaseStatus": "Release",
"shippingDocumentation": [
{
"type": "ShippingLabel",
"format": "Pdf",
"link": "https://docs.sandbox.esw.com/labels/ESW-PKG-98410.pdf",
"documentStatus": "Created"
},
{
"type": "SupportingDocumentation",
"format": "Pdf",
"link": "https://docs.sandbox.esw.com/docs/ESW-PKG-98410-dg-declaration.pdf",
"documentStatus": "Created"
}
]
}
}
{% hint style="info" %}
DG shipments commonly generate a `SupportingDocumentation` item (the DG declaration) alongside the `ShippingLabel` — pull both from the documentation endpoint, not just the label.
{% endhint %}
{% hint style="info" icon="plane-departure" %}
#### 3B. DG package held for compliance review, then released
{% endhint %}
{% stepper %}
{% step %}
#### Create the package
A phone case with a built-in battery needs an air carrier's sign-off before it can fly.
`POST /packagemanagement/v1/acmefashion/orders/ORD-100411/packages`
{% code expandable="true" %}
```json
{
"packageReference": "PKG-100411-01",
"weight": {
"weight": 0.5,
"weightUnit": "kg"
},
"serviceLevel": "EXP2",
"eswCarrierIdentifier": "DHL-EXPRESS",
"dimensionInfo": {
"length": 15,
"width": 10,
"height": 8,
"measurementUnit": "cm"
},
"consigneeAddress": {
"firstName": "Anna",
"lastName": "Kowalski",
"address1": "ul. Długa 5",
"city": "Warsaw",
"postalCode": "00-238",
"countryIso": "PL",
"email": "anna.kowalski@example.com",
"telephone": "+48123456789"
},
"dangerousGoodsInfo": {
"dangerousGoods": true,
"dangerousGoodsClassificationCode": "9",
"dangerousGoodsUnNumber": "UN3481",
"dangerousGoodsContentId": "PHONE-CASE-WITH-BATTERY"
},
"packageItems": [
{
"productCode": "SKU-6042",
"quantity": 1,
"productDescription": "Phone Case with Power Bank",
"dangerousGoods": true,
"hsCode": "8507.60"
}
]
}
```
{% endcode %}
Response `201` — air express carrier requires manual compliance sign-off for lithium-battery-in-equipment (UN3481) before a label can be produced:
```json
{
"outcome": "PackageCreatedAndLabelOnHold",
"status": "LabelOnHold",
"package": {
"packageReference": "PKG-100411-01",
"eShopPackageReference": "ESW-PKG-98411",
"dangerousGoods": true,
"shippingStatus": "Pending",
"holdReleaseStatus": "Hold",
"shippingDocumentation": []
}
}
```
{% endstep %}
{% step %}
#### Confirm the hold
`GET .../orders/ORD-100411/packages/PKG-100411-01` → `200`, `holdReleaseStatus: "Hold"`.
{% endstep %}
{% step %}
#### Correct or supplement adjacent data
You cannot update `dangerousGoodsInfo` or `holdReleaseStatus` with `PUT`. The compliance workflow releases the hold separately. Use `PUT` to correct reviewer-flagged data or add a review reference in `metaData`:
`PUT /packagemanagement/v1/acmefashion/orders/ORD-100411/packages/PKG-100411-01`
```json
{
"weight": {
"weight": 0.52,
"weightUnit": "kg"
},
"metaData": "{\"complianceReviewId\":\"CR-4471\",\"reviewedBy\":\"compliance-team\"}"
}
```
Response `200`:
```json
{
"outcome": "PackageUpdated",
"status": "UnderReview",
"package": {
"packageReference": "PKG-100411-01",
"holdReleaseStatus": "Hold"
}
}
```
*(Label state doesn't change from this call alone.)*
{% endstep %}
{% step %}
#### Poll until released
Repeat `GET .../orders/ORD-100411/packages/PKG-100411-01` with backoff until `holdReleaseStatus: "Release"` and `shippingStatus: "Complete"`.
{% endstep %}
{% step %}
#### Pull the label
`GET .../documentation/ESW-PKG-98411` → `200`:
{% code expandable="true" %}
```json
[
{
"type": "ShippingLabel",
"format": "Pdf",
"link": "https://docs.sandbox.esw.com/labels/ESW-PKG-98411.pdf",
"documentStatus": "Created"
},
{
"type": "SupportingDocumentation",
"format": "Pdf",
"link": "https://docs.sandbox.esw.com/docs/ESW-PKG-98411-dg-declaration.pdf",
"documentStatus": "Created"
}
]
```
{% endcode %}
{% endstep %}
{% endstepper %}
{% hint style="info" %}
#### 3C DG package rejected outright (carrier/service doesn't support the class)
{% endhint %}
Someone tries to send spare lithium batteries through a pickup-point service that simply won't carry them.
`POST /packagemanagement/v1/acmefashion/orders/ORD-100412/packages`
{% code expandable="true" %}
```json
{
"packageReference": "PKG-100412-01",
"weight": {
"weight": 1.2,
"weightUnit": "kg"
},
"serviceLevel": "PUDO",
"eswCarrierIdentifier": "FEDEX-STD",
"consigneeAddress": {
"firstName": "Erik",
"lastName": "Lindqvist",
"address1": "Sveavägen 10",
"city": "Stockholm",
"postalCode": "11157",
"countryIso": "SE",
"email": "erik.lindqvist@example.com",
"telephone": "+46701234567"
},
"dangerousGoodsInfo": {
"dangerousGoods": true,
"dangerousGoodsClassificationCode": "9",
"dangerousGoodsUnNumber": "UN3480",
"dangerousGoodsContentId": "SPARE-LITHIUM-BATTERY"
},
"packageItems": [
{
"productCode": "SKU-7301",
"quantity": 2,
"productDescription": "Spare Lithium-Ion Battery Pack",
"dangerousGoods": true,
"hsCode": "8507.60"
}
]
}
```
{% endcode %}
Response `201` — pickup-point delivery (`PUDO`) doesn't accept stand-alone lithium batteries (UN3480), so label generation fails outright rather than going to hold:
{% code expandable="true" %}
```json
{
"outcome": "PackageCreatedAndLabelError",
"status": "LabelGenerationFailed",
"package": {
"packageReference": "PKG-100412-01",
"eShopPackageReference": "ESW-PKG-98412",
"dangerousGoods": true,
"shippingStatus": "Pending",
"holdReleaseStatus": "Hold",
"shippingDocumentation": [
{
"type": "ShippingLabel",
"format": "NoLabel",
"documentStatus": "Error"
}
]
}
}
```
{% endcode %}
**Recovery:** You cannot change the DG classification with `PUT`. Choose a carrier and service that accepts the declared UN number. For example, switch from `PUDO` to a dedicated ground DG service:
`PUT /packagemanagement/v1/acmefashion/orders/ORD-100412/packages/PKG-100412-01`
```json
{
"eswCarrierIdentifier": "FEDEX-GROUND-DG",
"serviceLevel": "POST",
"carrierServiceDescription": "FedEx Ground - Dangerous Goods Accepted"
}
```
Response `200`, assuming the new combination accepts the class:
{% code expandable="true" %}
```json
{
"outcome": "PackageAndLabelUpdated",
"status": "LabelGenerated",
"package": {
"packageReference": "PKG-100412-01",
"shippingStatus": "Complete",
"shippingDocumentation": [
{
"type": "ShippingLabel",
"format": "Pdf",
"link": "https://docs.sandbox.esw.com/labels/ESW-PKG-98412.pdf",
"documentStatus": "Created"
}
]
}
}
```
{% endcode %}
---
# 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/package-management/package-management-api/use-cases.md?ask=&goal=
```
`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.