> 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-api/resources/tutorials/copy-of-creating-a-package.md).

# Copy of Creating a Package

This tutorial covers every field in `PackageCreate`, how field requirements vary by order type, and how to construct a valid request for each scenario.

```http
POST /api/v4/Package
Authorization: Bearer <token>
Content-Type: application/json
```

***

### Required Fields

Every `PackageCreate` request must include these five fields regardless of order type

<details>

<summary><mark style="color:$danger;"><code>Required</code></mark></summary>

| Field              | Type   | Constraint   | Description                                                            |
| ------------------ | ------ | ------------ | ---------------------------------------------------------------------- |
| `brandCode`        | string | Max 3 chars  | ESW's three-letter brand identifier                                    |
| `orderReference`   | string | Max 50 chars | Your unique reference for the order this package belongs to            |
| `packageReference` | string | Max 50 chars | Your unique reference for this specific package                        |
| `orderType`        | enum   | See Step 2   | The type of order this package relates to                              |
| `weight`           | object | See Step 3   | Package weight — `weight` (number) and `weightUnit` (`"KG"` or `"LB"`) |

</details>

#### Identifier rules

`brandCode`, `orderReference`, and `packageReference` together form the **composite key** for a package. All three are immutable after creation — they cannot be updated via `PUT`. They are also the parameters used to retrieve, update, and delete the package.

* `packageReference` must be unique per order — two packages on the same order cannot share the same `packageReference`
* `brandCode` must match your ESW-configured brand code exactly — case-sensitive

***

### `orderType`

`orderType` determines the purpose of the package and affects which `packageItems` fields are required. Choose the value that matches how the order originated.

<details>

<summary><code>orderType</code></summary>

| Value                    | When to use                                                             | `packageItems` requirement                                               |
| ------------------------ | ----------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `"CHECKOUT"`             | Order placed through ESW's checkout — ESW has the order details         | Optional — if omitted, all order items are assumed to be in this package |
| `"NONCHECKOUT"`          | Order placed outside ESW's checkout — ESW does not have product details | Required — `packageItems` must describe every item                       |
| `"RETURN"`               | Shopper is returning goods to the retailer                              | Required — `packageItems` must describe returned items                   |
| `"OFFLINE"`              | A manual or offline order — no checkout session                         | Required — `packageItems` must describe every item                       |
| `"NONCHECKOUTECOMMERCE"` | Non-checkout order originating from an ecommerce channel                | Required — `packageItems` must describe every item                       |

</details>

***

### `weight`

`weight` is required on all package creation requests. It uses the `WeightInfo` object.

```json
"weight": {
  "weight": 1.45,
  "weightUnit": "KG"
}
```

| Field        | Type            | Required | Description                                              |
| ------------ | --------------- | -------- | -------------------------------------------------------- |
| `weight`     | number (double) | ✅        | Total weight of the package including packaging material |
| `weightUnit` | enum            | ✅        | `"KG"` (kilograms) or `"LB"` (pounds)                    |

Both integers and strings are accepted for `weightUnit` — `0` or `"KG"` for kilograms, `1` or `"LB"` for pounds. Always use the string form.

***

### `ShippingStatus`

`shippingStatus` should always be set explicitly. If omitted, `"Complete"` is assumed — see Tutorial 2 for why this matters.

```json
"shippingStatus": "Pending"
```

| Value        | Effect                                                  |
| ------------ | ------------------------------------------------------- |
| `"Complete"` | Package is ready to ship; locked from further updates   |
| `"Pending"`  | Package is being prepared; updates via PUT are accepted |

***

### Documentation Flags

Two boolean flags control whether ESW generates and returns shipping and return documentation in the `POST` response.

```json
"shippingDocumentationRequested": true,
"returnDocumentationRequested": false
```

| Field                            | Default | Description                                                                                                     |
| -------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| `shippingDocumentationRequested` | `false` | Request shipping documentation (label, customs docs, packing slip, invoice) to be returned in the response      |
| `returnDocumentationRequested`   | `false` | Request return documentation (return label) to be returned in the response — must be agreed with ESW in advance |

When `shippingDocumentationRequested: true`, the response body will include a `shippingDocumentation` array containing base64-encoded documents.&#x20;

Setting these flags to `true` increases response time — ESW must generate the documents before returning the response. If your integration retrieves labels separately (e.g. via a downstream label service), leave both as `false`.

***

### &#x20;`dimensions`

`dimensions` is optional but, once any dimension field is provided, all fields within the object must be populated. You cannot provide height without also providing length and width.

```json
"dimensions": {
  "dimHeight": "25.0",
  "dimLength": "35.0",
  "dimWidth": "15.0",
  "dimWeight": "1.45",
  "dimMeasurementUnit": "CM"
}
```

| Field                | Type   | Description                                                                                           |
| -------------------- | ------ | ----------------------------------------------------------------------------------------------------- |
| `dimHeight`          | string | Height of the packed package                                                                          |
| `dimLength`          | string | Length of the packed package (`dimLength` is labelled "Width" in the description — use it for length) |
| `dimWidth`           | string | Width of the packed package (`dimWidth` is labelled "Length" in the description — use it for width)   |
| `dimWeight`          | string | Dimensional weight of the package                                                                     |
| `dimMeasurementUnit` | enum   | `"CM"` (centimetres) or `"IN"` (inches)                                                               |

***

### &#x20;`consignee`

`consignee` is the delivery recipient. It is optional on `CHECKOUT` orders (ESW already has the shopper's address from the checkout session) but should be provided for all other order types.

Eight fields are required on the consignee object when it is provided:

{% code expandable="true" %}

```json
"consignee": {
  "firstName": "Jane",
  "lastName": "Smith",
  "address1": "350 Fifth Avenue",
  "address2": "Suite 1200",
  "city": "New York",
  "postalCode": "10118",
  "region": "NY",
  "country": "US",
  "email": "jane.smith@example.com",
  "telephone": "+12125551234",
  "name": null,
  "unit": null,
  "poBox": null,
  "gender": null
}
```

{% endcode %}

<details>

<summary>Required consignee fields</summary>

| Field        | Description                                            |
| ------------ | ------------------------------------------------------ |
| `firstName`  | Recipient first name                                   |
| `lastName`   | Recipient last name                                    |
| `address1`   | Primary address line                                   |
| `city`       | City                                                   |
| `postalCode` | Postal or ZIP code                                     |
| `country`    | ISO 3166-1 alpha-2 country code                        |
| `email`      | Recipient email address                                |
| `telephone`  | Recipient phone number (include country dialling code) |

</details>

<details>

<summary>Optional consignee fields</summary>

| Field      | Description                                                |
| ---------- | ---------------------------------------------------------- |
| `name`     | Used for ship-to-store — the store name                    |
| `address2` | Secondary address line                                     |
| `address3` | Tertiary address line                                      |
| `region`   | State, province, or county — ISO preferred where available |
| `poBox`    | PO box address                                             |
| `gender`   | Recipient gender (required by some carriers for customs)   |
| `unit`     | Unit number                                                |

</details>

***

### Carrier Fields

ESW assigns carriers in most cases. Provide carrier fields only when your warehouse or logistics system has already determined the carrier.

```json
"carrierId": 7,
"carrierReference": "DHL1234567890"
```

| Field              | Type            | Description                                                          |
| ------------------ | --------------- | -------------------------------------------------------------------- |
| `carrierId`        | integer         | ESW's numeric carrier identifier — see Tutorial 15 for the full list |
| `carrierReference` | string (max 50) | The carrier's own tracking reference for this package                |

When `carrierId` is omitted, ESW selects the carrier based on the order's destination, service level, and your brand configuration.

<details>

<summary>Common carrier IDs:</summary>

| ID   | Carrier     |
| ---- | ----------- |
| 6    | Royal Mail  |
| 7    | DHL Express |
| 9    | Aramex      |
| 11   | USPS        |
| 14   | Colissimo   |
| 15   | Yamato      |
| 20   | Canada Post |
| 1014 | UPS         |
| 1038 | FedEx       |

</details>

***

### &#x20;`serviceLevel`

`serviceLevel` specifies the shipping speed tier.

| Value             | Description                                        |
| ----------------- | -------------------------------------------------- |
| `"Standard"`      | Standard delivery — same as `POST`                 |
| `"POST"`          | Standard post — same as `Standard`                 |
| `"EXP1"`          | Deferred express                                   |
| `"EXP2"`          | Express                                            |
| `"Pudo"`          | Pick-up / drop-off point — selected retailers only |
| `"RussiaExpress"` | Not currently used                                 |

If omitted, the service level is determined by your brand and carrier configuration in ESW's system.

***

### &#x20;`distributionCentre` and `hubCode`

These fields identify where the package originates from.

```json
"distributionCentre": "USDC1",
"hubCode": "AMS"
```

| Field                | Max length | Description                                                                                                                                                                |
| -------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `distributionCentre` | 200 chars  | The warehouse or distribution centre code. Examples: `IEDUB`, `AUCOW`, `FRPAR`, `USASD`. Must be agreed with ESW — ESW creates distribution centres and provides the code. |
| `hubCode`            | 10 chars   | An ESW-configured hub code for package routing. Used by selected retailers only — ESW provides the accepted values.                                                        |

***

### Dangerous Goods

Three fields handle dangerous or hazardous materials.

```json
"dangerousGoods": true,
"dangerousGoodsClassificationCode": "4.1",
"dangerousGoodsUNNumber": "UN 0001"
```

| Field                              | Description                                                                                               |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `dangerousGoods`                   | `true` if any item in the package is classified as hazardous — as agreed with ESW's Trade Compliance team |
| `dangerousGoodsClassificationCode` | IATA/IMDG classification code for the hazardous material                                                  |
| `dangerousGoodsUNNumber`           | UN number identifying the hazardous substance                                                             |

Dangerous goods handling must be agreed with ESW's Trade Compliance team before use.

***

### `shippingInfo` and `insuranceAmount`

Both use the `Price` object — `amount` as a number (double) and `currency` as an ISO 4217 string.

```json
"shippingInfo": {
  "amount": 8.50,
  "currency": "EUR"
},
"insuranceAmount": {
  "amount": 500.00,
  "currency": "EUR"
}
```

| Field             | Description                                                                            |
| ----------------- | -------------------------------------------------------------------------------------- |
| `shippingInfo`    | The shipping cost for this package — used for customs valuation and carrier settlement |
| `insuranceAmount` | The declared insurance value of the package contents                                   |

### Other Optional Fields

<details>

<summary>Other Optional Fields</summary>

| Field                         | Type    | Max length | Description                                                                                                                                |
| ----------------------------- | ------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `parentOrderReference`        | string  | 30 chars   | Links this package to a parent order — used for back-orders and child orders                                                               |
| `isBackOrder`                 | boolean | —          | `true` if this is not the first package shipped for the order. Default: `false`                                                            |
| `goodsDescription`            | string  | 100 chars  | Free-text description of the package contents — used on customs documents. If omitted, ESW uses the description of the first order article |
| `additionalImportInformation` | string  | 200 chars  | Additional documents, certificates, or authorisations for customs                                                                          |
| `palletId`                    | string  | —          | The pallet identifier this package is consolidated onto                                                                                    |
| `additionalCarrierData`       | object  | —          | Up to five carrier-specific data fields (`additionalCarrierData1` through `5`) — must be agreed with ESW                                   |
| `metadata`                    | object  | —          | Pass-through custom data — any JSON structure                                                                                              |
| `channelType`                 | string  | —          | Sales channel identifier                                                                                                                   |

</details>

***

### Examples

{% hint style="info" icon="puzzle-piece-simple" %}

#### Example A — Checkout order, ready to ship, label requested

{% endhint %}

A single-item checkout order packed and ready for immediate dispatch with DHL Express. All details are known at time of packing.

{% tabs %}
{% tab title="Checkout order, ready to ship, label requested" %}
{% @code-walkthrough/code-walkthrough title="Checkout order, ready to ship, label requested" language="javascript" filename="POST /api/v4/Package" code="POST /api/v4/Package

{
"brandCode": "GOC",
"orderReference": "ORD-2024-78542",
"packageReference": "PKG-2024-78542-001",
"orderType": "CHECKOUT",
"shippingStatus": "Complete",
"shippingDocumentationRequested": true,
"returnDocumentationRequested": false,

"weight": {
"weight": 0.85,
"weightUnit": "KG"
},

"dimensions": {
"dimHeight": "10.0",
"dimLength": "25.0",
"dimWidth": "15.0",
"dimWeight": "0.85",
"dimMeasurementUnit": "CM"
},

"carrierId": 7,
"serviceLevel": "EXP2",
"distributionCentre": "IEDUB",
"goodsDescription": "Leather goods — wallet and belt",

"consignee": {
"firstName": "Jane",
"lastName": "Smith",
"address1": "350 Fifth Avenue",
"city": "New York",
"postalCode": "10118",
"region": "NY",
"country": "US",
"email": "<jane.smith@example.com>",
"telephone": "+12125551234"
},

"shippingInfo": {
"amount": 12.00,
"currency": "EUR"
}
}" steps="\[
{"label":"Request line and package references","description":"<code>POST /api/v4/Package</code> creates a new package record. <code>brandCode</code> scopes the request to the brand. <code>orderReference</code> links this package back to the originating order. <code>packageReference</code> is your unique identifier for this physical parcel — one order can have multiple packages.","lines":"1-6"},
{"label":"Order type and shipping status","description":"<code>orderType: CHECKOUT</code> distinguishes this from a return or exchange flow. <code>shippingStatus: Complete</code> indicates the package is ready for handover. <code>shippingDocumentationRequested: true</code> triggers generation of shipping labels and customs paperwork. <code>returnDocumentationRequested: false</code> suppresses return label generation.","lines":"7-10"},
{"label":"Weight and dimensions","description":"<code>weight</code> and <code>weightUnit</code> are the actual shipment weight used for carrier billing. <code>dimensions</code> defines the physical box size — <code>dimHeight</code>, <code>dimLength</code>, and <code>dimWidth</code> in the specified <code>dimMeasurementUnit</code>. <code>dimWeight</code> is the volumetric weight; carriers bill whichever is higher between actual and volumetric.","lines":"12-23"},
{"label":"Carrier and fulfilment routing","description":"<code>carrierId: 7</code> selects the carrier contract to use for this shipment. <code>serviceLevel: EXP2</code> selects the delivery tier within that carrier. <code>distributionCentre: IEDUB</code> is the origin warehouse the package ships from. <code>goodsDescription</code> is the plain-language contents description that appears on the shipping label and customs declaration.","lines":"25-28"},
{"label":"Consignee","description":"The <code>consignee</code> block is the delivery recipient. All address fields, <code>email</code>, and <code>telephone</code> are required for carrier label generation and customs documentation — missing fields cause label generation failures.","lines":"30-40"},
{"label":"Shipping cost","description":"<code>shippingInfo.amount</code> and <code>currency</code> record the shipping charge applied to this package — always in the retailer's home currency. This feeds into landed cost calculations and financial reconciliation.","lines":"42-45"}
]" %}
{% endtab %}
{% endtabs %}

{% code expandable="true" %}

```json
POST /api/v4/Package

{
  "brandCode": "GOC",
  "orderReference": "ORD-2024-78542",
  "packageReference": "PKG-2024-78542-001",
  "orderType": "CHECKOUT",
  "shippingStatus": "Complete",
  "shippingDocumentationRequested": true,
  "returnDocumentationRequested": false,

  "weight": {
    "weight": 0.85,
    "weightUnit": "KG"
  },

  "dimensions": {
    "dimHeight": "10.0",
    "dimLength": "25.0",
    "dimWidth": "15.0",
    "dimWeight": "0.85",
    "dimMeasurementUnit": "CM"
  },

  "carrierId": 7,
  "serviceLevel": "EXP2",
  "distributionCentre": "IEDUB",
  "goodsDescription": "Leather goods — wallet and belt",

  "consignee": {
    "firstName": "Jane",
    "lastName": "Smith",
    "address1": "350 Fifth Avenue",
    "city": "New York",
    "postalCode": "10118",
    "region": "NY",
    "country": "US",
    "email": "jane.smith@example.com",
    "telephone": "+12125551234"
  },

  "shippingInfo": {
    "amount": 12.00,
    "currency": "EUR"
  }
}
```

{% endcode %}

***

{% hint style="info" icon="puzzle-piece-simple" %}

#### Example B — Checkout order, pre-registered as Pending

{% endhint %}

A checkout order where the package is being registered before packing is complete. Weight is estimated; final weight and carrier will be confirmed via `PUT.`

{% code expandable="true" %}

```json
POST /api/v4/Package

{
  "brandCode": "GOC",
  "orderReference": "ORD-2024-78543",
  "packageReference": "PKG-2024-78543-001",
  "orderType": "CHECKOUT",
  "shippingStatus": "Pending",
  "shippingDocumentationRequested": false,

  "weight": {
    "weight": 1.00,
    "weightUnit": "KG"
  },

  "consignee": {
    "firstName": "Sophie",
    "lastName": "Nguyen",
    "address1": "42 George Street",
    "city": "Sydney",
    "postalCode": "2000",
    "region": "NSW",
    "country": "AU",
    "email": "sophie.nguyen@example.com",
    "telephone": "+61412345678"
  }
}
```

{% endcode %}

Follow-up <mark style="color:$warning;">`PUT`</mark> when packing is complete:

{% code expandable="true" %}

```json
PUT /api/v4/Package

{
  "brandCode": "GOC",
  "orderReference": "ORD-2024-78543",
  "packageReference": "PKG-2024-78543-001",
  "shippingStatus": "Complete",
  "weight": {
    "weight": 0.92,
    "weightUnit": "KG"
  },
  "carrierId": 25,
  "dimensions": {
    "dimHeight": "8.0",
    "dimLength": "22.0",
    "dimWidth": "14.0",
    "dimWeight": "0.92",
    "dimMeasurementUnit": "CM"
  }
}
```

{% endcode %}

***

{% hint style="info" icon="puzzle-piece-simple" %}

#### Example C — Non-checkout order with package items

{% endhint %}

A non-checkout B2B order. ESW does not have the product details, so `packageItems` must be provided in full.

{% code expandable="true" %}

```json
POST /api/v4/Package

{
  "brandCode": "GOC",
  "orderReference": "B2B-2024-00091",
  "packageReference": "PKG-B2B-2024-00091-001",
  "orderType": "NONCHECKOUT",
  "shippingStatus": "Complete",
  "shippingDocumentationRequested": true,

  "weight": {
    "weight": 2.30,
    "weightUnit": "KG"
  },

  "goodsDescription": "Apparel — knitwear",

  "consignee": {
    "firstName": "Marc",
    "lastName": "Dupont",
    "address1": "12 Rue du Commerce",
    "city": "Paris",
    "postalCode": "75015",
    "country": "FR",
    "email": "marc.dupont@example.com",
    "telephone": "+33612345678"
  },

  "packageItems": [
    {
      "productCode": "SKU-00789",
      "quantity": 2,
      "productDescription": "Silk Scarf — 90x90cm ivory",
      "productCustomsDescription": "100% pure silk woven scarf, hand-rolled edges",
      "countryOfOrigin": "FR",
      "hsCode": "6214.10",
      "weight": {
        "weight": 0.15,
        "weightUnit": "KG"
      },
      "unitPrice": {
        "amount": 149.00,
        "currency": "EUR"
      }
    },
    {
      "productCode": "SKU-00456",
      "quantity": 1,
      "productDescription": "Leather Belt — 90cm brown",
      "productCustomsDescription": "Full-grain leather dress belt with silver buckle",
      "countryOfOrigin": "IT",
      "hsCode": "4203.30",
      "weight": {
        "weight": 0.30,
        "weightUnit": "KG"
      },
      "unitPrice": {
        "amount": 59.95,
        "currency": "EUR"
      }
    }
  ],

  "carrierId": 14,
  "serviceLevel": "Standard",
  "distributionCentre": "FRPAR"
}
```

{% endcode %}

***

{% hint style="info" %}

#### Example D — Back-order package

{% endhint %}

The main order (wallet) shipped in a first package. This is the back-order package for the belt, which was out of stock.

{% code expandable="true" %}

```json
POST /api/v4/Package

{
  "brandCode": "GOC",
  "orderReference": "ORD-2024-78542-B",
  "packageReference": "PKG-2024-78542-002",
  "orderType": "CHECKOUT",
  "parentOrderReference": "ORD-2024-78542",
  "isBackOrder": true,
  "shippingStatus": "Pending",
  "shippingDocumentationRequested": false,

  "weight": {
    "weight": 0.50,
    "weightUnit": "KG"
  },

  "consignee": {
    "firstName": "Jane",
    "lastName": "Smith",
    "address1": "350 Fifth Avenue",
    "city": "New York",
    "postalCode": "10118",
    "region": "NY",
    "country": "US",
    "email": "jane.smith@example.com",
    "telephone": "+12125551234"
  }
}
```

{% endcode %}

***

### Common Errors

| Status                                 | Likely cause                                                                                   | Fix                                                                       |
| -------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `400` — `brandCode` has invalid length | More than 3 characters                                                                         | Use your exact 3-letter ESW brand code                                    |
| `400` — `orderReference` is required   | Field missing or empty                                                                         | Provide a non-empty `orderReference`                                      |
| `400` — `weight` is required           | `weight` object missing or `weight`/`weightUnit` absent                                        | Both `weight` and `weightUnit` are required                               |
| `400` — dimension fields incomplete    | Some but not all dimension fields provided                                                     | Provide all five dimension fields or none                                 |
| `409` — package already exists         | A package with this `brandCode`/`orderReference`/`packageReference` combination already exists | Use a unique `packageReference`, or DELETE the existing package first     |
| `404` — order not found                | `orderReference` not found in ESW's system (for CHECKOUT orders)                               | Verify the order was confirmed with ESW before creating the package       |
| `422`                                  | Request is not valid or well-formed                                                            | Check for malformed JSON, missing required fields, or invalid enum values |


---

# 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-api/resources/tutorials/copy-of-creating-a-package.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.