Status page

API/FTP: Send an order - advanced scenario

Suggest Edits

Now that you know how to send basic orders via API, let's focus on some advanced scenarios.

1. Order with multiple trackers

Orders might be sent to their recipient into different shipments. In that case, you need to let Shipup know how the different order line items will be split into the final trackers. There are two options to split line items: In multiple fulfillments at the order level, or in multiple trackers at the fulfillment level.

Whether to pick the first or second option depends on when the decision to send multiple shipments occurs in your information system. If you know in advance that the order will be sent in several shipments, prefer splitting your order in multiple fulfillments as it will give a clearer view to your customer in its tracking page and more notification options. Splitting a fulfillment into several trackers happens when you anticipated a single shipment, but logistics constraints (line item out of stock, line items don't fit in a single package, ...) later changed the shipping plans.

1.1. Order with multiple fulfillments

Splitting your order in multiple fulfillments occurs when you know right away that the order will require several shipments.

For instance, an online grocery store could have a combination of two types of products: fresh groceries that will be delivered the next day using an express delivery service and regular products that will follow a normal logistics flow and be delivered within 2-4 days. Another example is when you have different stock levels for an order's line items: some are already in stock and will be shipped right away while others need to be manufactured or moved from a warehouse to another before being shipped.

In these situations, you will send the order with several fulfillments, each containing its allocated line items. In the below example, one of the order's fulfillments is already shipped while the second is still in transit to stock:

// 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_FRESH",
      "warehouse_merchant_id": "warehouse_paris",
      "status_code": "shipped",
        "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": "766533422",
              "title": "Butter",
              "sku": "BUT3546633",
              "quantity": 2
            }
          ]
        }
      ]
    },
    {
      "merchant_id": "ODR1234_2",
      "fulfillment_number": "ZDDA445YY_REGULAR",
      "status_code": "in_transit_to_stock",
      "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": "637448222",
          "title": "Soap",
          "sku": "SOA54644667",
          "quantity": 12
        }
      ]
    }
  ]
}

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
ODR1234;YDGE56TYY;[email protected];Jane;Doe;ODR1234_1;YDGE56TYY_FRESH;shipped;12, rue de Cléry;Paris;France;FR;Jane;Doe;75002;766533422;Butter;BUT3546633;2;ups;1Z548V626898567913
ODR1234;YDGE56TYY;[email protected];Jane;Doe;ODR1234_2;ZDDA445YY_REGULAR;in_transit_to_stock;12, rue de Cléry;Paris;France;FR;Jane;Doe;75002;637448222;Soap;SOA54644667;12;;

1.2. Fulfillment with multiple trackers

On some occasions, your logistics department may need to split the fulfillment into several shipments. For example, if one of the line items is very heavy and needs its own tracker. Or if a line item's quantity is too high to be shipped in a single package. In this situation, the trackers field will contain two line items.

// 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",
        "country": "France",
        "country_code": "FR",
        "first_name": "Jane",
        "last_name": "Doe",
        "zip": "75002"
      },
      "trackers": [
        {
          "carrier_code": "ups",
          "tracking_number": "1Z548V626898567913",
          "line_items": [
            {
              "merchant_id": "55636421",
              "title": "Painting color blue",
              "sku": "JUH78899777",
              "quantity": 3
            }
          ]
        },
        {
          "carrier_code": "dpd",
          "tracking_number": "15503895894309",
          "line_items": [
            {
              "merchant_id": "12355432",
              "title": "Amazing picture",
              "sku": "HJY333452",
              "quantity": 1
            }
          ]
        }
      ]
    }
  ]
}

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
ODR1234;YDGE56TYY;[email protected];Jane;Doe;ODR1234_1;YDGE56TYY_1;shipped;12, rue de Cléry;Paris;France;FR;Jane;Doe;75002;12355432;Amazing picture;HJY333452;1;dpd;15503895894309
ODR1234;YDGE56TYY;[email protected];Jane;Doe;ODR1234_1;YDGE56TYY_1;shipped;12, rue de Cléry;Paris;France;FR;Jane;Doe;75002;55636421;Painting color blue;JUH78899777;3;ups;1Z548V626898567913

2. Order with a line item split into two trackers

In some situations, the line item's quantity is too high to be sent all at once. It could be split into two or more trackers using the shipped_quantity attribute:

// 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",
      "warehouse_merchant_id": "warehouse_paris",
      "status_code": "shipped",
        "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": "6634778822",
              "title": "Blue pen",
              "sku": "PEN3352227",
              "quantity": 1000,
              "shipped_quantity": 750
            }
          ]
        },
        {
          "carrier_code": "ups",
          "tracking_number": "1Z548V626898567915",
          "line_items": [
            {
              "merchant_id": "6634778822",
              "title": "Blue pen",
              "sku": "PEN3352227",
              "quantity": 1000,
              "shipped_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;tracker.shipped_quantity
ODR1234;YDGE56TYY;[email protected];Jane;Doe;ODR1234_1;YDGE56TYY_1;shipped;12, rue de Cléry;Paris;France;FR;Jane;Doe;75002;6634778822;Blue pen;PEN 3352227;1000;ups;1Z548V626898567913;750
ODR1234;YDGE56TYY;[email protected];Jane;Doe;ODR1234_1;YDGE56TYY_1;shipped;12, rue de Cléry;Paris;France;FR;Jane;Doe;75002;6634778822;Blue pen;PEN 3352227;1000;ups;1Z548V626898567915;250

📘

shipped_quantity and quantity

The line item quantity has not changed in this example. The line item with merchant_id 6634778822 was ordered with a quantity of 1000. You must repeat this quantity and all other line item's fields in your payloads. That is why we repeat the title and quantity fields in the two line items. To specify what quantity has been shipped in each tracker you must add a shipped_quantity field with the shipped quantity in each line item.

3. Order without fulfillments

Sometimes, when an order is placed you do not yet have the information on how you will split the different products into fulfillments. In this situation, you can create an order without any fulfillments. Line items should first be added at the order level, and then split into different fulfillments in a subsequent payload. Here's how the first payload might look like:

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

{
  "merchant_id": "ODR1234",
  "order_number": "YDGE56TYY",
  "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
    }
  ]
}

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

4. Order with a partially shipped fulfillment

It may occur that some line items which were supposed to be shipped in a single fulfillment end up being shipped only partially. For example one of the line items could be damaged or out of stock without you knowing beforehand. In this situation, you will have a fulfillment with partially_shipped status. Part of the line items will be in the fulfillment's line_items field, while another part will be in the first tracker's line_items field:

// 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",
      "warehouse_merchant_id": "warehouse_paris",
      "status_code": "partially_shipped",
        "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
            }
          ]
        }
      ]
    }
  ]
}

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
ODR1234;YDGE56TYY;[email protected];Jane;Doe;ODR1234_1;YDGE56TYY_1;partially_shipped;12, rue de Cléry;Paris;France;FR;Jane;Doe;75002;12355432;Amazing picture;HJY333452;1;ups;1Z548V626898567913
ODR1234;YDGE56TYY;[email protected];Jane;Doe;ODR1234_1;YDGE56TYY_1;partially_shipped;12, rue de Cléry;Paris;France;FR;Jane;Doe;75002;55636421;Painting color blue;JUH78899777;3;;

Updated 11 months ago