---
updatedAt: 2026-02-23T14:04:14.000Z
agentTools:
  projectIndex: https://developers.shipup.co/llms.txt
---

# 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](https://developers.shipup.co/reference/line-item-object) 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:

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

* the customer later cancels 2 of these 5 notebooks:

```json
{
  "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:

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

{
  "merchant_id": "HM120D9",
  "order_number": "HM120D9",
  "email": "jane@gmail.com",
  "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.