Status page
Guides

API/FTP: Send an order - exhaustive scenario

Suggest Edits

After having seen basic and advanced situations for adding order via API, we will now focus on a very exhaustive scenario. Even though a regular order will generally go through a more basic set of states, this hypothetical scenario should cover the majority of situations that can occur during the lifetime of an order.

The 5 successive states for this order are:

  1. Order without fulfillments
  2. Order with one fulfillment not yet shipped and one line item not yet fulfilled
  3. Order with one fulfillment partially shipped and one line item fulfilled into two fulfillments
  4. Order with two fulfillments shipped and the last fulfillment partially shipped in different trackers
  5. Order with three fulfillments shipped

1. Order without fulfillments

The order has 3 line items and at this step, we do not know yet how we will split them into several fulfillments:

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

{
  "merchant_id": "COMPLEX1234",
  "order_number": "GGFFTE342",
  "email": "[email protected]",
  "first_name": "Jane",
  "last_name": "Doe",
  "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
    },
    {
      "merchant_id": "55636421",
      "title": "Painting color blue",
      "sku": "JUH78899777",
      "quantity": 3
    },
    {
      "merchant_id": "6634778822",
      "title": "Blue pen",
      "sku": "PEN3352227",
      "quantity": 1000
    }
  ]
}

order.merchant_id;order.order_number;order.email;order.first_name;order.last_name;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
ODR1234;YDGE56TYY;[email protected];Jane;Doe;12, rue de Cléry;Paris;France;FR;Jane;Doe;75002;12355432;Amazing picture;HJY333452;1
ODR1234;YDGE56TYY;[email protected];Jane;Doe;12, rue de Cléry;Paris;France;FR;Jane;Doe;75002;55636421;Painting color blue;JUH78899777;3
ODR1234;YDGE56TYY;[email protected];Jane;Doe;12, rue de Cléry;Paris;France;FR;Jane;Doe;75002;6634778822;Blue pen;PEN 3352227;1000

2. Order with one fulfillment not yet shipped and one line item not yet fulfilled

At this step, the first two line items are fulfilled in the same fulfillment but we don't know yet whether we will split the last line item into several fulfillments or not. 

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

{
  "merchant_id": "COMPLEX1234",
  "order_number": "GGFFTE342",
  "email": "[email protected]",
  "first_name": "Jane",
  "last_name": "Doe",
  "fulfillments": [
    {
      "merchant_id": "COMPLEX1234_1",
      "fulfillment_number": "YDGE56TYY_1",
      "status_code": "preparing_shipment",
      "warehouse_merchant_id": "warehouse_paris",
      "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
        },
        {
          "merchant_id": "55636421",
          "title": "Painting color blue",
          "sku": "JUH78899777",
          "quantity": 3
        }
      ]
    }
  ],
  "line_items": [
    {
      "merchant_id": "6634778822",
      "title": "Blue pen",
      "sku": "PEN3352227",
      "quantity": 1000
    }
  ]
}

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
COMPLEX1234;GGFFTE342;[email protected];Jane;Doe;COMPLEX1234_1;YDGE56TYY_1;preparing_shipment;12, rue de Cléry;Paris;France;FR;Jane;Doe;75002;12355432;Amazing picture;HJY333452;1
COMPLEX1234;GGFFTE342;[email protected];Jane;Doe;COMPLEX1234_1;YDGE56TYY_1;preparing_shipment;12, rue de Cléry;Paris;France;FR;Jane;Doe;75002;55636421;Painting color blue;JUH78899777;3
COMPLEX1234;GGFFTE342;[email protected];Jane;Doe;;;;12, rue de Cléry;Paris;France;FR;Jane;Doe;75002;6634778822;Blue pen;PEN 3352227;1000

As you can see, the first two line items have moved from the line_items field of the order to the line_items field of the first fulfillment. The remaining line item is still in the line_items field of the order.

3. Order with one fulfillment partially shipped and one line item fulfilled into two fulfillments

At this step, 2 new updates occurred on the order:

  • Only a part of the first fulfillment's line items has been shipped.
  • The last line item that was in quantity 1000 has been split into two fulfillments, as we only have 750 in stock. The remaining 250 need to be manufactured. A new line item of quantity 250 is created and we update the original line item quantity to 750.
// POST https://api.shipup.co/v2/orders

{
  "merchant_id": "COMPLEX1234",
  "order_number": "GGFFTE342",
  "email": "[email protected]",
  "first_name": "Jane",
  "last_name": "Doe",
  "fulfillments": [
    {
      "merchant_id": "COMPLEX1234_1",
      "fulfillment_number": "YDGE56TYY_1",
      "status_code": "partially_shipped",
      "warehouse_merchant_id": "warehouse_paris",
      "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": "55636421",
          "title": "Painting color blue",
          "sku": "JUH78899777",
          "quantity": 3
        }
      ],
      "trackers": [
        {
          "carrier_code": "ups",
          "tracking_number": "1Z548V626898567913",
          "line_items": [
            {
              "merchant_id": "12355432",
              "title": "Amazing picture",
              "sku": "HJY333452",
              "quantity": 1
            }
          ]
        }
      ]
    },
    {
      "merchant_id": "COMPLEX1234_2",
      "fulfillment_number": "YDGE56TYY_2",
      "status_code": "preparing_shipment",
      "warehouse_merchant_id": "warehouse_paris",
      "shipping_address": {
        "address1": "12, rue de Clery",
        "city": "Paris",
        "country": "France",
        "country_code": "FR",
        "first_name": "Jane",
        "last_name": "Doe",
        "zip": "75002"
      },
      "line_items": [
        {
          "merchant_id": "6634778822",
          "title": "Blue pen",
          "sku": "PEN3352227",
          "quantity": 750
        }
      ]
    },
    {
      "merchant_id": "COMPLEX1234_3",
      "fulfillment_number": "YDGE56TYY_3",
      "warehouse_merchant_id": "warehouse_paris",
      "status_code": "in_production",
      "line_items": [
        {
          "merchant_id": "7765449334",
          "title": "Blue pen",
          "sku": "PEN3352227",
          "quantity": 250
        }
      ]
    }
  ]
}

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;tracker.carrier_code;tracker.tracking_number
COMPLEX1234;GGFFTE342;[email protected];Jane;Doe;COMPLEX1234_1;YDGE56TYY_1;partially_shipped;12, rue de Cléry;Paris;France;FR;Jane;Doe;75002;12355432;Amazing picture;HJY333452;1;ups;1Z548V626898567913
COMPLEX1234;GGFFTE342;[email protected];Jane;Doe;COMPLEX1234_1;YDGE56TYY_1;partially_shipped;12, rue de Cléry;Paris;France;FR;Jane;Doe;75002;55636421;Painting color blue;JUH78899777;3;;
COMPLEX1234;GGFFTE342;[email protected];Jane;Doe;COMPLEX1234_2;YDGE56TYY_2;preparing_shipment;12, rue de Cléry;Paris;France;FR;Jane;Doe;75002;6634778822;Blue pen;PEN 3352227;750;;
COMPLEX1234;GGFFTE342;[email protected];Jane;Doe;COMPLEX1234_3;YDGE56TYY_3;in_production;12, rue de Cléry;Paris;France;FR;Jane;Doe;75002;7765449334;Blue pen;PEN 3352227;250;;

As we decided to split the last line item into two distinct fulfillments, a new line item with the same sku but a different merchant_id has to be created.
The new line item quantity is the amount that needs to be manufactured. That is why the new line item has 7765449334 for merchant_id and 250 for quantity.
The other line item has its quantity updated to the quantity in stock. This is why the other line item still has 6634778822 for merchant_id and now has 750 for quantity.

4. Order with two fulfillments shipped and the last fulfillment partially shipped in different trackers

At this step, the first two fulfillments are now completely shipped. The last fulfillment, containing the 250 products which needed to be manufactured is ready to be shipped, but due to a logistical issue, only a subset of the line items can be sent. The rest of the line item's quantity is still present in the fulfillment.

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

{
  "merchant_id": "COMPLEX1234",
  "order_number": "GGFFTE342",
  "email": "[email protected]",
  "first_name": "Jane",
  "last_name": "Doe",
  "fulfillments": [
    {
      "merchant_id": "COMPLEX1234_1",
      "fulfillment_number": "YDGE56TYY_1",
      "status_code": "shipped",
      "warehouse_merchant_id": "warehouse_paris",
      "shipping_address": {
        "address1": "12, rue de Cléry",
        "city": "Paris",
        "country": "France",
        "country_code": "FR",
        "first_name": "Jane",
        "last_name": "Doe",
        "zip": "75002"
      },
      "trackers": [
        {
          "carrier_code": "ups",
          "tracking_number": "1Z548V626898567913",
          "line_items": [
            {
              "merchant_id": "12355432",
              "title": "Amazing picture",
              "sku": "HJY333452",
              "quantity": 1
            }
          ]
        },
        {
          "carrier_code": "dpd",
          "tracking_number": "15503895894309",
          "line_items": [
            {
              "merchant_id": "55636421",
              "title": "Painting color blue",
              "sku": "JUH78899777",
              "quantity": 3
            }
          ]
        }
      ]
    },
    {
      "merchant_id": "COMPLEX1234_2",
      "fulfillment_number": "YDGE56TYY_2",
      "status_code": "shipped",
      "warehouse_merchant_id": "warehouse_paris",
      "shipping_address": {
        "address1": "12, rue de Cléry",
        "city": "Paris",
        "country": "France",
        "country_code": "FR",
        "first_name": "Jane",
        "last_name": "Doe",
        "zip": "75002"
      },
      "trackers": [
        {
          "carrier_code": "ups",
          "tracking_number": "2Z548V626778567654",
          "line_items": [
            {
              "merchant_id": "6634778822",
              "title": "Blue pen",
              "sku": "PEN3352227",
              "quantity": 750
            }
          ]
        }
      ]
    },
    {
      "merchant_id": "COMPLEX1234_3",
      "fulfillment_number": "YDGE56TYY_3",
      "status_code": "partially_shipped",
      "warehouse_merchant_id": "warehouse_paris",
      "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": "7765449334",
          "title": "Blue pen",
          "sku": "PEN3352227",
          "quantity": 250
        }
      ],
      "trackers": [
        {
          "carrier_code": "ups",
          "tracking_number": "1J548W6267654678525",
          "line_items": [
            {
              "merchant_id": "7765449334",
              "title": "Blue pen",
              "sku": "PEN3352227",
              "quantity": 250,
              "shipped_quantity": 200
            }
          ]
        }
      ]
    }
  ]
}

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;tracker.carrier_code;tracker.tracking_number;tracker.shipped_quantity
COMPLEX1234;GGFFTE342;[email protected];Jane;Doe;COMPLEX1234_1;YDGE56TYY_1;shipped;12, rue de Cléry;Paris;France;FR;Jane;Doe;75002;12355432;Amazing picture;HJY333452;1;ups;1Z548V626898567913;
COMPLEX1234;GGFFTE342;[email protected];Jane;Doe;COMPLEX1234_1;YDGE56TYY_1;shipped;12, rue de Cléry;Paris;France;FR;Jane;Doe;75002;55636421;Painting color blue;JUH78899777;3;dpd;15503895894309;
COMPLEX1234;GGFFTE342;[email protected];Jane;Doe;COMPLEX1234_2;YDGE56TYY_2;shipped;12, rue de Cléry;Paris;France;FR;Jane;Doe;75002;6634778822;Blue pen;PEN 3352227;750;ups;2Z548V626778567654;
COMPLEX1234;GGFFTE342;[email protected];Jane;Doe;COMPLEX1234_3;YDGE56TYY_3;partially_shipped;12, rue de Cléry;Paris;France;FR;Jane;Doe;75002;7765449334;Blue pen;PEN 3352227;750;ups;1J548W6267654678525;200
COMPLEX1234;GGFFTE342;[email protected];Jane;Doe;COMPLEX1234_3;YDGE56TYY_3;partially_shipped;12, rue de Cléry;Paris;France;FR;Jane;Doe;75002;7765449334;Blue pen;PEN 3352227;750;ups;;

As in the advanced situation of the order with a line item split into two trackers, we can see that the last line item, with merchant_id 7765449334, still has 250 for quantity.
We used the shipped_quantity field to indicate that only 200 line items were sent in the tracker 1J548W6267654678525.
The remaining quantity of the line item in the fulfillment can be deduced using the quantity and shipped_quantity fields. We have 50 line items not yet shipped.

5. Order with three fulfillments shipped

Finally, the order's shipping is complete. Hooray!

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

{
  "merchant_id": "COMPLEX1234",
  "order_number": "GGFFTE342",
  "email": "[email protected]",
  "first_name": "Jane",
  "last_name": "Doe",
  "shipping_address": {
    "address1": "12, rue de Cléry",
    "city": "Paris",
    "country": "France",
    "country_code": "FR",
    "first_name": "Jane",
    "last_name": "Doe",
    "zip": "75002"
  },
  "fulfillments": [
    {
      "merchant_id": "COMPLEX1234_1",
      "fulfillment_number": "YDGE56TYY_1",
      "status_code": "shipped",
      "warehouse_merchant_id": "warehouse_paris",
      "trackers": [
        {
          "carrier_code": "ups",
          "tracking_number": "1Z548V626898567913",
          "line_items": [
            {
              "merchant_id": "12355432",
              "title": "Amazing picture",
              "sku": "HJY333452",
              "quantity": 1
            }
          ]
        },
        {
          "carrier_code": "dpd",
          "tracking_number": "15503895894309",
          "line_items": [
            {
              "merchant_id": "55636421",
              "title": "Painting color blue",
              "sku": "JUH78899777",
              "quantity": 3
            }
          ]
        }
      ]
    },
    {
      "merchant_id": "COMPLEX1234_2",
      "fulfillment_number": "YDGE56TYY_2",
      "status_code": "shipped",
      "warehouse_merchant_id": "warehouse_paris",
      "trackers": [
        {
          "carrier_code": "ups",
          "tracking_number": "2Z548V626778567654",
          "line_items": [
            {
              "merchant_id": "6634778822",
              "title": "Blue pen",
              "sku": "PEN3352227",
              "quantity": 750
            }
          ]
        }
      ]
    },
    {
      "merchant_id": "COMPLEX1234_3",
      "fulfillment_number": "YDGE56TYY_3",
      "status_code": "partially_shipped",
      "warehouse_merchant_id": "warehouse_paris",
      "line_items": [
        {
          "merchant_id": "7765449334",
          "title": "Blue pen",
          "sku": "PEN3352227",
          "quantity": 250
        }
      ],
      "trackers": [
        {
          "carrier_code": "ups",
          "tracking_number": "1J548W6267654678525",
          "line_items": [
            {
              "merchant_id": "7765449334",
              "title": "Blue pen",
              "sku": "PEN3352227",
              "quantity": 250,
              "shipped_quantity": 200
            }
          ]
        },
        {
          "carrier_code": "ups",
          "tracking_number": "3Z548X6267334678998",
          "line_items": [
            {
              "merchant_id": "7765449334",
              "title": "Blue pen",
              "sku": "PEN3352227",
              "quantity": 250,
              "shipped_quantity": 50
            }
          ]
        }
      ]
    }
  ]
}

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;tracker.carrier_code;tracker.tracking_number;tracker.shipped_quantity
COMPLEX1234;GGFFTE342;[email protected];Jane;Doe;COMPLEX1234_1;YDGE56TYY_1;shipped;12, rue de Cléry;Paris;France;FR;Jane;Doe;75002;12355432;Amazing picture;HJY333452;1;ups;1Z548V626898567913;
COMPLEX1234;GGFFTE342;[email protected];Jane;Doe;COMPLEX1234_1;YDGE56TYY_1;shipped;12, rue de Cléry;Paris;France;FR;Jane;Doe;75002;55636421;Painting color blue;JUH78899777;3;dpd;15503895894309;
COMPLEX1234;GGFFTE342;[email protected];Jane;Doe;COMPLEX1234_2;YDGE56TYY_2;shipped;12, rue de Cléry;Paris;France;FR;Jane;Doe;75002;6634778822;Blue pen;PEN 3352227;750;ups;2Z548V626778567654;
COMPLEX1234;GGFFTE342;[email protected];Jane;Doe;COMPLEX1234_3;YDGE56TYY_3;shipped;12, rue de Cléry;Paris;France;FR;Jane;Doe;75002;7765449334;Blue pen;PEN 3352227;750;ups;1J548W6267654678525;200
COMPLEX1234;GGFFTE342;[email protected];Jane;Doe;COMPLEX1234_3;YDGE56TYY_3;shipped;12, rue de Cléry;Paris;France;FR;Jane;Doe;75002;7765449334;Blue pen;PEN 3352227;750;ups;3Z548X6267334678998;50

For the last fulfillment, we used the two shipped_quantity fields to indicate that 200 products were sent in the tracker 1J548W6267654678525, and that 50 products were sent in the tracker 3Z548X6267334678998.

Updated over 1 year ago