# Example 2 - Shipment

## Scenario <a href="#scenario" id="scenario"></a>

In our first example we created a sales order transformation file that could be used in the example of taking sales order data from a ecommerce system and sending it to a 3PL provider as a **CSV file**. Building on this, in this second example we're going to have a look at building a custom Shipment transformation file. This scenario would be for shipment data flowing back to the ecommerce system from the 3PL provider.

In this example we're going to move data from a CSV file on FTP to the Shopify fulfilment REST API.&#x20;

### Starting with the destination schema <a href="#start-with-the-basics" id="start-with-the-basics"></a>

To begin with lets take a look at the fields that **Shopify** needs to create a fulfilment against a Sales Order, the example below being taken from <https://shopify.dev/api/admin/rest/reference/shipping-and-fulfillment/fulfillment#create-2021-04>

{% tabs %}
{% tab title="Destination schema example" %}

```javascript
{
  "fulfillment": {
    "location_id": 905684977,
    "tracking_number": "123456789010",
    "tracking_company": "fed ex",
    "tracking_url": "https://www.new-fedex-tracking.com/?number=123456789010",
    "line_items": [
      {
        "id": 466157049
      },
      {
        "id": 518995019
      },
      {
        "id": 703073504
      }
    ]
  }
}
```

{% endtab %}
{% endtabs %}

### Reviewing the input data

Next lets take a look at the example CSV file that has been provided from the 3PL partner:

{% tabs %}
{% tab title="CSV input data example" %}

```
"order","shipment_date","courier","tracking_code","tracking_url"
"#GB123042","2021-07-01","DPD","DPD1234567890-AA","https://www.dpd.co.uk/apps/tracking/?reference=DPD1234567890-AA"
"#GB123043","2021-07-01","DPD","DPD1234567891-BB","https://www.dpd.co.uk/apps/tracking/?reference=DPD1234567891-BB"
"#GB123044","2021-07-01","DPD","DPD1234567892-CC","https://www.dpd.co.uk/apps/tracking/?reference=DPD1234567892-CC"
```

{% endtab %}
{% endtabs %}

In this typical CSV file that has been provided by a 3PL partner, we can see the basic fields required to keep the ecommerce system up to date with the shipment information.&#x20;

### Creating the transformation

Above, we have taken a look at the required destination format (payload out) and the input data from the 3PL (payload in). The next step is to bring this all together in our transformation file, mapping the input data to create the output data.&#x20;

The example tabs below show the data as received by **HighCohesion**, the transformation and finally the payload out that would be sent to **Shopify**.

{% tabs %}
{% tab title="Payload In" %}

```javascript
{
    "order": "#GB123042",
    "shipment_date": "2021-07-01",
    "courier": "DPD",
    "tracking_code": "DPD1234567890-EE",
    "tracking_url": "https://www.dpd.co.uk/apps/tracking/?reference=DPD1234567890-EE"
}
```

{% endtab %}

{% tab title="Transformation" %}

```javascript
{
  "fulfillment": {
    "location_id": {
      "*static_value*": 12345678900
    },
    "tracking_number": {
      "*ppk*": "tracking_code"
    },
    "tracking_company": {
      "*ppk*": "courier"
    },
    "tracking_url": {
      "*ppk*": "tracking_url"
    }
  }
}
```

{% endtab %}

{% tab title="Payload Out" %}

```javascript
{
  "fulfillment": {
    "location_id": 12345678900,
    "tracking_number": "DPD1234567890-EE",
    "tracking_company": "DPD",
    "tracking_url": "https://www.dpd.co.uk/apps/tracking/?reference=DPD1234567890-EE"
  }
}
```

{% endtab %}
{% endtabs %}

The transformation file ends up being quite simple, just four fields are required to ship the sales order in Shopify. Three of these fields are mapped using the `*ppk*` option, meaning that the transformation logic will use a value from the payload in. The fourth value `location_id` is populated using a `*static_value*` which in the example above enters the value 12345678900 in to the payload out.&#x20;

{% hint style="info" %}
**No Products?**

In the example above there are no line items covered in the transformation file. This is due (in this example) to the 3PL file not containing the line level detail. In the **HighCohesion** system, if there are no line items, then all lines will be fulfilled automatically.&#x20;
{% endhint %}

### Example with line items

Building on the example above, some 3PL partners offer good line level detail which can be mapped over to Shopify to create partial or split shipments. In the example below we look at how the source information has changed and how the transformation file is changed to handle it:

{% tabs %}
{% tab title="CSV input data with line items example" %}

```
"order","sku","qty","shipment_date","courier","tracking_code","tracking_url"
"#GB123042","ABC001",3,"2021-07-01","DPD","DPD1234567890-AA","https://www.dpd.co.uk/apps/tracking/?reference=DPD1234567890-AA"
"#GB123042","CEG032",4"2021-07-01","DPD","DPD1234567890-AA","https://www.dpd.co.uk/apps/tracking/?reference=DPD1234567890-AA"
"#GB123042","AGJF22",1"2021-07-01","DPD","DPD1234567890-AA","https://www.dpd.co.uk/apps/tracking/?reference=DPD1234567890-AA"
"#GB123043","BBC901",1"2021-07-01","DPD","DPD1234567891-BB","https://www.dpd.co.uk/apps/tracking/?reference=DPD1234567891-BB"
"#GB123043","BBC902",1"2021-07-01","DPD","DPD1234567891-BB","https://www.dpd.co.uk/apps/tracking/?reference=DPD1234567891-BB"
```

{% endtab %}
{% endtabs %}

The lines of the CSV will be grouped together by the common piece of data, in this case the order column that contains the order number will be used to group the data.&#x20;

{% tabs %}
{% tab title="Payload In" %}

```javascript
{
    "order": "#GB123042",
    "sku": "ABC001",
    "qty": 3,
    "shipment_date": "2021-07-01",
    "courier": "DPD",
    "tracking_code": "DPD1234567890-EE",
    "tracking_url": "https://www.dpd.co.uk/apps/tracking/?reference=DPD1234567890-EE"
    "line_items": [
        {
            "order": "#GB123042",
            "sku": "ABC001",
            "qty": 3,
            "shipment_date": "2021-07-01",
            "courier": "DPD",
            "tracking_code": "DPD1234567890-EE",
            "tracking_url": "https://www.dpd.co.uk/apps/tracking/?reference=DPD1234567890-EE"
        },
        {
            "order": "#GB123042",
            "sku": "CEG032",
            "qty": 4,
            "shipment_date": "2021-07-01",
            "courier": "DPD",
            "tracking_code": "DPD1234567890-EE",
            "tracking_url": "https://www.dpd.co.uk/apps/tracking/?reference=DPD1234567890-EE"
        },
        {
            "order": "#GB123042",
            "sku": "AGJF22",
            "qty": 1,
            "shipment_date": "2021-07-01",
            "courier": "DPD",
            "tracking_code": "DPD1234567890-EE",
            "tracking_url": "https://www.dpd.co.uk/apps/tracking/?reference=DPD1234567890-EE"
        }
    ]
}
```

{% endtab %}

{% tab title="Transformation" %}

```javascript
{
    "fulfillment": {
        "location_id": {
            "*static_value*": 12345678900
        },
        "tracking_number": {
            "*ppk*": "tracking_code"
        },
        "tracking_company": {
            "*ppk*": "courier"
        },
        "tracking_url": {
            "*ppk*": "tracking_url"
        },
        "line_items": {
            "*list*": "line_items",
            "*list_fields*":
            {
                "sku": {
                    "*ppk*": "sku"
                },
                "quantity": {
                    "*ppk*": "qty"
                }
            }
        }
    }
}
```

{% endtab %}

{% tab title="Payload Out" %}

```javascript
{
  "fulfillment": {
    "location_id": 12345678900,
    "tracking_number": "DPD1234567890-EE",
    "tracking_company": "DPD",
    "tracking_url": "https://www.dpd.co.uk/apps/tracking/?reference=DPD1234567890-EE"
    "line_items": [
      {
        "sku": "ABC001",
        "quantity": 3
      },
      {
        "sku": "CEG032",
        "quantity": 4
      },
      {
        "sku": "AGJF22",
        "quantity": 1
      },
    ]
  }
}
```

{% endtab %}
{% endtabs %}

The transformation above adds in a `*list*` and `*list_fields*` block in order to create the array of line items that is sent to Shopify.

{% hint style="info" %}
**SKU vs ID**\
In the example above we use the SKU code in the line items as that is the data that is available from the 3PL partner shipment file. The HighCohesion system will automatically match SKU code to the line item ID in **Shopify** for fulfilment to work correctly.&#x20;
{% endhint %}

{% hint style="info" %}
For a tutorial example for [FTP to Shopify integration with CSV files](/integration-tutorials/shopify-with-ftp/shopify-x-ftp-part-2.md), check [this link](/integration-tutorials/shopify-with-ftp/shopify-x-ftp-part-2.md).
{% endhint %}


---

# Agent Instructions: 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:

```
GET https://docs.highcohesion.com/creating-streams/transformations/writing-a-transformation/example-2.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.