# Add, change and remove invoice lines at once

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

- API version: v2
- Operation ID: `v2_public_invoice_item_bulk`
- Section: Invoices and payments › [Invoice line items](https://developer.yoprint.com/reference/invoice-line-items.md)
- Web page: https://developer.yoprint.com/reference/invoice-line-items/v2-invoice-item-bulk/
- Authentication: `Authorization: Bearer YOUR_API_KEY`

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

The body is a JSON array of actions. Each has your own label `bid`, an `action`, and for `create` and `update` a `payload` with the same body as Add a line to an invoice or Update an invoice line; `update` and `delete` name the line in `cart_item_id`.

YoPrint runs every delete first, then the creates, then the updates, then recalculates once. Returns every line of the invoice afterwards, and 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. Quantities take up to 8 decimal places, a discount `rate` 4 and a manual tax `total` 6; more decimals are a 422 `validation_failed`. A shipping fee price is rounded half-up to 6 decimal places (a float `value` there is 422 `amount_out_of_range`). 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 invoice's sales 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

- Tax lines can't be added or changed here: 422 "Tax Item is not allow in bulk operations." A `delete` of the tax line is carried out on an invoice without Auto Invoice (it is refused on one with it). Use Change the tax on an invoice for tax changes.
- 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 invoice is the same code with reason `item_not_available`; the same sales order line twice is reason `duplicate_order_item`. Deleting a line that is already deleted is skipped.
- Creates run sorted by kind and sales order line, not in the order you sent: use `position` for the order on the invoice.
- `lock_version` is not checked in bulk.
- Every rule of the single calls applies to each action.

## Side effects

- Recalculates the invoice: line totals, subtotal, shipping, discounts, tax and total.
- Updates the sales order's invoiced totals and each line's invoiced status (not invoiced, partly, fully, or over-invoiced), and automatically redistributes (reallocates) recorded payments across the order's invoices to match updated totals (funds frozen by an open dispute or review stay where they are).
- When the team syncs to QuickBooks Online automatically and the order is published, the order is synced again about 3 minutes later (not after a change of `position` only).
- 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 invoice's `id` (a hash id), as its answers show it. Its unique key (`ordinv_...`) also works, but API answers don't include it. Example `cBRpSf5nw6upt5`.

## 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 some errors.
- `cart_item_id` (string, optional): The invoice line. Required for `update` and `delete`.
- `payload` (object, optional): Required for `create` and `update`: the line body, as on the single calls.

### Example request

```bash
curl -X POST 'https://secure.yoprint.com/v2/api/store/your-team/v2/invoice/cBRpSf5nw6upt5/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": "update",
      "bid": "row-2",
      "cart_item_id": "wigm2YNiE4PciF",
      "payload": {
        "quantity": {
          "total": {
            "dp": 0,
            "value": 6
          },
          "type": "unit"
        }
      }
    },
    {
      "action": "delete",
      "bid": "row-3",
      "cart_item_id": "DW7m2sWa8vVVDL"
    }
  ]'
```

## Response

`200` Successful response.

Fields:

- `data` (array of objects, required): Every line of the invoice after the call, one envelope each, all marked `CREATED`. `has_changes` is at the top level, next to `data`.
  - Each item:
    - `object_type` (string, optional): Always `"invoice_item"`.
    - `action_performed` (string, optional): `NONE` when nothing changed. One of: `"CREATED"`, `"UPDATED"`, `"DELETED"`, `"NONE"`.
    - `has_changes` (boolean, optional)
    - `item` (object, optional): An invoice line.
      - `_meta` (object, optional): Read-only: `id`, `type`, `invoice_id`, `lock_version`, `from_legacy`, `position_hash`.
      - `auto_invoice_managed` (boolean, optional): YoPrint manages this line (Auto Invoice).
      - `external_ids` (array of objects, optional): Links to external systems; empty for lines made in YoPrint.
      - `external_type` (string | null, optional)
      - `from_legacy` (boolean, optional)
      - `id` (string, optional): The invoice line.
      - `invoice_id` (string, optional): The invoice.
      - `is_external` (boolean, optional)
      - `lock_version` (integer, optional): Send it back on Update an invoice line to detect a concurrent change.
      - `position` (integer, optional)
      - `pricing` (object, optional): Absent on tax and discount lines. `system` (sales order lines): `_meta.unit_price` is the price copied from the sales order line and `_meta.subtotal` is that price × this line's quantity. `fee` (shipping fees): `product.total` is the fee. Prices come at the stored scale (6 decimal places); `_meta.subtotal` at the combined scale of price × quantity (compacted when large). Always read `dp`.
        - `type` (string, optional): One of: `"system"`, `"fee"`.
      - `product` (object, optional)
        - `_meta` (object, optional): Read-only details, always an object (with `editable_fields_on_update`); for `order_item`, `parent` describes the sales order line.
        - `properties` (object, optional): The kind's fields; for `order_item`, `id` is the sales order line. A discount's percentage or amount comes back as `total` (you send it as `rate`).
        - `type` (string, optional): One of: `"order_item"`, `"shipment_fee"`, `"invoice_discount"`, `"user_tax"`, `"override_tax"`, `"auto_tax"`, `"invoice_surcharge"`.
      - `quantity` (object, optional): Absent on tax and discount lines.
        - `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.
      - `tax` (object, optional): Absent on tax and discount lines. YoPrint adds it by default only to sales order lines (`taxable`); other lines have it only when it was sent.
        - `type` (string, optional): One of: `"taxable"`, `"non_taxable"`.
      - `type` (string, optional): Same as `product.type`.
    - `lock_version` (object, optional): Lock versions after the change.
      - `invoice` (object, optional): The invoice's lock versions: `invoice_item_lock_version`, `invoice_lock_version`.
      - `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`.
- `status` (integer, required)
- `success` (boolean, required)

Example response:

```json
{
  "data": [
    {
      "action_performed": "CREATED",
      "has_changes": true,
      "item": {
        "_meta": {
          "from_legacy": false,
          "id": "nhsGsn84PyJBvK",
          "invoice_id": "cBRpSf5nw6upt5",
          "lock_version": 1730000000000000,
          "position_hash": "EXAMPLEpositionHash",
          "type": "order_item"
        },
        "auto_invoice_managed": false,
        "external_ids": [],
        "external_type": null,
        "from_legacy": false,
        "id": "nhsGsn84PyJBvK",
        "invoice_id": "cBRpSf5nw6upt5",
        "is_external": false,
        "lock_version": 1730000000000000,
        "position": 100,
        "position_hash": "EXAMPLEpositionHash",
        "pricing": {
          "_meta": {
            "subtotal": {
              "dp": 0,
              "value": 300
            },
            "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"
        },
        "tax": {
          "type": "taxable"
        },
        "type": "order_item"
      },
      "lock_version": {
        "invoice": {
          "invoice_item_lock_version": 1730000000000000,
          "invoice_lock_version": 1730000000000000
        },
        "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
        }
      },
      "object_type": "invoice_item"
    },
    {
      "action_performed": "CREATED",
      "has_changes": true,
      "item": {
        "_meta": {
          "from_legacy": false,
          "id": "wigm2YNiE4PciF",
          "invoice_id": "cBRpSf5nw6upt5",
          "lock_version": 1730000000000000,
          "position_hash": "EXAMPLEpositionHash",
          "type": "order_item"
        },
        "auto_invoice_managed": false,
        "external_ids": [],
        "external_type": null,
        "from_legacy": false,
        "id": "wigm2YNiE4PciF",
        "invoice_id": "cBRpSf5nw6upt5",
        "is_external": false,
        "lock_version": 1730000000000000,
        "position": 200,
        "position_hash": "EXAMPLEpositionHash",
        "pricing": {
          "_meta": {
            "subtotal": {
              "dp": 0,
              "value": 180
            },
            "unit_price": {
              "dp": 6,
              "value": 30000000
            }
          },
          "type": "system"
        },
        "product": {
          "_meta": {
            "parent": {
              "product_name": "Gildan 18500 Hoodie"
            }
          },
          "properties": {
            "id": "OM2IMHqOYFKlP4"
          },
          "type": "order_item"
        },
        "quantity": {
          "total": {
            "dp": 0,
            "value": 6
          },
          "type": "unit"
        },
        "tax": {
          "type": "taxable"
        },
        "type": "order_item"
      },
      "lock_version": {
        "invoice": {
          "invoice_item_lock_version": 1730000000000000,
          "invoice_lock_version": 1730000000000000
        },
        "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
        }
      },
      "object_type": "invoice_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 invoice isn't your team's. Fix: Check the invoice 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 its `bid` and `fields`) or a rule refuses an action; nothing is saved. Fix: Fix the named action and resend the whole array.

## Notes

- Every line in the response says `CREATED`, whatever happened to it; use the top-level `has_changes` (next to `data`) instead.
- An empty array succeeds with `has_changes` false.

## Related

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