# Add, change and remove shipment lines at once

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

- API version: v2
- Operation ID: `v2_public_shipment_item_bulk`
- 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-bulk/
- Authentication: `Authorization: Bearer YOUR_API_KEY`

Applies several line changes to one shipment in one transaction: all of them are saved, or none.

The body is a JSON array of actions, each with your own label `bid`, an `action`, a `payload` for `create` and `update` (the same body as the single calls) and `cart_item_id` for `update` and `delete`. YoPrint runs the deletes first, then the creates, then the updates, and recalculates once. Returns every line of the shipment afterwards, with a top-level `has_changes`. 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`.

## 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

- One action per line: a second is 422 `cart_item_validation_error` with `error.context.reason` `duplicate_item_action` and the row's `error.bid`.
- An `update` or `delete` of a line that isn't on the shipment is the same code with reason `item_not_available` (and `error.bid`). Deleting an already deleted line is skipped.
- The validation and Shopify lock rules of the single calls apply to each action (the Shopify lock to every action, synced line or not). Two don't: a shipping cost line for a package that already has one is created again (the single call answers `NONE`), and the draft-order "Publish this order before ..." rule for externally synced shipments isn't checked.

## 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.

The body is an array of objects.

Fields:

- `action` (string, required): One of: `"create"`, `"update"`, `"delete"`.
- `bid` (string, required): Your label for this action, echoed in errors.
- `cart_item_id` (string, optional): The shipment line. Required for `update` and `delete`.
- `payload` (object, optional): Required for `create` and `update`.

### Example request

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

## Response

`200` Successful response.

Fields:

- `data` (array of objects, required): Every line of the shipment after the save, one envelope each (deleted lines are absent). `has_changes` is at the top level, next to `data`.
  - Each item:
    - `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"
    }
  ],
  "has_changes": true,
  "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`; `bulk_validation_payload_failed` names the failing item's `bid` and its `fields`.
  - When: A payload fails validation (`bulk_validation_payload_failed`, with `bid` and `fields`), or a rule refuses an action; nothing is saved. Fix: Fix the named action and resend the whole array.

## Notes

- Lines you updated say `UPDATED`; lines you created and lines you didn't touch both say `CREATED`, and deleted lines are absent. Use the top-level `has_changes` (next to `data`) to know whether anything changed.

## Related

- [Add a line to a shipment](https://developer.yoprint.com/reference/shipment-line-items/v2-shipment-item-create.md): `POST /v2/api/store/{team_slug}/v2/shipment/{unique_key}/item`
- [Update a shipment line](https://developer.yoprint.com/reference/shipment-line-items/v2-shipment-item-update.md): `PUT /v2/api/store/{team_slug}/v2/shipment/item/{unique_key}`
- [Remove a line from a shipment](https://developer.yoprint.com/reference/shipment-line-items/v2-shipment-item-destroy.md): `DELETE /v2/api/store/{team_slug}/v2/shipment/item/{unique_key}`