API Methods
The following methods are included in Customs Catalog API
POST/Upload Catalog
To send catalog information to ESW, submit a
POST
request to /api/v2/RetailerCatalog
The ESW Customs Catalog API ↗ supports the following use cases:
1. Uploading a Full Catalog
Recommended when synchronizing your complete product catalog for the first time—usually during onboarding. The file should contain all products you intend to offer.
2. Adding New Products
If you’ve already submitted your initial catalog, send only the new items you want to add. Existing catalog entries are not affected.
3. Updating Existing Products
To modify previously submitted products—for example, updating product categories or prices—send only the updated entries. If processed successfully, existing fields in ESW’s system are overwritten with the new values.
Minimum Required Parameters
The Customs Catalog API contains certain parameters, which are required at a minimum to correctly identify the items in the catalog. If you submit the API request but do not include these parameters, internal exceptions are created in the ESW system, impacting the overall catalog integration process and product availability.
| Parameter/Field Name | Type | Description |
|---|---|---|
| productCode | String (50) |
(Required) The brand's unique master identifier or SKU (Stock Keeping Unit). Example: 1231321313, ABC-1234, 2132132323
|
| name | String (150) |
(Required) The name of the product. Example (Apparel): Boys long-sleeve jersey knit pocket t-shirtExample (Cosmetics): LOVELY MASCARA
|
| description | String (100) |
(Required) Short description of the product. Example: High volume mascara that helps your lashes look fuller
|
| material | String (100) |
(Required) Description of material(s). Example: 90% cotton, 10% silkExample: Water (x%), castor oil (x%)
|
| countryOfOrigin | CountryIso |
(Required) Two-letter ISO code of the manufacturing country. Example: CN, US
|
| hsCode | String (12) |
(Required) HS code of the product (minimum 6 digits). Example: 62310100, 62.31.0100
|
| hsCodeRegion | Region |
(Required) The ESW region related to the HS code. Example: EU, US
|
| category | Category |
(Optional) ESW category ID. Example: ApparelClothingNotKnitted
|
| gender | Gender |
(Optional) The gender intended for the product. Example: Male, Female
|
| ageGroup | AgeGroup |
(Optional) The age group intended for the product. Example: Adult, Kids
|
| size | String (100) |
(Optional) The size of the product. Example: Small, Large, 32D
|
| weight | Decimal |
(Optional) The weight of the product. Example: 1.00
|
| weightUnit | WeightUnit |
(Optional) Unit for the product weight. Example: Kg, Lb
|
| url | String (200) |
(Optional) Product landing page URL. Example: https://yourstore.com/product123
|
| imageUrl | String (200) |
(Optional) URL of product image thumbnail. Example: https://yourstore.com/product123.jpg
|
| unitPrice | Decimal |
(Optional) Price of the product. Example: 2.69
|
| unitPriceCurrencyIso | CurrencyIso |
(Optional) ISO currency code for the unit price. Example: EUR
|
| dangerousGoods | Boolean |
(Optional) Whether the product is classified as dangerous goods. Accepted values: TRUE, FALSE
|
| additionalProductCode | String (50) | (Optional) An additional identifier such as manufacturer’s product code or SKU. |
| variantProductCode | String (50) | (Optional) Another version of the product’s unique identifier. |
| isRestricted | Boolean |
(Optional) Indicates if the product is restricted regardless of country. Accepted values: TRUE, FALSE
|
| MID | String (500) | (Optional) Manufacturer ID for US shipments over $800. |
| MIDAddressZip | String (500) |
(Optional) Postal code of manufacturer’s address. Required if Country of Origin is China and MID is specified. |
| AdditionalInformation | String (200) | (Optional) Any additional catalog details. |
| CategoryInformation | String (200) | (Optional) Classification data for goods or services. |
| IsSubscription | Boolean |
(Optional) Indicates if the product is part of a subscription. Accepted values: TRUE, FALSE
|
| IsCustomized | Boolean |
(Optional) Indicates if the product is customized. Accepted values: TRUE, FALSE
|
Parameter Example
[
{
"productCode": "11160296020014",
"name": "JACKET",
"description": "JACKET",
"material": "FABRIC 53% cotton, 21% polyester, 21% acrylic, 4% viscose, 1% polyester, lining 100% polyester",
"countryOfOrigin": "IT",
"hsCode": "62043290",
"hsCodeRegion": "EU",
"category": null,
"gender": null,
"ageGroup": null,
"size": null,
"weight": null,
"weightUnit": null,
"url": null,
"imageUrl": null,
"unitPrice": null,
"dangerousGoods": null,
"additionalProductCode": null,
"variantProductCode": null
},
]