ChannelEngine: one-time shipment feeds

About this article

This article explains how to create shipments by uploading a feed from the orders overview.

Table of contents

Introduction

Requirements

Create a shipment feed

• Shipment fields
• Shipment line fields

Feed examples

• CSV
• JSON
• XML

Upload a shipment feed

View the upload history

View the validation report

Common issues

Introduction

Use one-time shipment feeds to create shipments for multiple orders at once, similarly to uploading a product feed.

One-time shipment feeds are useful:

• If you manage shipments manually on ChannelEngine, and want to speed up shipment creation.
• As a workaround when shipments sent through the API do not come through to ChannelEngine correctly, and you want to create them from the web interface.

Use CSV, XML, or JSON formats for one-time shipment feeds.

Access one-time shipment feeds at Orders, Orders, three-dot menu, Upload shipments.

Requirements

• The order that you wish to fulfill must exist on ChannelEngine, be acknowledged, and have the status In progress (IN_PROGRESS) or Combined (IN_COMBI).
• The one-time shipment feed format must be CSV, XML, or JSON.
• Each shipment must contain at least one valid shipment line containing a product to be shipped.
• Each order line you ship must exist in the related order.
• Each MerchantShipmentNo must be unique, in the feed and against existing shipments on ChannelEngine.

Create a shipment feed

The tables below describe which fields to include in one-time shipment feeds. Each entry in the feed represents one shipment, which is linked to an existing order through MerchantOrderNo.

Shipment fields

These fields apply to the shipment as a whole.

Shipment line fields

Every shipment needs at least one valid shipment line, which includes the product(s) to be shipped.

Feed examples

The examples below describe the same shipment: shipment SHIP123 for order ORDER456, containing one unit of product MPN-12 and two units of product MPN-13.

CSV

Below is an example of a CSV shipment feed. The columns are driven by the header row, so the order of the columns does not matter. The delimiter is a comma ( , ).

MerchantShipmentNo,MerchantOrderNo,ShipmentDate,Method,TrackTraceNo,TrackTraceUrl,ReturnMethod,ReturnTrackTraceNo,ShippedFromCountryCode,ShippedFromStockLocationId,AirWaybillNo,Shipment_ExtraDataKey1,Shipment_ExtraDataValue1,Shipment_ExtraDataKey2,Shipment_ExtraDataValue2,OrderLine1_Id,OrderLine1_MerchantProductNo,ShipmentLine1_Quantity,ShipmentLine1_ExtraDataKey1,ShipmentLine1_ExtraDataValue1,ShipmentLine1_ExtraDataKey2,ShipmentLine1_ExtraDataValue2,OrderLine2_Id,OrderLine2_MerchantProductNo,ShipmentLine2_Quantity,ShipmentLine2_ExtraDataKey1,ShipmentLine2_ExtraDataValue1,ShipmentLine2_ExtraDataKey2,ShipmentLine2_ExtraDataValue2
SHIP123,ORDER456,2024-01-10T10:30:00Z,Standard,TRACK999,https://tracking.example.com,DHL Return,RETURN12345,NL,12,057-12345678,WarehouseLocation,A-15,ShippingCarrier,DHL,8036,MPN-12,1,PackageWeight,2.5kg,PackageType,Box,8037,MPN-13,2,PackageWeight,3.5kg,PackageType,Box

In CSV, each row is one shipment. 

• OrderLine1_* - identifies the order line to ship, through OrderLine1_MerchantProductNo and, optionally, OrderLine1_Id.
• ShipmentLine1_* - the quantity you ship from that order line, and the extra data of the shipment line.
• Shipment_ExtraDataKey1 and Shipment_ExtraDataValue1 - the extra data of the shipment.

All other columns are shipment fields, as described in shipment fields. Increase the number in the column name to add more shipment lines or extra data fields: OrderLine2_*, ShipmentLine2_*, Shipment_ExtraDataKey2, and so on.

JSON

Below is an example of a JSON shipment feed. Each object in the array is one shipment, and the lines array holds its shipment lines.

[
  {
    "merchantShipmentNo": "SHIP123",
    "merchantOrderNo": "ORDER456",
    "shipmentDate": "2024-01-10T10:30:00Z",
    "method": "Standard",
    "trackTraceNo": "TRACK999",
    "trackTraceUrl": "https://tracking.example.com",
    "returnMethod": "DHL Return",
    "returnTrackTraceNo": "RETURN12345",
    "shippedFromCountryCode": "NL",
    "shippedFromStockLocationId": 12,
    "airWaybillNo": "057-12345678",
    "extraData": {
      "WarehouseLocation": "A-15",
      "ShippingCarrier": "DHL"
    },
    "lines": [
      {
        "merchantProductNo": "MPN-12",
        "orderLineId": 8036,
        "quantity": 1,
        "extraData": {
          "PackageWeight": "2.5kg",
          "PackageType": "Box"
        }
      },
      {
        "merchantProductNo": "MPN-13",
        "orderLineId": 8037,
        "quantity": 2,
        "extraData": {
          "PackageWeight": "3.5kg",
          "PackageType": "Box"
        }
      }
    ]
  }
]

XML

Below is an example of an XML shipment feed. Each Shipment element is one shipment, and the Lines element holds its shipment lines.

<?xml version="1.0" encoding="utf-8"?>
<Shipments>
  <Shipment>
    <MerchantShipmentNo>SHIP123</MerchantShipmentNo>
    <MerchantOrderNo>ORDER456</MerchantOrderNo>
    <ShipmentDate>2024-01-10T10:30:00Z</ShipmentDate>
    <Method>Standard</Method>
    <TrackTraceNo>TRACK999</TrackTraceNo>
    <TrackTraceUrl>https://tracking.example.com</TrackTraceUrl>
    <ReturnMethod>DHL Return</ReturnMethod>
    <ReturnTrackTraceNo>RETURN12345</ReturnTrackTraceNo>
    <ShippedFromCountryCode>NL</ShippedFromCountryCode>
    <ShippedFromStockLocationId>12</ShippedFromStockLocationId>
    <AirWaybillNo>057-12345678</AirWaybillNo>
    <ExtraData>
      <WarehouseLocation>A-15</WarehouseLocation>
      <ShippingCarrier>DHL</ShippingCarrier>
    </ExtraData>
    <Lines>
      <Line>
        <MerchantProductNo>MPN-12</MerchantProductNo>
        <OrderLineId>8036</OrderLineId>
        <Quantity>1</Quantity>
        <ExtraData>
          <PackageWeight>2.5kg</PackageWeight>
          <PackageType>Box</PackageType>
        </ExtraData>
      </Line>
      <Line>
        <MerchantProductNo>MPN-13</MerchantProductNo>
        <OrderLineId>8037</OrderLineId>
        <Quantity>2</Quantity>
        <ExtraData>
          <PackageWeight>3.5kg</PackageWeight>
          <PackageType>Box</PackageType>
        </ExtraData>
      </Line>
    </Lines>
  </Shipment>
</Shipments>

Upload a shipment feed

1. From the left sidebar, go to Orders, Orders.
2. In the order overview, click the three-dot menu and select Upload shipments.

3. In the Upload shipments pop-up, click Choose file and select the feed from your computer.

   

   • Expand File format information if you want to see the description of each field.
4. Click Upload.

ChannelEngine processes the feed and shows a confirmation message: File uploaded and processed successfully. The message contains a View shipment upload history link that takes you straight to the upload history.

Fully shipped orders become Shipped, partially shipped orders stay In progress.

View the upload history

The Shipment feed upload history page lists every shipment feed you have uploaded. Open it in one of two ways:

• In the Upload shipments pop-up, click View shipment upload history.
• In the confirmation message that appears after an upload, click View shipment upload history.

The page shows the following columns:

• Date - the date and time of the upload.
• Name - the name of the uploaded feed.
• Type - the format of the uploaded feed: CSV, XML, or JSON.
• Status - the status of the feed upload. Success if ChannelEngine processed the whole feed, Failed if there were validation errors.
• Report - the report link if the upload resulted in errors.

Use the search field to find a specific feed, and the pagination at the bottom of the page to browse older uploads.

View the validation report

Click Report to open the Validation report for a specific feed upload. Each row corresponds to one error:

Use the dropdown at the top of the page to filter the errors.

To receive the full report by email, click Download CSV. Correct the errors in your feed and re-upload it.

Common issues