# Add a line to a shipment

```http
POST https://secure.yoprint.com/v2/api/store/{team_slug}/v2/shipment/{unique_key}/item
```

- API version: v2
- Operation ID: `v2_public_shipment_item_create`
- Section: Shipping › [Shipment line items](https://developer.yoprint.com/reference/shipment-line-items.md)
- Web page: https://developer.yoprint.com/reference/shipment-line-items/v2-shipment-item-create/
- Authentication: `Authorization: Bearer YOUR_API_KEY`

Adds one line to a shipment and recalculates it. Returns the line in an action envelope (`action_performed` `CREATED`, `has_changes`, `lock_version`, `item`).

| `product.type` | What it is |
| --- | --- |
| `order_item` | Ships a quantity of a line of the same order (any kind of product line, or a fee). |
| `shipment_cost` | A shipping cost line (Shipping Cost in the web app), with its own price, optionally tied to a package or an estimate. |

Numbers are `{ value, dp }` pairs: `value` is the number without its decimal point and `dp` the count of decimal places, so 12.50 is `{ "value": 1250, "dp": 2 }` (or `{ "value": 125, "dp": 1 }`). `value` is a JSON integer or a digit string, never a float: `12.5` is refused. Quantities take up to 8 decimal places; shipping costs and a pricing mode's rate take 6. More significant decimals than that are a 422, not rounded. Send very large numbers as strings. Answers send prices at the stored scale (6 decimal places), quantities without trailing zeros, and `_meta.subtotal` (price × quantity) at the combined scale, compacted when it would exceed a safe integer: always read `dp`.

Nothing caps the quantity at what was ordered: shipping more marks the order line over-allocated.

## Permission

Needs permission to edit the shipment's order: the team owner, a role whose Manage Sales Orders permission is "update all", or "update assigned" when you created the order or are assigned to it, or, on a draft order, its creator when their role can create sales orders. Otherwise 403 `user_is_not_authorized`. Reading needs only team membership.

## Business rules

- `product.type` is `order_item` or `shipment_cost` only; the order line kinds (`db_catalog` and so on) are refused with "The selected product.type is invalid."
- An order line can be on a shipment once: 422 `cart_item_validation_error` "Shipment already has the same Order Item".
- The order line must be on the shipment's order and shippable; otherwise 422 with a bare `{ "message": "order_item: ..." }`.
- A shipping cost line's package or estimate must belong to this shipment. A second cost line for the same package returns the first with `action_performed` `NONE`.
- A Shopify shipment that is locked (managed by Shopify or already fulfilled there) or has a broken Shopify link takes no new lines: 422 `validation_error` "Cannot create Shopify-synced shipment item from API." An externally synced shipment on a draft order: "Publish this order before creating an externally synced shipment item."
- Fields that aren't listed are dropped, and a `null` counts as not sent (except `shipment_package_id` and `shipment_estimate_id`).

## Side effects

- Recalculates the shipment's cost and billable fee totals and the order's shipping totals.
- Updates each order line's shipped status (not allocated, partly, fully or over-allocated).
- On an Auto Invoice order, shipping cost lines are mirrored as shipping fees on the managed invoice.
- Open Admin Portal pages refresh, and so do Customer Portal pages the order's customer has open. No webhook or email is sent.

## Path parameters

- `team_slug` (string, required): Your team slug, shown as Team ID next to your API key in Profile. Example `your-team`.
- `unique_key` (string, required): The shipment's `id` (a hash id), as its answers show it. Its unique key (`shp_...`) also works, but API answers don't include it. Example `MQyJUnd3oty75h`.

## Request body

Content type `application/json`, required.

What are you adding? Send one of these 2 bodies: **Order line**, **Shipping cost**.

### Order line

Variant 1 of 2. On the web page: https://developer.yoprint.com/reference/shipment-line-items/v2-shipment-item-create/#variant-order-line

Ships a quantity of a line of the same order.

Fields:

- `product` (object, required)
  - `type` (string, required): Always `"order_item"`.
  - `properties` (object, required)
    - `id` (string, required): The order line's `id` (a hash id). It must be on the shipment's order, shippable, and not already on this shipment.
- `quantity` (object, required): How many to ship. Not negative; may be more than ordered (the line then shows as over-allocated).
  - `type` (string, required): Always `"unit"`.
  - `total` (decimal pair, required): The quantity, up to 8 decimal places. `{ "value": 1250, "dp": 2 }` is 12.50 (see https://developer.yoprint.com/concepts/money-and-quantities.md).
- `position` (integer, required): Where the line sits on the shipment; lower comes first.
- `pricing` (object, optional): Optional; the price always comes from the order line.
  - `type` (string, optional): Always `"system"`.

Example request (Order line):

```bash
curl -X POST 'https://secure.yoprint.com/v2/api/store/your-team/v2/shipment/MQyJUnd3oty75h/item' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'X-Yoprint-Decimal-Format: exact-v1' \
  -H 'Content-Type: application/json' \
  -d '{
    "position": 100,
    "product": {
      "properties": {
        "id": "ZJTJ2uF5dMiArL"
      },
      "type": "order_item"
    },
    "quantity": {
      "total": {
        "dp": 0,
        "value": 24
      },
      "type": "unit"
    }
  }'
```

### Shipping cost

Variant 2 of 2. On the web page: https://developer.yoprint.com/reference/shipment-line-items/v2-shipment-item-create/#variant-shipping-cost

A shipping cost line with its own cost.

Fields:

- `pricing` (object, required)
  - `type` (string, required): Always `"shipment_cost"`.
  - `product_cost` (object, required)
    - `pricing_mode` (string, required): Send `none`: the price billed is the cost. See the notes for the other values. One of: `"none"`, `"override"`, `"markup"`, `"margin"`.
    - `total` (decimal pair, optional): The cost, up to 6 decimal places. Missing means 0. `{ "value": 1250, "dp": 2 }` is 12.50 (see https://developer.yoprint.com/concepts/money-and-quantities.md).
- `product` (object, required)
  - `type` (string, required): Always `"shipment_cost"`.
  - `properties` (object, required)
    - `name` (string, required)
    - `description` (string, optional)
    - `shipment_estimate_id` (string | null, optional): A shipping estimate of this shipment the cost comes from.
    - `shipment_package_id` (string | null, optional): A package of this shipment the cost is for. One live cost line per package: a second create returns the existing line.
- `position` (integer, required)
- `quantity` (object, optional): Optional and not used in the totals.

Example request (Shipping cost):

```bash
curl -X POST 'https://secure.yoprint.com/v2/api/store/your-team/v2/shipment/MQyJUnd3oty75h/item' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'X-Yoprint-Decimal-Format: exact-v1' \
  -H 'Content-Type: application/json' \
  -d '{
    "position": 900,
    "pricing": {
      "product_cost": {
        "pricing_mode": "none",
        "total": {
          "dp": 2,
          "value": 1240
        }
      },
      "type": "shipment_cost"
    },
    "product": {
      "properties": {
        "name": "USPS Ground Advantage",
        "shipment_package_id": "o6foWpSAayc79D"
      },
      "type": "shipment_cost"
    }
  }'
```

## Response

`200` Successful response.

Fields:

- `data` (object, required): What happened, and the line.
  - `object_type` (string, optional): Always `"shipment_item"`.
  - `action_performed` (string, optional): `NONE` when nothing changed. One of: `"CREATED"`, `"UPDATED"`, `"DELETED"`, `"NONE"`.
  - `has_changes` (boolean, optional)
  - `item` (object, optional): A shipment line.
    - `_meta` (object, optional): Read-only details of the line.
    - `auto_invoice_managed` (boolean, optional)
    - `billable_fee_total` (decimal pair, optional): Shipping cost lines only: what is billed (after override, markup or margin); `pricing.product_cost.total` is the cost. A decimal pair: the amount is `value` ÷ 10^`dp` (`{ "value": 1250, "dp": 2 }` is 12.50). Read `dp` every time: it can differ between fields and records. See https://developer.yoprint.com/concepts/money-and-quantities.md.
    - `external_ids` (array of objects, optional): Links to external systems; usually empty.
    - `external_type` (string | null, optional)
    - `from_legacy` (boolean, optional)
    - `id` (string, optional): The shipment line.
    - `is_external` (boolean, optional)
    - `lock_version` (integer, optional): Returned but not checked on shipment lines.
    - `position` (integer, optional)
    - `pricing` (object, optional): For `system`, `_meta.unit_price` is the order line's unit price and `_meta.subtotal` is that price × this shipment line's quantity (`_meta.total` is always 0); for `shipment_cost`, `product_cost` has `override` (always true for lines saved through the API), `total` (the cost), `pricing_mode` and `pricing_mode_total` (decimal pairs at 6 decimal places).
      - `type` (string, optional): One of: `"system"`, `"shipment_cost"`.
    - `product` (object, optional)
      - `_meta` (object, optional): Read-only details; for `order_item`, `parent` describes the order line.
      - `properties` (object, optional): For `order_item`, `id` is the order line; for `shipment_cost`, `name`, `description`, `shipment_package_id`, `shipment_estimate_id`.
      - `type` (string, optional): One of: `"order_item"`, `"shipment_cost"`.
    - `quantity` (object, optional)
      - `type` (string, optional): Always `"unit"`.
      - `total` (decimal pair, optional): The quantity. A decimal pair: the amount is `value` ÷ 10^`dp` (`{ "value": 1250, "dp": 2 }` is 12.50). Read `dp` every time: it can differ between fields and records. See https://developer.yoprint.com/concepts/money-and-quantities.md.
    - `shipment_id` (string, optional): The shipment.
    - `type` (string, optional): Same as `product.type`.
    - `weight` (object, optional): The order line's weight (`_meta.total`, `_meta.unit`).
  - `lock_version` (object, optional): Lock versions after the change.
    - `order` (object, optional): The order's lock versions: `job_lock_version`, `invoice_lock_version`, `order_item_lock_version`, `shipment_lock_version`, `payment_lock_version`, `order_lock_version`.
    - `shipment` (object, optional): The shipment's lock versions: `shipment_item_lock_version`, `shipment_lock_version`.
- `status` (integer, required)
- `success` (boolean, required)

Example response:

```json
{
  "data": {
    "action_performed": "CREATED",
    "has_changes": true,
    "item": {
      "auto_invoice_managed": false,
      "external_ids": [],
      "external_type": null,
      "from_legacy": false,
      "id": "u8mEG7LHUtS55s",
      "is_external": false,
      "lock_version": 1730000000000000,
      "position": 100,
      "pricing": {
        "_meta": {
          "subtotal": {
            "dp": 0,
            "value": 300
          },
          "total": {
            "dp": 0,
            "value": 0
          },
          "unit_price": {
            "dp": 6,
            "value": 12500000
          }
        },
        "type": "system"
      },
      "product": {
        "_meta": {
          "parent": {
            "product_name": "Gildan 5000 T-shirt"
          }
        },
        "properties": {
          "id": "ZJTJ2uF5dMiArL"
        },
        "type": "order_item"
      },
      "quantity": {
        "total": {
          "dp": 0,
          "value": 24
        },
        "type": "unit"
      },
      "shipment_id": "MQyJUnd3oty75h",
      "type": "order_item",
      "weight": {
        "type": "use_system"
      }
    },
    "lock_version": {
      "order": {
        "invoice_lock_version": 1730000000000000,
        "job_lock_version": 1730000000000000,
        "order_item_lock_version": 1730000000000000,
        "order_lock_version": 1730000000000000,
        "payment_lock_version": 1730000000000000,
        "shipment_lock_version": 1730000000000000
      },
      "shipment": {
        "shipment_item_lock_version": 1730000000000000,
        "shipment_lock_version": 1730000000000000
      }
    },
    "object_type": "shipment_item"
  },
  "status": 200,
  "success": true
}
```

## Errors

- `401` The API key is missing or wrong (`unauthenticated`).
- `403` You are not allowed to do this. `api_access_not_in_plan`: your team's plan doesn't include API access (Pro and above, with an active subscription or trial), so every request answers this until the team upgrades. When your role lacks the permission the operation needs, the body is only `{"message": "Insufficient Permission"}`. Other refusals use the error envelope, with `unauthorized` or `user_is_not_authorized`.
  - When: Your role can't edit this order. Fix: Ask the team owner to adjust your role or assign you to the order.
- `404` Not found. `page_not_found`: the team slug is unknown, you are not a member of the team, or an id in the path is not one of this team's. `code: null`, with a message that starts "No query results for": there is no record with that id.
  - When: The shipment isn't your team's. Fix: Check the id.
- `422` The request was refused and changed nothing. `validation_failed` lists what to fix in `error.fields`; other codes name a business rule, explained in `error.message`. A few checks answer with only `{"message": "..."}`. An operation that calls another service (a payment provider, a carrier, an accounting app) can answer `connect_timeout` ("Please retry again") when that service does not answer in time: the change may or may not have happened there, so read the record back before you retry.
  - When: Validation (`validation_failed`) or a business rule (`cart_item_validation_error`, or a bare `message`). Fix: Read the message and fix the line.

## Notes

- A shipping cost line's `pricing_mode` `override`, `markup` and `margin` are accepted, but the API can't pass their rate: `override` bills 0 and the others bill the cost. Use `none` and set the cost you want to bill.

## Related

- [List the lines of a shipment](https://developer.yoprint.com/reference/shipment-line-items/v2-shipment-item-index.md): `GET /v2/api/store/{team_slug}/v2/shipment/{unique_key}/item`
- [Add, change and remove shipment lines at once](https://developer.yoprint.com/reference/shipment-line-items/v2-shipment-item-bulk.md): `POST /v2/api/store/{team_slug}/v2/shipment/{unique_key}/item/bulk`
- [List the packages of a shipment](https://developer.yoprint.com/reference/shipment-packages/v2-shipment-package-index.md): `GET /v2/api/store/{team_slug}/v2/shipment/{hash_id}/packages`