API/FTP: Send an order

As described in our data model, an order is comprised of various fulfillments.
A fulfillment is a group of line items that will follow a common logistics flow and will generally end up being sent together.
The most common scenario is an order being created with one fulfillment containing all the line items. This fulfillment is then shipped in a single tracker. We'll describe below how to send updates to Shipup about your order information for this simple scenario.

📘
For the sake of simplicity, we've omitted many fields from the below payloads. Your typical payloads will contain much more customer and order information.

1. Yet to be shipped order

The customer has just placed an order containing several line items and your logistics system already knows that those items will all be shipped together. This means all line items of this order will belong to the same fulfillment. You haven't yet generated any shipping label for the future package: It's too early to include a tracker in the fulfillment.
In this situation, you will first send the order with one fulfillment containing all the line items when the order is placed:

// POST https://api.shipup.co/v2/orders

{
  "merchant_id": "ODR1234",
  "order_number": "YDGE56TYY",
  "email": "[email protected]",
  "first_name": "Jane",
  "last_name": "Doe",
  "fulfillments": [
    {
      "merchant_id": "ODR1234_1",
      "fulfillment_number": "YDGE56TYY_1",
      "status_code": "preparing_shipment",
      "shipping_address": {
        "address1": "12, rue de Cléry",
        "city": "Paris",
        "country": "France",
        "country_code": "FR",
        "first_name": "Jane",
        "last_name": "Doe",
        "zip": "75002"
      },
      "line_items": [
        {
          "merchant_id": "12355432",
          "title": "Amazing picture",
          "sku": "HJY333452",
          "quantity": 1,
          "thumbnail": {
            "src": "https://shipup-assets.s3-eu-west-1.amazonaws.com/logos/shipup_logos/Shipup-Logo-130.png",
            "height": 130,
            "width": 130
          }
        },
        {
          "merchant_id": "55636421",
          "title": "Painting color blue",
          "sku": "JUH78899777",
          "quantity": 3,
          "thumbnail": {
            "src": "https://shipup-assets.s3.eu-west-1.amazonaws.com/logos/shipup_logos/favicon/favicon-96x96.png",
            "height": 96,
            "width": 96
          }
        }
      ]
    }
  ]
}

// CSV file sent on the FTP
order.merchant_id;order.order_number;order.email;order.first_name;order.last_name;fulfillment.merchant_id;fulfillment.fulfillment_number;fulfillment.status_code;shipping_address.address1;shipping_address.city;shipping_address.country;shipping_address.country_code;shipping_address.first_name;shipping_address.last_name;shipping_address.zip;line_item.merchant_id;line_item.title;line_item.sku;line_item.quantity;line_item.thumbnail.src
ODR1234;YDGE56TYY;[email protected];Jane;Doe;ODR1234_1;YDGE56TYY_1;preparing_shipment;12, rue de Cléry;Paris;France;FR;Jane;Doe;75002;12355432;Amazing picture;HJY333452;1;https://shipup-assets.s3-eu-west-1.amazonaws.com/logos/shipup_logos/Shipup-Logo-130.png
ODR1234;YDGE56TYY;[email protected];Jane;Doe;ODR1234_1;YDGE56TYY_1;preparing_shipment;12, rue de Cléry;Paris;France;FR;Jane;Doe;75002;55636421;Painting color blue;JUH78899777;3;https://shipup-assets.s3.eu-west-1.amazonaws.com/logos/shipup_logos/favicon/favicon-96x96.png

Note that the fulfillments field is an array because an order can contain multiple fulfillments. Likewise, the line_items field is an array.

2. Shipped order

This is what follows in most cases: all the line items of the fulfillment are now shipped in a single tracker. This tracker has a carrier and a tracking number. It is added to the previously created fulfillment.
Note that the trackers field is an array because a fulfillment can contain multiple trackers. Also, the line_items list has now been moved from the first fulfillment to the first tracker. We'll see in the next examples that the line items of a fulfillment can be split between the fulfillment and its trackers. In this given example, all items are now shipped, and in a single tracker, so all line_items are placed in the first tracker.

// POST https://api.shipup.co/v2/orders

{
  "merchant_id": "ODR1234",
  "order_number": "YDGE56TYY",
  "email": "[email protected]",
  "first_name": "Jane",
  "last_name": "Doe",
  "fulfillments": [
    {
      "merchant_id": "ODR1234_1",
      "fulfillment_number": "YDGE56TYY_1",
      "status_code": "shipped",
      "warehouse_merchant_id": "warehouse_paris",
      "shipping_address": {
        "address1": "12, rue de Cléry",
        "city": "Paris",
        "company_title": "ACME corp",
        "country": "France",
        "country_code": "FR",
        "first_name": "Jane",
        "last_name": "Doe",
        "name": "Jane Doe",
        "zip": "75002"
      },
      "trackers": [
        {
          "carrier_code": "ups",
          "tracking_number": "1Z548V626898567913",
          "line_items": [
            {
              "merchant_id": "12355432",
              "title": "Amazing picture",
              "sku": "HJY333452",
              "quantity": 1,
              "thumbnail": {
                "src": "https://shipup-assets.s3-eu-west-1.amazonaws.com/logos/shipup_logos/Shipup-Logo-130.png",
                "height": 130,
                "width": 130
              }
            },
            {
              "merchant_id": "55636421",
              "title": "Painting color blue",
              "sku": "JUH78899777",
              "quantity": 3,
              "thumbnail": {
                "src": "https://shipup-assets.s3.eu-west-1.amazonaws.com/logos/shipup_logos/favicon/favicon-96x96.png",
                "height": 96,
                "width": 96
              }
            }
          ]
        }
      ]
    }
  ]
}

// CSV file sent on the FTP
order.merchant_id;order.order_number;order.email;order.first_name;order.last_name;fulfillment.merchant_id;fulfillment.fulfillment_number;fulfillment.status_code;shipping_address.address1;shipping_address.city;shipping_address.country;shipping_address.country_code;shipping_address.first_name;shipping_address.last_name;shipping_address.zip;line_item.merchant_id;line_item.title;line_item.sku;line_item.quantity;line_item.thumbnail.src;tracker.carrier_code;tracker.tracking_number
ODR1234;YDGE56TYY;[email protected];Jane;Doe;ODR1234_1;YDGE56TYY_1;preparing_shipment;12, rue de Cléry;Paris;France;FR;Jane;Doe;75002;12355432;Amazing picture;HJY333452;1;https://shipup-assets.s3-eu-west-1.amazonaws.com/logos/shipup_logos/Shipup-Logo-130.png;ups;1Z548V626898567913
ODR1234;YDGE56TYY;[email protected];Jane;Doe;ODR1234_1;YDGE56TYY_1;preparing_shipment;12, rue de Cléry;Paris;France;FR;Jane;Doe;75002;55636421;Painting color blue;JUH78899777;3;https://shipup-assets.s3.eu-west-1.amazonaws.com/logos/shipup_logos/favicon/favicon-96x96.png;ups;1Z548V626898567913