> 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/integrations/package-file-integration.md).

# Package File Integration

Use the Package file to send package and item data to ESW in batches. One file can contain many packages.

If you also send catalog data by SFTP, keep the naming and sequencing rules consistent across feeds.

### File naming

Use this format:

* `Package-nnn-xxxxxxxx.xml`

Where:

* `nnn`: the ESW-provided brand code.
* `xxxxxxxx`: an 8-digit, zero-padded counter starting at `00000001`.

Example: `Package-123-00000001.xml`

### Delivery (SFTP)

* Upload files to an ESW-provided SFTP folder.
* Agree the delivery schedule with ESW (hourly, daily, etc.).
* Keep the sequence increasing for each new file you send.
* Do not re-use a file name. Send a new file after fixes.

{% hint style="info" %}
ESW provides SFTP connection details (host, username, password) during onboarding.
{% endhint %}

### File format rules

* XML must be well-formed and encoded as UTF-8.
* Use a single root node: `<Packages>`.
* Include one `<Package>` node per package.
* Element names and casing must match the agreed schema.
* Omit optional elements when you have no value (preferred over sending empty tags).

After upload, ESW processes the file and returns a success/failure notification. See [File Processing](/integrations/catalog-file-integration/file-processing.md).

### Example XML

<details>

<summary>Show example XML</summary>

{% hint style="warning" %}
Use element names exactly as shown. XML element names are case-sensitive.
{% endhint %}

```xml
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<Packages>
  <Package>
    <BrandCode>123</BrandCode>
    <WareHouse>DUB1</WareHouse>
    <OrderReference>ORDER-10001</OrderReference>
    <OriginalOrderReference>ORDER-10001</OriginalOrderReference>
    <PackageReference>PKG-00000001</PackageReference>
    <CarrierReference>TRACKING-123</CarrierReference>
    <IsBackOrder>false</IsBackOrder>

    <Consignee>
      <FirstName>Jane</FirstName>
      <LastName>Doe</LastName>
      <Email>jane.doe@example.com</Email>
      <Telephone>+3531234567</Telephone>
      <Address1>1 Main St</Address1>
      <City>Dublin</City>
      <PostalCode>D01 ABC2</PostalCode>
      <Country>IE</Country>
    </Consignee>

    <OrderType>CHECKOUT</OrderType>

    <ShippingInfo>
      <ShippingChargeValue>4.15</ShippingChargeValue>
      <ShippingChargeCurrency>EUR</ShippingChargeCurrency>
    </ShippingInfo>

    <Weight>
      <WeightTotal>1.2</WeightTotal>
      <WeightUnit>Kg</WeightUnit>
    </Weight>

    <Dimensions>
      <DimHeight>10</DimHeight>
      <DimLength>30</DimLength>
      <DimWidth>20</DimWidth>
      <DimMeasurementUnit>Cm</DimMeasurementUnit>
    </Dimensions>

    <GoodsDescription>Apparel</GoodsDescription>
    <ServiceLevel>POST</ServiceLevel>

    <PackageItems>
      <PackageItem>
        <ProductCode>SKU-001</ProductCode>
        <Quantity>1</Quantity>
        <ProductDescription>T-shirt</ProductDescription>
        <ProductCustomsDescription>100% cotton t-shirt</ProductCustomsDescription>
        <CountryOfOrigin>CN</CountryOfOrigin>
        <Weight>0.3</Weight>
        <WeightUnit>Kg</WeightUnit>
        <UnitPrice>25.00</UnitPrice>
        <UnitPriceCurrency>EUR</UnitPriceCurrency>
        <HsCode>610910</HsCode>
      </PackageItem>
    </PackageItems>

    <PackageStatus>NEW</PackageStatus>
  </Package>
</Packages>
```

</details>

### Field reference

{% hint style="info" %}
Some fields are required only for specific order flows (for example non-checkout orders). Confirm your exact requirements with ESW during onboarding.
{% endhint %}

<details>

<summary>Package</summary>

| Element                  | Type          | Required    | Notes                                                                               |
| ------------------------ | ------------- | ----------- | ----------------------------------------------------------------------------------- |
| `BrandCode`              | string (3)    | Yes         | ESW-provided identifier for the brand/retailer.                                     |
| `WareHouse`              | string (200)  | No          | Warehouse shipping location identifier.                                             |
| `OrderReference`         | string (30)   | Yes         | Unique order reference for the package.                                             |
| `OriginalOrderReference` | string (30)   | No          | Parent order reference for backorders or split shipments.                           |
| `PackageReference`       | string (50)   | Yes         | Unique package reference.                                                           |
| `CarrierReference`       | string (50)   | No          | Carrier tracking/reference number.                                                  |
| `IsBackOrder`            | boolean       | No          | Set `true` when this is not the first package for the order.                        |
| `Consignee`              | object        | Conditional | Optional for checkout; required for non-checkout orders.                            |
| `OrderType`              | string / enum | Yes         | Order flow identifier (for example `CHECKOUT`). Use the ESW-agreed values.          |
| `ShippingInfo`           | object        | Yes         | Shipping charge details.                                                            |
| `Weight`                 | object        | Yes         | Total package weight.                                                               |
| `Dimensions`             | object        | Yes         | Package dimensions.                                                                 |
| `GoodsDescription`       | string (100)  | Yes         | High-level description of goods.                                                    |
| `ServiceLevel`           | string / enum | Conditional | Optional for checkout; required for non-checkout orders. Use the ESW-agreed values. |
| `PackageItems`           | object        | Yes         | Container for one or more `PackageItem` nodes.                                      |
| `PackageStatus`          | string / enum | Yes         | Package status (for example `NEW`). Use the ESW-agreed values.                      |

</details>

<details>

<summary>Consignee</summary>

| Element      | Type         | Required | Notes                                       |
| ------------ | ------------ | -------- | ------------------------------------------- |
| `FirstName`  | string (70)  | Yes      | Recipient first name.                       |
| `LastName`   | string (70)  | Yes      | Recipient last name.                        |
| `Gender`     | string (6)   | No       | Recipient gender.                           |
| `Email`      | string (100) | Yes      | Recipient email address.                    |
| `Telephone`  | string (150) | Yes      | Recipient phone number.                     |
| `Unit`       | string (100) | No       | Apartment/unit/suite.                       |
| `Address1`   | string (150) | Yes      | Address line 1.                             |
| `Address2`   | string (150) | No       | Address line 2.                             |
| `Address3`   | string (150) | No       | Address line 3.                             |
| `City`       | string (100) | Yes      | City.                                       |
| `PostalCode` | string (50)  | Yes      | Postcode or ZIP.                            |
| `POBox`      | string (50)  | No       | PO box.                                     |
| `Region`     | string (150) | No       | State/province/region.                      |
| `Country`    | string (2)   | Yes      | ISO 3166-1 alpha-2 code (for example `JP`). |

</details>

<details>

<summary>ShippingInfo</summary>

| Element                  | Type       | Required | Notes                                  |
| ------------------------ | ---------- | -------- | -------------------------------------- |
| `ShippingChargeValue`    | decimal    | No       | Shipping amount (for example `4.15`).  |
| `ShippingChargeCurrency` | string (3) | No       | ISO 4217 currency (for example `EUR`). |

</details>

<details>

<summary>Weight</summary>

| Element       | Type          | Required | Notes                                                                 |
| ------------- | ------------- | -------- | --------------------------------------------------------------------- |
| `WeightTotal` | decimal       | Yes      | Total package weight.                                                 |
| `WeightUnit`  | string / enum | Yes      | Unit for `WeightTotal` (for example `Kg`). Use the ESW-agreed values. |

</details>

<details>

<summary>Dimensions</summary>

| Element              | Type          | Required | Notes                                                                    |
| -------------------- | ------------- | -------- | ------------------------------------------------------------------------ |
| `DimHeight`          | decimal       | No       | Package height.                                                          |
| `DimLength`          | decimal       | No       | Package length.                                                          |
| `DimWidth`           | decimal       | No       | Package width.                                                           |
| `DimensionalWeight`  | decimal       | No       | Dimensional weight if provided.                                          |
| `DimMeasurementUnit` | string / enum | No       | Unit for dimensions (for example `In`, `Cm`). Use the ESW-agreed values. |

</details>

<details>

<summary>PackageItem</summary>

| Element                     | Type          | Required    | Notes                                                                           |
| --------------------------- | ------------- | ----------- | ------------------------------------------------------------------------------- |
| `ProductCode`               | string (50)   | Yes         | Retailer SKU or product code.                                                   |
| `Quantity`                  | integer       | Yes         | Quantity for this `ProductCode` at the same `UnitPrice`.                        |
| `ProductDescription`        | string (150)  | Conditional | Optional for checkout; required for non-checkout orders.                        |
| `ProductCustomsDescription` | string (150)  | Conditional | Optional for checkout; required for non-checkout orders.                        |
| `CountryOfOrigin`           | string (2)    | Conditional | Optional for checkout; required for non-checkout orders. ISO 3166-1 alpha-2.    |
| `Weight`                    | decimal       | Yes         | Item weight.                                                                    |
| `WeightUnit`                | string / enum | Yes         | Unit for item `Weight` (for example `Kg`). Use the ESW-agreed values.           |
| `UnitPrice`                 | decimal       | Conditional | Optional for checkout; required for non-checkout orders. Price after discounts. |
| `UnitPriceCurrency`         | string (3)    | Conditional | Required when `UnitPrice` is present. ISO 4217 (for example `EUR`).             |
| `HsCode`                    | string (20)   | Conditional | Optional for checkout; required for non-checkout orders.                        |

</details>


---

# 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/integrations/package-file-integration.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.