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

# Catalog File Integration

Use the Catalog file to send your product master data to ESW. ESW uses this data for duties/taxes calculations and customs validation.

You can upload either an **Excel `.xlsx`** file or a **CSV `.csv`** file. Deliver files to an ESW-provided **SFTP** location.

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref">Link</th><th data-hidden data-card-cover data-type="image">Cover image</th><th data-hidden data-card-cover-dark data-type="image">Cover image (dark)</th></tr></thead><tbody><tr><td><strong>File Processing</strong><br>What to expect after upload, plus sample templates.</td><td><a href="/spaces/bB3UcHnWX3RLHHoolsLd/pages/7ea0dc635c01fd18bf934c6efe780f45ffbed488">/spaces/bB3UcHnWX3RLHHoolsLd/pages/7ea0dc635c01fd18bf934c6efe780f45ffbed488</a></td><td><a href="/files/gMYsvBEHgaaDHKZgKM4r">/files/gMYsvBEHgaaDHKZgKM4r</a></td><td><a href="/files/kjbJbJR7abG5u3N5s4SG">/files/kjbJbJR7abG5u3N5s4SG</a></td></tr><tr><td><strong>Sample Customs Catalog Template</strong><br>Download a starter file and <code>enum</code> values</td><td><a href="/spaces/bB3UcHnWX3RLHHoolsLd/pages/5XnBNID38K8vApYWe0ax">/spaces/bB3UcHnWX3RLHHoolsLd/pages/5XnBNID38K8vApYWe0ax</a></td><td><a href="/files/XCzeUsZZ5xMCqiOK8gzc">/files/XCzeUsZZ5xMCqiOK8gzc</a></td><td><a href="/files/3MBubEJJZmNSZKxvVECM">/files/3MBubEJJZmNSZKxvVECM</a></td></tr></tbody></table>

### File naming

Use this format:

* `Catalog-nnn-xxxxxxxx.xlsx`
* `Catalog-nnn-xxxxxxxx.csv`

Where:

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

Example: `Catalog-ABC-00000001.xlsx`

### Generation and delivery

* Agree the delivery schedule with ESW (daily, weekly, etc.).
* Include records for **one brand/retailer** per file.
* Keep the sequence increasing for each new file you send.

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

### Upload modes

ESW can process both full loads and delta uploads. Agree the approach with ESW.

* **Full catalog**: recommended for first upload and for major refreshes.
* **New products only**: include only SKUs not yet in ESW.
* **Updates to existing products**: include only SKUs you want to change.
  * On successful processing, populated fields overwrite previously stored values.

### File format rules

{% tabs %}
{% tab title="Excel (.xlsx)" %}

* Use **one worksheet** only.
* Put **one product per row**.
* Row 1 must be the **header row**.
* Use header names exactly as defined in [Field reference](#field-reference).
* Do not include HTML tags or markup in any field.
  {% endtab %}

{% tab title="CSV (.csv)" %}

* Choose a delimiter: comma `,`, semicolon `;`, or pipe `|`. Agree this with ESW.
* Use the same delimiter for the header and all data rows.
* Quote fields when they contain the delimiter (standard CSV rules).
* Put **one product per row**.
* Do not include HTML tags or markup in any field.
* Avoid trailing empty records at the end of the file.
  {% endtab %}
  {% endtabs %}

### Data rules

* Use **English** values only.
* Use one row to represent one product.
* Use stable identifiers. `productCode` is the primary key.
* If you model variants in the file, add differentiators (for example `size`) and use `variantProductCode` where applicable.

### Field reference

<table><thead><tr><th width="177">Field</th><th width="134">Type</th><th>Description</th><th>Notes</th></tr></thead><tbody><tr><td><code>productCode</code></td><td>String (50)</td><td><mark style="color:$danger;"><code>Required</code></mark> Brand unique master identifier or SKU. Examples: <code>1231321313</code>, <code>ABC-1234</code>, <code>2132132323 1</code></td><td>Key identifier. Use the product SKU where possible. Keep it searchable and consistent across the retailer site, checkout, and shipping.</td></tr><tr><td><code>name</code></td><td>String (150)</td><td><mark style="color:$danger;"><code>Required</code></mark> Product name. Examples: <code>Cubania Shirt</code>, <code>10" High-Rise Skinny Jeans in Indigo Dye Wash</code>, <code>LOVELY MASCARA</code></td><td>Match the product landing page title. For variants, include a distinguishing value such as color or size.</td></tr><tr><td><code>description</code></td><td>String (100)</td><td><mark style="color:$danger;"><code>Required</code></mark> Short product description. Examples: <code>women’s trousers (woven)</code>, <code>A soft, lightweight, and breathable Cubania shirt</code>, <code>high glow lipstick</code></td><td>Use a concise customs-ready description. This field is used for customs clearance.</td></tr><tr><td><code>material</code></td><td>String (100)</td><td><mark style="color:$danger;"><code>Required</code></mark> Material composition of the product. Examples: <code>90% cotton, 10% silk</code>, <code>Premium 95% cotton/3% poly/2% elastane ISKO™ denim</code>, <code>Aqua (Water), Paraffin, Glyceryl Stearate</code></td><td>List the primary material first. You can add up to two secondary materials. This field is used for customs clearance.</td></tr><tr><td><code>countryOfOrigin</code></td><td>CountryIso</td><td><mark style="color:$danger;"><code>Required</code></mark> Two-letter ISO code for the country where the product is manufactured. Examples: <code>CN</code>, <code>US</code></td><td></td></tr><tr><td><code>hsCode</code></td><td>String (12)</td><td><mark style="color:$danger;"><code>Required</code></mark> Brand HS code for the product. Use 8 to 12 digits. Example: <code>62310100</code></td><td>Keep HS code length consistent across products in the same file.</td></tr><tr><td><code>hsCodeRegion</code></td><td>Region</td><td><mark style="color:$danger;"><code>Required</code></mark> ESW region for the related <code>hsCode</code>. Examples: <code>EU</code>, <code>US</code></td><td></td></tr><tr><td><code>category</code></td><td>Category</td><td><mark style="color:$warning;"><code>Optional</code></mark> ESW category ID for the product. Example: <code>ApparelClothingNotKnitted</code></td><td>Recommended when you know the best category match.</td></tr><tr><td><code>gender</code></td><td>Gender</td><td><mark style="color:$warning;"><code>Optional</code></mark> Gender value for the product. Examples: <code>Female</code>, <code>Male</code></td><td>Use for a single product with multiple variants.</td></tr><tr><td><code>ageGroup</code></td><td>AgeGroup</td><td><mark style="color:$warning;"><code>Optional</code></mark> Age group for the product. Examples: <code>Adult</code>, <code>Kids</code></td><td>Use for a single product with multiple variants.</td></tr><tr><td><code>size</code></td><td>String (100)</td><td><mark style="color:$warning;"><code>Optional</code></mark> Product size. Examples: <code>Small</code>, <code>Large</code>, <code>32D</code>, <code>XXL</code></td><td>Use for a single product with multiple variants.</td></tr><tr><td><code>weight</code></td><td>Decimal</td><td><mark style="color:$warning;"><code>Optional</code></mark> Product weight in the related <code>weightUnit</code>. Example: <code>1.00</code></td><td><p>Use the product weight without packaging.</p><div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><h4>Conditional</h4><p>If <code>weightUnit</code> is present, <code>weight</code> is required.</p></div></td></tr><tr><td><code>weightUnit</code></td><td>WeightUnit</td><td><mark style="color:$warning;"><code>Optional</code></mark> Unit for <code>weight</code>. Examples: <code>Kg</code>, <code>Lb</code></td><td><div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><h4>Conditional</h4><p>If <code>weight</code> is present, <code>weightUnit</code> is required.</p></div></td></tr><tr><td><code>url</code></td><td>String (200)</td><td><mark style="color:$warning;"><code>Optional</code></mark> Product landing page URL.</td><td><p>Use a verified domain. Start with <code>http://</code> or <code>https://</code>.</p><div data-gb-custom-block data-tag="hint" data-style="danger" class="hint hint-danger"><h4>Required for specific destinations</h4><p>This field is required when shipping to Russia or Japan.</p></div></td></tr><tr><td><code>imageUrl</code></td><td>String (200)</td><td><mark style="color:$warning;"><code>Optional</code></mark> URL for the product’s main image thumbnail.</td><td>Link to the main product image thumbnail. Start with <code>http://</code> or <code>https://</code>.</td></tr><tr><td><code>unitPrice</code></td><td>Decimal</td><td><mark style="color:$warning;"><code>Optional</code></mark> Product price. Example: <code>2.69</code></td><td><p>Submit the accurate selling price, not an approximate value.</p><div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><h4>Conditional</h4><p>If <code>unitPriceCurrencyIso</code> is present, <code>unitPrice</code> is required.</p></div></td></tr><tr><td><code>unitPriceCurrencyIso</code></td><td>CurrencyIso</td><td><mark style="color:$warning;"><code>Optional</code></mark> ISO currency for <code>unitPrice</code>. Example: <code>EUR</code></td><td><p>Use a valid ISO currency code.</p><div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><h4>Conditional</h4><p>If <code>unitPrice</code> is present, <code>unitPriceCurrencyIso</code> is required.</p></div></td></tr><tr><td><code>dangerousGoods</code></td><td>Boolean</td><td><mark style="color:$warning;"><code>Optional</code></mark> Indicates whether the product is classified as dangerous goods or hazardous material. Accepted values: <code>TRUE</code>, <code>FALSE</code></td><td>Items that can cause damage, harm, or injury are not allowed.</td></tr><tr><td><code>additionalProductCode</code></td><td>String (50)</td><td><mark style="color:$warning;"><code>Optional</code></mark> Additional product identifier, such as a manufacturer SKU.</td><td>Use when you need a secondary searchable identifier. Keep it consistent across checkout and shipping.</td></tr><tr><td><code>variantProductCode</code></td><td>String (50)</td><td><mark style="color:$warning;"><code>Optional</code></mark> Variant-level version of the brand master identifier or SKU.</td><td>Use when product variants need their own identifier. Keep it consistent across checkout and shipping.</td></tr><tr><td><code>isRestricted</code></td><td>Boolean</td><td><mark style="color:$warning;"><code>Optional</code></mark> Identifies whether the product is restricted, independent of destination or other attributes. Accepted values: <code>TRUE</code>, <code>FALSE</code></td><td></td></tr><tr><td><code>MID</code></td><td>String (500)</td><td><mark style="color:$warning;"><code>Optional</code></mark> Manufacturer or shipper identification code.</td><td><div data-gb-custom-block data-tag="hint" data-style="danger" class="hint hint-danger"><h4>Conditional</h4><p>This field is required for shipments to or from the US when the order value is <code>$800</code> or more.</p></div></td></tr><tr><td><code>MIDAddressZip</code></td><td>String (500)</td><td><mark style="color:$warning;"><code>Optional</code></mark> Merchant registered address ZIP or postal code.</td><td><div data-gb-custom-block data-tag="hint" data-style="danger" class="hint hint-danger"><h4>Conditional</h4><p>This field is required when <code>MID</code> is present and <code>countryOfOrigin</code> is <code>CN</code> or <code>VN</code>. Full MID address details are mandatory when <code>countryOfOrigin</code> is <code>VN</code>.</p></div></td></tr><tr><td><code>AdditionalInformation</code></td><td>String (200)</td><td><mark style="color:$warning;"><code>Optional</code></mark> Extra catalog details.</td><td></td></tr><tr><td><code>CategoryInformation</code></td><td>String (200)</td><td><mark style="color:$warning;"><code>Optional</code></mark> Additional data that categorizes the retailer’s goods or services.</td><td></td></tr><tr><td><code>IsSubscription</code></td><td>Boolean</td><td><mark style="color:$warning;"><code>Optional</code></mark> Indicates whether the product can be bought as part of a subscription. Accepted values: <code>TRUE</code>, <code>FALSE</code></td><td></td></tr><tr><td><code>IsCustomized</code></td><td>Boolean</td><td><mark style="color:$warning;"><code>Optional</code></mark> Indicates whether the product is customized. Accepted values: <code>TRUE</code>, <code>FALSE</code></td><td></td></tr><tr><td><code>eccn</code></td><td>String (5)</td><td><mark style="color:$warning;"><code>Optional</code></mark> Export Control Classification Number for consumer electronics.</td><td><div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><h4>Conditional</h4><p><code>eccn</code> is required in several cases, including export or re-export flows, shipments to certain countries, dual-use items, and sensitive technologies.</p></div></td></tr><tr><td><code>ean</code></td><td>String (13)</td><td><mark style="color:$warning;"><code>Optional</code></mark> Product identifier used for catalog matching and downstream system reference. This is not a mandatory customs attribute.</td><td><p>Used for product identification only.</p><div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><h4>If supplied</h4><ul><li>EAN must be 13 numeric digits.</li><li>Only one of <code>EAN</code> or <code>UPC</code> is required per product.</li><li>If both are provided, ESW prioritizes <code>EAN</code>.</li><li>If neither is supplied, customs processing can still proceed if all other mandatory catalog fields are present.</li></ul></div></td></tr><tr><td><code>upc</code></td><td>String (12)</td><td><mark style="color:$warning;"><code>Optional</code></mark> Product identifier used for catalog matching and downstream system reference. This is not a mandatory customs attribute.</td><td><p>Used for product identification only.</p><div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><h4>If supplied</h4><ul><li>UPC must be 12 numeric digits.</li><li>Only one of <code>EAN</code> or <code>UPC</code> is required per product.</li><li>If both are provided, ESW prioritizes <code>EAN</code>.</li><li>If neither is supplied, customs processing can still proceed if all other mandatory catalog fields are present.</li></ul></div></td></tr></tbody></table>


---

# 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/catalog-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.