> 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/returns-api/returns-api-v3.0/methods/ingestion-methods.md).

# Ingestion Methods

The following are the methods associated with the **Ingestion** API data type

## POST- Create Order <a href="#post-create-order" id="post-create-order"></a>

In scenarios where a full customer order can be ingested, such as from an Order Management System (OMS), this method can be used to create or replace the outbound order on the ESW returns platform.

The `canOverwrite` boolean field can be used to control how the action is allowed to proceed.

* When this is set to ‘TRUE’, the initial request will create the order and subsequent requests made for the same order will replace the entire order. If any items in the original request had a shipping\
  status of shipped the request will fail with a HTTP 400 Bad Request.
* When this is set to ‘FALSE’, the initial request will create the order and subsequent requests will return an HTTP 409 conflict. This will protect against accidental overwrites and boost performance.

Each item in an order can have a shipping status of ‘Unshipped’, ‘Shipped’, or ‘Cancelled’.

If a shipping status is omitted in the POST request, then a default shipping status of ‘Unshipped’ will be applied to each order item

To create or replace an order send a&#x20;

{% code expandable="true" %}

```http
POST  /{identifier}/outbound-orders
```

{% endcode %}

### Method Parameters <a href="#method-parameters" id="method-parameters"></a>

<details>

<summary><strong>Request Parameters</strong></summary>

| Field Name                                       | Data Type                                                        | Required/Optional                       | Description                                                                                                                                                                                                                                    |
| ------------------------------------------------ | ---------------------------------------------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| orderReference                                   | <ul><li>string</li><li>Max 30 characters length</li></ul>        | Required                                | The Retailer’s unique reference for the order. This is case-insensitive.                                                                                                                                                                       |
| contactInformation                               | object                                                           | Required                                |                                                                                                                                                                                                                                                |
| contactInformation.firstName                     | <ul><li>string</li><li>Max 70 characters length</li></ul>        | Required                                | First name of the recipient of the order.                                                                                                                                                                                                      |
| contactInformation.lastName                      | <ul><li>string</li><li>Max 70 characters length</li></ul>        | <p>Required</p><p> </p>                 | Last name of the recipient of the order.                                                                                                                                                                                                       |
| contactInformation.unit                          | <ul><li>string</li><li>Max 100 characters length</li></ul>       | Optional                                | Unit number of the recipient.                                                                                                                                                                                                                  |
| contactInformation.POBox                         | <ul><li>string</li><li>Max 50 characters length</li></ul>        | Optional                                | Postal Office box no of the recipient.                                                                                                                                                                                                         |
| contactInformation.address1                      | <ul><li>string</li><li>Max 150 characters length</li></ul>       | Required                                | Address Line 1 of the recipient.                                                                                                                                                                                                               |
| contactInformation.address2                      | <ul><li>string</li><li>Max 150 characters length</li></ul>       | Optional                                | Address Line 2 of the recipient.                                                                                                                                                                                                               |
| contactInformation.city                          | <ul><li>string</li><li>Max 150 characters length</li></ul>       | Optional                                | The recipient's city.                                                                                                                                                                                                                          |
| contactInformation.region                        | <ul><li>string</li><li>Max 150 characters length</li></ul>       | Optional                                | Region, province, state, or county of the recipient's address.                                                                                                                                                                                 |
| contactInformation.postalCode                    | <ul><li>string</li><li>Max 50 characters length</li></ul>        | <p>Always Optional</p><p> </p>          | Postal code or zip code of the recipient's address.                                                                                                                                                                                            |
| contactInformation.countryIso                    | <ul><li>string</li><li>ISO 3166-1 alpha-2 format</li></ul>       | Required                                | <p>The CountryISO of the recipient.</p><p>The CountryISO will be validated against the brand configuration if not found the request will fail validation</p>                                                                                   |
| contactInformation.email                         | <ul><li>string</li><li>Max 100 characters length</li></ul>       | Required                                | Email Address of the recipient.                                                                                                                                                                                                                |
| contactInformation.telephone                     | <ul><li>string</li><li>Max 50 characters length</li></ul>        | Optional                                | Phone number of the recipient.                                                                                                                                                                                                                 |
| contactInformation.cultureLanguageIso            | string                                                           | Optional                                | <p>The preferred language of the recipient.</p><p>If not supplied then the value is defaulted to “en-IE”.</p>                                                                                                                                  |
| orderitems                                       | object                                                           | Required                                |                                                                                                                                                                                                                                                |
| orderitems.productCode                           | <ul><li>string</li><li>Max 50 characters length</li></ul>        | Required                                | The retailer's unique identification code or SKU for the order item.                                                                                                                                                                           |
| orderitems.lineItemId                            | string                                                           | Optional                                | ID that identifies the line item.                                                                                                                                                                                                              |
| orderItems.quantity                              | integer                                                          | Optional                                | The number of items for the given ProductCode.                                                                                                                                                                                                 |
| orderItems.productDescripton                     | string                                                           | Required                                | Title of the product.                                                                                                                                                                                                                          |
| orderItems.productCustomsDescription             | string                                                           | Optional                                | Description of the product, including material composition for customs.                                                                                                                                                                        |
| orderItems.Composition                           | string                                                           | Optional                                | The composition of the product’s materials.                                                                                                                                                                                                    |
| orderItems.countryOfOriginIso                    | <ul><li>string</li><li>ISO 3166-1 alpha-2 format</li></ul>       | Required                                | Two-letter manufacturing country of origin of the product .                                                                                                                                                                                    |
| orderItems.hsCode                                | <ul><li>string</li><li>Max 20 characters length</li></ul>        | Optional                                | Harmonized System (HS) code of the product.                                                                                                                                                                                                    |
| orderItems.weight                                | object                                                           | Required                                |                                                                                                                                                                                                                                                |
| orderItems.weight.weightTotal                    | double                                                           | Required                                | Weight of the item.                                                                                                                                                                                                                            |
| orderItems.weight.weightUnit                     | enum                                                             | Required                                | Weight unit of the item (Kg, Lb)                                                                                                                                                                                                               |
| orderItems.unitPrice                             | object                                                           | Required                                |                                                                                                                                                                                                                                                |
| orderItems.unitPrice.amount                      | double                                                           | Required                                | Unit price of the product.                                                                                                                                                                                                                     |
| orderItems.unitPrice.currencyIso                 | <ul><li>string</li><li>Valid 3 character currency code</li></ul> | Required                                | CurrencyISO used when determining the price of the item.                                                                                                                                                                                       |
| orderItems.shippinginformation                   | object                                                           | Optional                                | Defaults to Unshipped status if section omitted.                                                                                                                                                                                               |
| orderItems.shippinginformation.shippingReference | <ul><li>string</li><li>Max 50 characters length</li></ul>        | Required if shippingStatus is ‘shipped’ | The retailer's unique reference for the package in which the item was shipped.                                                                                                                                                                 |
| orderItems.shippinginformation.barcodeReference  | <ul><li>string</li><li>Max 50 characters length</li></ul>        | Optional                                | The retailer's barcode reference for the package in which the item was shipped.                                                                                                                                                                |
| orderItems.shippinginformation.shippingStatus    | enum                                                             | Required if shipping is included        | The shipping status of the item (Unshipped, Shipped, Cancelled)                                                                                                                                                                                |
| orderItems.shippinginformation.statusDate        | datetime                                                         | Optional                                | <p>UTC date-time for the shipping status.</p><p>Current date-time is used if not explicitly supplied.</p>                                                                                                                                      |
| orderItems.productImageUrl                       | string                                                           | Optional                                | Image url of the item.                                                                                                                                                                                                                         |
| orderItems.color                                 | string                                                           | Optional                                | Item color.                                                                                                                                                                                                                                    |
| orderItems.size                                  | string                                                           | Optional                                | Item size.                                                                                                                                                                                                                                     |
| orderItems.category                              | string                                                           | Optional                                | Item categories such as Furniture, Hardware, HealthBeauty, LuggageBags, etc.                                                                                                                                                                   |
| orderItems.personalized                          | boolean                                                          | Optional                                | Flag to check if the item has been personalized?                                                                                                                                                                                               |
| orderItems.dangerousGoods                        | boolean                                                          | Optional                                | Flag to indicate whether the item is dangerous/hazardous?                                                                                                                                                                                      |
| orderItems.unitedNationsNumber                   | string                                                           | Optional                                | The standard united nations number used to represent the dangerous goods.                                                                                                                                                                      |
| orderItems.PackingInstructions                   | string                                                           | Optional                                | The instructions for packaging the order.                                                                                                                                                                                                      |
| orderItems.prohibitedForReturns                  | boolean                                                          | Optional                                | Flag to indicate if the item should be prohibited for return.                                                                                                                                                                                  |
| customFields                                     | object                                                           | Optional                                | Custom data items as string, object key value pairs                                                                                                                                                                                            |
| canOverwrite                                     | boolean                                                          | Optional                                | <p>Flag to indicate whether a subsequent PUT request can override the original data.</p><ul><li>When ‘true’, the subsequent requests replace the entire order.</li><li>When ‘false’ an error will be returned for a subsequent call.</li></ul> |

</details>

<details>

<summary><strong>Response Parameters</strong></summary>

| Field Name             | Data Type | Description                                                                              |
| ---------------------- | --------- | ---------------------------------------------------------------------------------------- |
| id                     | string    | Unique identifier for the Order. This is a combination of tenantCode and orderReference. |
| orderitems             | object    | An array of items sent in the shipment.                                                  |
| orderitems.id          | guid      | A unique identifier for the order item.                                                  |
| orderitems.productCode | string    | The Retailer's unique identification code or SKU for the order item.                     |
| orderitems.lineItemid  | string    | ID that identifies the line item.                                                        |

</details>

<details>

<summary>Response</summary>

| Response Code  | Description                                                      |
| -------------- | ---------------------------------------------------------------- |
| 201 (Created)  | The Outbound Order has been successfully created or replaced.    |
| 409 (Conflict) | The Outbound Order already exists. (If canOverwrite is ‘False’). |

</details>

{% code title="Request-Response Example" expandable="true" %}

```json
{  // sample
  "orderReference" : "338755000",
  "contactInformation": {
    "firstName": "John",
    "lastName": "Smith",
    "unit": "Unit 12",
    "poBox": "PO Box 1",
    "address1": "2107 Massachusetts Avenue",
    "address2": "Northwood",
    "city": "Washington",
    "region": "DC",
    "postalCode": "20008",
    "countryIso": "US",
    "email": "shipper@domain.com",
    "telephone": "187456998745",
    "cultureLanguageIso": "en-GB"
  },
  "orderItems": [
    {
      "productCode": "0607337",
      "lineItemId": "1",
      "quantity": 2,
      "productDescription": "Ultra Slim Watch",
      "productCustomsDescription": "Watch",
      "countryOfOriginIso": "CN",
      "hsCode": "6211490",
      "weight": {
        "weightTotal": 1.2,
        "weightUnit": "Kg"
      },
      "unitPrice": {
        "amount": 70.2,
        "currency": "USD"
      },
      "shippingInformation": {
        "shippingReference": "FBA_1636646500B",
        "barcodeReference": "5 012345 678900",
        "shippingStatus": "Unshipped",
        "statusDate": "2022-01-10T11:48:58.708Z"
      },
      "productImageUrl": "https://cdn.brand.com/img/221",
      "color": "Black",
      "size": "Small",
      "category": "Watches",
      "personalized": true,
      "dangerousGoods": true,
      "prohibitedForReturns": true
    }
  ],
  "customFields": {
    "additionalProp1": "string1",
    "additionalProp2": "string2",
    "additionalProp3": "string3"
  },
  "canOverwrite": true
}
```

{% endcode %}

## PUT- Update Order <a href="#put-update-order" id="put-update-order"></a>

This method can be used to update either customer contact information, custom fields, or order items by passing whichever property requires an update and assigning a ‘null’ value to the remaining ones. However, to update an order, the order must exist prior to calling this endpoint otherwise a ‘not found’ response will be returned.

* When supplied, contactInformation the custom fields are simply replaced in the existing order with the new information.
* If an existing item in the list cannot be identified, a new item is appended to the list. In this case, all mandatory fields for a new item must be supplied.

Items that have a shipping status of ‘Shipped’ or ‘Cancelled’ cannot be updated.

countryIso cannot be changed using this endpoint.

To update an order send a&#x20;

{% code expandable="true" %}

```http
PUT /{identifier}/outbound-orders/{orderReference}
```

{% endcode %}

### Method Parameters <a href="#method-parameters.1" id="method-parameters.1"></a>

<details>

<summary>Request Parameters</summary>

| Field Name                            | Data Type                                                        | Required/Optional                       | Description                                                                                                                                                  |
| ------------------------------------- | ---------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| orderReference                        | <ul><li>string</li><li>Max 30 characters length</li></ul>        | Required                                | The Retailer’s unique reference for the order. This is case-insensitive.                                                                                     |
| contactInformation                    | object                                                           | Required                                |                                                                                                                                                              |
| contactInformation.firstName          | <ul><li>string</li><li>Max 70 characters length</li></ul>        | Required                                | First name of the recipient of the order.                                                                                                                    |
| contactInformation.lastName           | <ul><li>string</li><li>Max 70 characters length</li></ul>        | <p>Required</p><p> </p>                 | Last name of the recipient of the order.                                                                                                                     |
| contactInformation.unit               | <ul><li>string</li><li>Max 100 characters length</li></ul>       | Optional                                | Unit number of the recipient.                                                                                                                                |
| contactInformation.POBox              | <ul><li>string</li><li>Max 50 characters length</li></ul>        | Optional                                | Postal Office box no of the recipient.                                                                                                                       |
| contactInformation.address1           | <ul><li>string</li><li>Max 150 characters length</li></ul>       | Required                                | Address Line 1 of the recipient.                                                                                                                             |
| contactInformation.address2           | <ul><li>string</li><li>Max 150 characters length</li></ul>       | Optional                                | Address Line 2 of the recipient.                                                                                                                             |
| contactInformation.city               | <ul><li>string</li><li>Max 150 characters length</li></ul>       | Optional                                | The recipient's city.                                                                                                                                        |
| contactInformation.region             | <ul><li>string</li><li>Max 150 characters length</li></ul>       | Optional                                | Region, province, state, or county of the recipient's address.                                                                                               |
| contactInformation.postalCode         | <ul><li>string</li><li>Max 50 characters length</li></ul>        | <p>Always Optional</p><p> </p>          | Postal code or zip code of the recipient's address.                                                                                                          |
| contactInformation.countryIso         | <ul><li>string</li><li>ISO 3166-1 alpha-2 format</li></ul>       | Required                                | <p>The CountryISO of the recipient.</p><p>The CountryISO will be validated against the brand configuration if not found the request will fail validation</p> |
| contactInformation.email              | <ul><li>string</li><li>Max 100 characters length</li></ul>       | Required                                | Email Address of the recipient.                                                                                                                              |
| contactInformation.telephone          | <ul><li>string</li><li>Max 50 characters length</li></ul>        | Optional                                | Phone number of the recipient.                                                                                                                               |
| contactInformation.cultureLanguageIso | string                                                           | Optional                                | <p>The preferred language of the recipient.</p><p>If not supplied then the value is defaulted to “en-IE”.</p>                                                |
| orderitems                            | object                                                           | Required                                |                                                                                                                                                              |
| productCode                           | <ul><li>string</li><li>Max 50 characters length</li></ul>        | Required                                | The retailer's unique identification code or SKU for the order item.                                                                                         |
| lineItemId                            | string                                                           | Optional                                | ID that identifies the line item.                                                                                                                            |
| quantity                              | integer                                                          | Optional                                | The number of items for the given ProductCode.                                                                                                               |
| productDescripton                     | string                                                           | Required                                | Title of the product.                                                                                                                                        |
| productCustomsDescription             | string                                                           | Optional                                | Description of the product, including material composition for customs.                                                                                      |
| countryOfOriginIso                    | <ul><li>string</li><li>ISO 3166-1 alpha-2 format</li></ul>       | Required                                | Two-letter manufacturing country of origin of the product .                                                                                                  |
| hsCode                                | <ul><li>string</li><li>Max 20 characters length</li></ul>        | Optional                                | Harmonized System (HS) code of the product.                                                                                                                  |
| weight                                | object                                                           | Required                                |                                                                                                                                                              |
| weight.weightTotal                    | double                                                           | Required                                | Weight of the item.                                                                                                                                          |
| weight.weightUnit                     | enum                                                             | Required                                | Weight unit of the item (Kg, Lb)                                                                                                                             |
| unitPrice                             | object                                                           | Required                                |                                                                                                                                                              |
| unitPrice.amount                      | double                                                           | Required                                | Unit price of the product.                                                                                                                                   |
| unitPrice.currencyIso                 | <ul><li>string</li><li>Valid 3 character currency code</li></ul> | Required                                | CurrencyISO used when determining the price of the item.                                                                                                     |
| shippinginformation                   | object                                                           | Optional                                | Defaults to Unshipped status if section omitted.                                                                                                             |
| shippinginformation.shippingReference | <ul><li>string</li><li>Max 50 characters length</li></ul>        | Required if shippingStatus is ‘shipped’ | The retailer's unique reference for the package in which the item was shipped.                                                                               |
| shippinginformation.barcodeReference  | <ul><li>string</li><li>Max 50 characters length</li></ul>        | Optional                                | The retailer's barcode reference for the package in which the item was shipped.                                                                              |
| shippinginformation.shippingStatus    | enum                                                             | Required if shipping is included        | The shipping status of the item (Unshipped, Shipped, Cancelled)                                                                                              |
| shippinginformation.statusDate        | datetime                                                         | Optional                                | <p>UTC date-time for the shipping status.</p><p>Current date-time is used if not explicitly supplied.</p>                                                    |
| productImageUrl                       | string                                                           | Optional                                | Image url of the item.                                                                                                                                       |
| color                                 | string                                                           | Optional                                | Item color.                                                                                                                                                  |
| size                                  | string                                                           | Optional                                | Item size.                                                                                                                                                   |
| category                              | string                                                           | Optional                                | Item categories such as Furniture, Hardware, HealthBeauty, LuggageBags, etc.                                                                                 |
| personalized                          | boolean                                                          | Optional                                | Flag to check if the item has been personalized?                                                                                                             |
| dangerousGoods                        | boolean                                                          | Optional                                | Flag to indicate whether the item is dangerous/hazardous?                                                                                                    |
| prohibitedForReturns                  | boolean                                                          | Optional                                | Flag to indicate if the item should be prohibited for return.                                                                                                |
| customFields                          | object                                                           | Optional                                | Custom data items as string, object key value pairs                                                                                                          |

</details>

<details>

<summary>Response</summary>

| Response Code | Description                                       |
| ------------- | ------------------------------------------------- |
| 200 (Ok)      | The outbound order has been successfully updated. |

</details>

### Request-Response Example <a href="#request-response-example.1" id="request-response-example.1"></a>

{% code title="Update Contact Information" expandable="true" %}

```json
{  // sample
    "contactInformation":{
    "firstName": "John",
    "lastName": "Smith",
    "unit": "Unit 12",
    "POBox": "PO Box 1",
    "address1": "2107 Massachusetts Ave",
    "address2": "Northwood",
    "city": "Washington",
    "Region": "DC",
    "postalCode": "20008",
    "email": "shopper@domain.com",
    "telephone": "544554",
    "cultureLanguageIso" : "en-US"
  }
}
```

{% endcode %}

{% code title="Update Items" expandable="true" %}

```json
{    //sample
  "orderItems": [
    {
      "productCode": "0607337",
      "lineItemId": "1",
      "quantity" : 2, // quantity added in request, represents multiple identical items
      "productDescription": "Ultra Slim Watch",
      "productCustomsDescription": "Ultra Slim Watch",
      "countryOfOriginIso": "CN",
      "hsCode": "6211490",
      "weight": {
        "weightTotal": 1,
        "weightUnit": "Kg"
      },
      "unitPrice": {
        "amount": 70.2,
        "currency": "USD"
      },
      "shippingInformation": {
        "shippingReference": "FBAFBA_1636646500B",
        "barcodeReference": "5 012345 678900",
        "shippingStatus": "Unshipped",
        "statusDate": "2022-01-10T11:48:58.708Z"
      },
      "productImageUrl": "https://cdn.retailer.com/images/file.png/20090821",
      "color": "Black",
      "size": "Small",
      "category": "Watches",
      "personalized": true,
      "dangerousGoods": true,
      "prohibitedForReturns": true
    }
  ]
}
```

{% endcode %}

{% code title="Update Custom Fields" expandable="true" %}

```json
{   //sample
  "customFields": {
    "additionalProp1": "string1",
    "additionalProp2": "string2",
    "additionalProp3": "string3"
  }
}
```

{% endcode %}

## POST- Submit Shipment <a href="#post-submit-shipment" id="post-submit-shipment"></a>

In the instances where the data is ingested from a shipment system rather than customer orders from an OMS, this method can be used to build up the order from one or more individual shipments. The ShippingReference and ShippingDate fields apply to all shipping items in the request. The shipment has to be ‘dispatched’ for this method to be used. If a request is successful, the shipment information is stored against a new or existing order.

To submit a shipment send&#x20;

{% code expandable="true" %}

```http
PUT /{identifier}/outbound-shipments
```

{% endcode %}

### Method Parameters <a href="#method-parameters.2" id="method-parameters.2"></a>

<details>

<summary><strong>Request Parameters</strong></summary>

| Field Name                              | Data Type                                                        | Required/Optional              | Description                                                                                                                                                  |
| --------------------------------------- | ---------------------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| orderReference                          | <ul><li>string</li><li>Max 30 characters length</li></ul>        | Required                       | The retailer’s unique reference for the order. This is case-insensitive.                                                                                     |
| shippingReference                       | <ul><li>string</li><li>Max 50 characters length</li></ul>        | Required                       | The retailer’s unique reference for this shipment.                                                                                                           |
| barcodeReference                        | <ul><li>string</li><li>Max 50 characters length</li></ul>        | Optional                       | The retailer's barcode reference for this shipment.                                                                                                          |
| shippingDate                            | <p>string</p><p>Defaults to current UTC if omitted</p>           | <p>Optional</p><p> </p>        | UTC datetime when the item was shipped                                                                                                                       |
| contactInformation                      | object                                                           | Required                       |                                                                                                                                                              |
| contactInformation.firstName            | <ul><li>string</li><li>Max 70 characters length</li></ul>        | Required                       | First name of the recipient of the order.                                                                                                                    |
| contactInformation.lastName             | <ul><li>string</li><li>Max 70 characters length</li></ul>        | <p>Required</p><p> </p>        | Last name of the recipient of the order.                                                                                                                     |
| contactInformation.unit                 | <ul><li>string</li><li>Max 100 characters length</li></ul>       | Optional                       | Unit number of the recipient.                                                                                                                                |
| contactInformation.POBox                | <ul><li>string</li><li>Max 50 characters length</li></ul>        | Optional                       | Postal Office box no of the recipient.                                                                                                                       |
| contactInformation.address1             | <ul><li>string</li><li>Max 150 characters length</li></ul>       | Required                       | Address Line 1 of the recipient.                                                                                                                             |
| contactInformation.address2             | <ul><li>string</li><li>Max 150 characters length</li></ul>       | Optional                       | Address Line 2 of the recipient.                                                                                                                             |
| contactInformation.city                 | <ul><li>string</li><li>Max 150 characters length</li></ul>       | Optional                       | The recipient's city.                                                                                                                                        |
| contactInformation.region               | <ul><li>string</li><li>Max 150 characters length</li></ul>       | Optional                       | Region, province, state, or county of the recipient's address.                                                                                               |
| contactInformation.postalCode           | <ul><li>string</li><li>Max 50 characters length</li></ul>        | <p>Always Optional</p><p> </p> | Postal code or zip code of the recipient's address.                                                                                                          |
| contactInformation.countryIso           | <ul><li>string</li><li>ISO 3166-1 alpha-2 format</li></ul>       | Required                       | <p>The CountryISO of the recipient.</p><p>The CountryISO will be validated against the brand configuration if not found the request will fail validation</p> |
| contactInformation.email                | <ul><li>string</li><li>Max 100 characters length</li></ul>       | Required                       | Email Address of the recipient.                                                                                                                              |
| contactInformation.telephone            | <ul><li>string</li><li>Max 50 characters length</li></ul>        | Optional                       | Phone number of the recipient.                                                                                                                               |
| contactInformation.cultureLanguageIso   | string                                                           | Optional                       | <p>The preferred language of the recipient.</p><p>If not supplied then the value is defaulted to “en-IE”.</p>                                                |
| shippingItems                           | object                                                           | Required                       |                                                                                                                                                              |
| shippingItems.productCode               | <ul><li>string</li><li>Max 50 characters length</li></ul>        | Required                       | The retailer's unique identification code or SKU for the order item.                                                                                         |
| shippingItems.lineItemId                | string                                                           | Optional                       | ID that identifies the line item.                                                                                                                            |
| shippingItems.quantity                  | integer                                                          | Optional                       | The number of items for the given ProductCode.                                                                                                               |
| shippingItems.productDescripton         | string                                                           | Required                       | Title of the product.                                                                                                                                        |
| shippingItems.productCustomsDescription | string                                                           | Optional                       | Description of the product, including material composition for customs.                                                                                      |
| shippingItems.Composition               | string                                                           | Optional                       | The composition of the product’s material.                                                                                                                   |
| shippingItems.countryOfOriginIso        | <ul><li>string</li><li>ISO 3166-1 alpha-2 format</li></ul>       | Required                       | Two-letter manufacturing country of origin of the product .                                                                                                  |
| shippingItems.hsCode                    | <ul><li>string</li><li>Max 20 characters length</li></ul>        | Optional                       | Harmonized System (HS) code of the product.                                                                                                                  |
| shippingItems.weight                    | object                                                           | Required                       |                                                                                                                                                              |
| shippingItems.weight.weightTotal        | double                                                           | Required                       | Weight of the item.                                                                                                                                          |
| shippingItems.weight.weightUnit         | enum                                                             | Required                       | Weight unit of the item (Kg, Lb)                                                                                                                             |
| shippingItems.unitPrice                 | object                                                           | Required                       |                                                                                                                                                              |
| shippingItems.unitPrice.amount          | double                                                           | Required                       | Unit price of the product.                                                                                                                                   |
| shippingItems.unitPrice.currencyIso     | <ul><li>string</li><li>Valid 3 character currency code</li></ul> | Required                       | CurrencyISO used when determining the price of the item.                                                                                                     |
| shippingItems.productImageUrl           | string                                                           | Optional                       | Image url of the item.                                                                                                                                       |
| shippingItems.color                     | string                                                           | Optional                       | Item color.                                                                                                                                                  |
| shippingItems.size                      | string                                                           | Optional                       | Item size.                                                                                                                                                   |
| shippingItems.category                  | string                                                           | Optional                       | Item categories such as Furniture, Hardware, HealthBeauty, LuggageBags, etc.                                                                                 |
| shippingItems.personalized              | boolean                                                          | Optional                       | Flag to check if the item has been personalized?                                                                                                             |
| shippingItems.dangerousGoods            | boolean                                                          | Optional                       | Flag to indicate whether the item is dangerous/hazardous?                                                                                                    |
| shippingItems.unitedNationsNumber       | string                                                           | Optional                       | The united nations standard number associated with the dangerous goods.                                                                                      |
| shippingItems.PackingInstructions       | string                                                           | Optional                       | The instructions for packaging the order.                                                                                                                    |
| shippingItems.prohibitedForReturns      | boolean                                                          | Optional                       | Flag to indicate if the item should be prohibited for return.                                                                                                |
| customFields                            | object                                                           | Optional                       | Custom data items as string, object key value pairs                                                                                                          |

</details>

<details>

<summary>Response</summary>

| Response Code | Description                                               |
| ------------- | --------------------------------------------------------- |
| 200 (Ok)      | The shipment information has been successfully submitted. |

</details>

{% code title="Request-Response Example" expandable="true" %}

```json
{ // sample
  "orderReference": "1636646500",
  "shippingReference": "FBB_1636646500B",
  "barcodeReference": "5 012345 678900",
  "shippingDate": "2022-01-10T11:48:58.708Z"
  "contactInformation": {
    "firstName": "John",
    "lastName": "Smith",
    "unit": "Unit 12",
    "poBox": "PO Box 1",
    "address1": "2107 Massachusetts Avenue",
    "address2": "Northwood",
    "city": "Washington",
    "region": "DC",
    "postalCode": "20008",
    "countryIso": "US",
    "email": "shipper@domain.com",
    "telephone": "187456998745",
    "cultureLanguageIso": "en-GB"
  },
  "shippingItems": [
    {
      "productCode": "0607337",
      "lineItemId": "1",
      "quantity": 2,
      "productDescription": "Ultra Slim Watch",
      "productCustomsDescription": "Watch",
      "countryOfOriginIso": "CN",
      "hsCode": "6211490",
      "weight": {
        "weightTotal": 1,
        "weightUnit": "Kg"
      },
      "unitPrice": {
        "amount": 70.2,
        "currency": "USD"
      },
      "productImageUrl": "https://cdn.brand.com/img/821",
      "color": "Black",
      "size": "Small",
      "category": "Watches",
      "personalized": true,
      "dangerousGoods": true,
      "prohibitedForReturns": true
    }
  ],
  "customFields": {
    "additionalProp1": "string1",
    "additionalProp2": "string2",
    "additionalProp3": "string3"
  },
}
```

{% 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/returns-api/returns-api-v3.0/methods/ingestion-methods.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.