Line items configuration

Overview

A line_item is a product included in an order, with an associated quantity.

📘

Check out the line_item object reference for an exhaustive list of the attributes

This guide will explain how to use some of these fields.

Title

A line_item has a title, that is used in notifications and on the tracking page.

To accommodate various possibilities regarding your own data model, we built this attribute with additional flexibility.

There are 3 fields related to the line_item title:

• title (eg. "iPod Nano")
• variant_title (eg. "Green 32 Go")
• name (eg. "Green iPod Nano of 32 Go")

By default, {{ title }} - {{ variant_title }} (eg. "iPod Nano - Green 32 Go") is used to describe a line_item in notifications.

👍

If you don't provide a variant_title, then title alone is used (without the dash)

In the Shipup admin, you can decide whether you want to display {{ title }} - {{ variant_title }} or {{ name }} instead (eg. "Green iPod Nano of 32 Go").

Description

You can provide an optional description for the line item. (eg. "Portable media player iPod Nano, 7th generation")

By default, the description is not displayed on customer notifications - you'll need to activate them in the Shipup back office.

Quantity

There are 3 fields related to a product's quantity within a fulfillment:

• quantity
• canceled_quantity
• shipped_quantity

🚧

The quantity must never change during a line item's life. Only the shipped_quantity and canceled_quantity attributes can change.

Use case: Canceled Quantity

Let's illustrate how to use the canceled_quantity field:

• the customer orders 5 notebooks:

{
  "line_items": [
    {
      "merchant_id": "1938123",
      "title": "Blue notebook",
      "sku": "BNH123K4",
      "quantity": 5
    }
  ]
}

• the customer later cancels 2 of these 5 notebooks:

{
  "line_items": [
    {
      "merchant_id": "1938123",
      "title": "Blue notebook",
      "sku": "BNH123K4",
      "quantity": 5, // the quantity remains the same
      "canceled_quantity": 2 // only the canceled_quantity evolves
    }
  ]
}

If the canceled_quantity is greater than or equal to the quantity, then the line item's canceled attribute will be forced to true.

📘

For the sake of simplicity, these examples display line_items on their own. In a real-life example, these line_items would be nested within an order, a fulfillment or a tracker.

Use case: Shipped Quantity

The shipped_quantity attribute is designed for use cases where the amount of a single product shipped cannot fit in a single parcel (ie. tracker).

For instance, if a customer orders 200 hammers (quantity), but you can only fit 150 in a single tracker, here are the order, fulfillment and trackers we expect to receive:

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

{
  "merchant_id": "HM120D9",
  "order_number": "HM120D9",
  "email": "[email protected]",
  "first_name": "Jane",
  "last_name": "Doe",
  "fulfillments": [
    {
      "merchant_id": "QSK29104",
      "fulfillment_number": "QSK29104",
      "status_code": "shipped",
      "trackers": [
        {
          "carrier_code": "ups",
          "tracking_number": "1J548W6267654678525",
          "line_items": [
            {
              "merchant_id": "7765449334",
              "title": "Hammer",
              "sku": "HMR123456",
              "quantity": 200, // the quantity remains the same
              "shipped_quantity": 150 // the shipped_quantity is used to know how many items are in the tracker
            }
          ]
        },
        {
          "carrier_code": "ups",
          "tracking_number": "1J548W6267654678528",
          "line_items": [
            {
              "merchant_id": "7765449334",
              "title": "Hammer",
              "sku": "HMR123456",
              "quantity": 200, // the quantity remains the same
              "shipped_quantity": 50 // the shipped_quantity is used to know how many items are in the tracker
            }
          ]
        }
      ]
    }
  ]
}

Notice how the quantity field remains the same in both line items - it's the shipped_quantity field that informs Shipup of how many of a line_item was shipped within the nesting tracker.

Requires Shipping

The requires_shipping attribute is designed for products that will never require shipping, like a virtual membership to a plan.

When a line_item is identified with requires_shipping: false, it singles it out in notifications and in the tracking page display (as this product is not technically part of the parcel).

❗️

Do not use the requires_shipping attribute to specify that a canceled line_item will not be shipped anymore - Shipup already handles graciously this use case when you use the canceled_quantity or canceled attributes.