# Add a line to an invoice

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

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

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

| `product.type` | What it is |
| --- | --- |
| `order_item` | Bills a line of the sales order (any kind of product line). Name and unit price come from that line. |
| `shipment_fee` | A shipping charge with its own price. |
| `invoice_discount` | A discount, as a percentage or a fixed amount. |
| `user_tax` | Tax from one of your tax presets. |
| `override_tax` | A tax you set by hand: a fixed amount, a percentage, or tax exempt. |
| `auto_tax` | US Auto Tax, calculated by YoPrint's tax provider. |

The sales order line kinds (`db_catalog`, `user_simple`, `db_variant`, `custom`, `fee`) are not invoice kinds: to bill one, add an `order_item` line that points at it.

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

An invoice has at most one tax line (`auto_tax`, `user_tax` or `override_tax`). To switch the tax type, use Change the tax on an invoice rather than adding a second one.

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

- `product.type` and `position` are always required. Any group you send (`product`, `pricing`, `quantity`, `tax`) needs its `type`.
- A sales order line can be on an invoice once: a second time is 422 "Invoice already has the same Order Item".
- A sales order line from another order, or a deleted one, is 422 "This order item is not available for this invoice."
- One tax line per invoice: a second is 422 `cart_item_validation_error` with `error.context.reason` `tax_type_conflict` ("You can only have 1 Tax Type per Invoice").
- Auto Tax needs a US plan with Auto Tax turned on.
- On an Auto Invoice invoice (`auto_invoice_managed: true`), YoPrint automatically updates invoice lines to match the sales order's product lines and shipping fees. You cannot add, edit, or delete its order lines, or edit or delete the shipping fees and discounts created by YoPrint. You can still add your own custom discounts and shipping fees; YoPrint always places them after the managed lines regardless of the `position` you send.
- Invoices synced from Shopify can't take new lines: 422 "Cannot create invoice item for a Shopify-synced invoice."
- Fields that aren't listed are dropped, and a `null` counts as not sent.

## 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.
- An `auto_tax` line calls the tax provider while you wait.

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

What are you adding? Send one of these 6 bodies: **Sales order line**, **Shipping fee**, **Discount**, **Tax from a tax preset**, **Manual tax**, **Auto Tax**.

### Sales order line

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

Bills a line of the invoice's sales order. The unit price is always the sales order line's.

Fields:

- `product` (object, required)
  - `type` (string, required): Always `"order_item"`.
  - `properties` (object, required)
    - `id` (string, required): The sales order line's `id` (a hash id). It must be on this invoice's order and not already on this invoice.
- `quantity` (object, required): How many to bill. Not negative; you may bill more than was ordered.
  - `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 invoice; lower comes first. Not checked against other lines.
- `tax` (object, optional): Sales order lines (`order_item`) only: whether the line is taxed (default `taxable`). Ignored on other kinds: shipping is taxed by the tax line's `shipping_taxable`.
  - `type` (string, required): One of: `"taxable"`, `"non_taxable"`.

Example request (Sales order line):

```bash
curl -X POST 'https://secure.yoprint.com/v2/api/store/your-team/v2/invoice/cBRpSf5nw6upt5/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"
    },
    "tax": {
      "type": "taxable"
    }
  }'
```

### Shipping fee

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

A shipping charge. Its quantity is always 1.

Fields:

- `pricing` (object, required)
  - `type` (string, required): Always `"fee"`.
  - `product` (object, required)
    - `total` (decimal pair, required): The fee. Rounded half-up to 6 decimal places. `{ "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_fee"`.
  - `properties` (object, required)
    - `description` (string, optional)
    - `name` (string, optional): Defaults to "Shipping Fee".
    - `shipping_taxable` (boolean, optional): Stored, but not used by the invoice tax calculation: to tax shipping, set `shipping_taxable` on the tax line. Default `false`.
- `position` (integer, required): Where the line sits on the invoice; lower comes first. Not checked against other lines.
- `tax` (object, optional): Sales order lines (`order_item`) only: whether the line is taxed (default `taxable`). Ignored on other kinds: shipping is taxed by the tax line's `shipping_taxable`.
  - `type` (string, required): One of: `"taxable"`, `"non_taxable"`.

Example request (Shipping fee):

```bash
curl -X POST 'https://secure.yoprint.com/v2/api/store/your-team/v2/invoice/cBRpSf5nw6upt5/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": {
        "total": {
          "dp": 2,
          "value": 1500
        }
      },
      "type": "fee"
    },
    "product": {
      "properties": {
        "name": "Shipping",
        "shipping_taxable": false
      },
      "type": "shipment_fee"
    }
  }'
```

### Discount

Variant 3 of 6. On the web page: https://developer.yoprint.com/reference/invoice-line-items/v2-invoice-item-create/#variant-discount

A discount on the invoice. You may add more than one.

Fields:

- `product` (object, required)
  - `type` (string, required): Always `"invoice_discount"`.
  - `properties` (object, required)
    - `applies_to_shipping` (boolean, required): Also discount the shipping.
    - `rate` (decimal pair, required): The percentage or amount, up to 4 decimal places, not negative. `{ "value": 1250, "dp": 2 }` is 12.50 (see https://developer.yoprint.com/concepts/money-and-quantities.md).
    - `type` (string, required): `percent` takes `rate` as a percentage (10 is 10%); `total` as an amount. One of: `"percent"`, `"total"`.
    - `description` (string, optional)
    - `name` (string, optional): Defaults to "Discount".
- `position` (integer, required): Where the line sits on the invoice; lower comes first. Not checked against other lines.
- `tax` (object, optional): Sales order lines (`order_item`) only: whether the line is taxed (default `taxable`). Ignored on other kinds: shipping is taxed by the tax line's `shipping_taxable`.
  - `type` (string, required): One of: `"taxable"`, `"non_taxable"`.

Example request (Discount):

```bash
curl -X POST 'https://secure.yoprint.com/v2/api/store/your-team/v2/invoice/cBRpSf5nw6upt5/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": 950,
    "product": {
      "properties": {
        "applies_to_shipping": false,
        "name": "Loyalty discount",
        "rate": {
          "dp": 0,
          "value": 10
        },
        "type": "percent"
      },
      "type": "invoice_discount"
    }
  }'
```

### Tax from a tax preset

Variant 4 of 6. On the web page: https://developer.yoprint.com/reference/invoice-line-items/v2-invoice-item-create/#variant-tax-from-a-tax-preset

Tax from one of your tax presets: name and rate are copied from it.

Fields:

- `product` (object, required)
  - `type` (string, required): Always `"user_tax"`.
  - `properties` (object, required)
    - `id` (string, required): The tax preset (from List tax presets).
    - `apply_before_discount` (boolean, optional): Work out the tax before discounts.
    - `description` (string, optional)
    - `shipping_taxable` (boolean, optional): Tax the shipping too.
- `position` (integer, required): Where the line sits on the invoice; lower comes first. Not checked against other lines.
- `tax` (object, optional): Sales order lines (`order_item`) only: whether the line is taxed (default `taxable`). Ignored on other kinds: shipping is taxed by the tax line's `shipping_taxable`.
  - `type` (string, required): One of: `"taxable"`, `"non_taxable"`.

Example request (Tax from a tax preset):

```bash
curl -X POST 'https://secure.yoprint.com/v2/api/store/your-team/v2/invoice/cBRpSf5nw6upt5/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": 1000,
    "product": {
      "properties": {
        "id": "KC48n7qAAfGYMM"
      },
      "type": "user_tax"
    }
  }'
```

### Manual tax

Variant 5 of 6. On the web page: https://developer.yoprint.com/reference/invoice-line-items/v2-invoice-item-create/#variant-manual-tax

A tax you set by hand.

Fields:

- `product` (object, required)
  - `type` (string, required): Always `"override_tax"`.
  - `properties` (object, required)
    - `total` (decimal pair, required): The tax amount or rate, up to 6 decimal places, not negative. `{ "value": 1250, "dp": 2 }` is 12.50 (see https://developer.yoprint.com/concepts/money-and-quantities.md).
    - `apply_before_discount` (boolean, optional): Work out the tax before discounts.
    - `description` (string, optional)
    - `mode` (string, optional): `fixed_total` and `tax_exempt` take `total` as the tax amount; `percent` as a rate. One of: `"fixed_total"`, `"tax_exempt"`, `"percent"`. Default `"fixed_total"`.
    - `shipping_taxable` (boolean, optional): Tax the shipping too. Required when `mode` is `percent`.
- `position` (integer, required): Where the line sits on the invoice; lower comes first. Not checked against other lines.
- `tax` (object, optional): Sales order lines (`order_item`) only: whether the line is taxed (default `taxable`). Ignored on other kinds: shipping is taxed by the tax line's `shipping_taxable`.
  - `type` (string, required): One of: `"taxable"`, `"non_taxable"`.

Example request (Manual tax):

```bash
curl -X POST 'https://secure.yoprint.com/v2/api/store/your-team/v2/invoice/cBRpSf5nw6upt5/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": 1000,
    "product": {
      "properties": {
        "description": "Sales tax",
        "mode": "fixed_total",
        "total": {
          "dp": 2,
          "value": 825
        }
      },
      "type": "override_tax"
    }
  }'
```

### Auto Tax

Variant 6 of 6. On the web page: https://developer.yoprint.com/reference/invoice-line-items/v2-invoice-item-create/#variant-auto-tax

US Auto Tax. YoPrint asks its tax provider for the rate while you wait.

Fields:

- `product` (object, required)
  - `type` (string, required): Always `"auto_tax"`.
  - `properties` (object, required)
    - `engine` (string, required): Always `"us"`.
    - `from` (object, required): Where the goods ship from. Without an override, the invoice's billing address.
      - `override` (boolean, required)
      - `address_id` (string, optional): Required when `override` is true.
    - `rate` (decimal pair, required): Required but not used: the provider sets the rate. `{ "value": 1250, "dp": 2 }` is 12.50 (see https://developer.yoprint.com/concepts/money-and-quantities.md).
    - `to` (object, required): Where they ship to. Without an override, the invoice's shipping address, then its billing address.
      - `override` (boolean, required)
      - `address_id` (string, optional): Required when `override` is true.
    - `apply_before_discount` (boolean, optional): Ignored: always false.
    - `description` (string, optional)
    - `name` (string, optional): Defaults to "Auto Tax".
    - `shipping_taxable` (boolean, optional): Ignored: the provider decides.
- `position` (integer, required): Where the line sits on the invoice; lower comes first. Not checked against other lines.
- `tax` (object, optional): Sales order lines (`order_item`) only: whether the line is taxed (default `taxable`). Ignored on other kinds: shipping is taxed by the tax line's `shipping_taxable`.
  - `type` (string, required): One of: `"taxable"`, `"non_taxable"`.

Example request (Auto Tax):

```bash
curl -X POST 'https://secure.yoprint.com/v2/api/store/your-team/v2/invoice/cBRpSf5nw6upt5/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": 1000,
    "product": {
      "properties": {
        "engine": "us",
        "from": {
          "override": false
        },
        "rate": {
          "dp": 0,
          "value": 0
        },
        "to": {
          "override": false
        }
      },
      "type": "auto_tax"
    }
  }'
```

## Response

`200` Successful response.

Fields:

- `data` (object, required): What happened, and the line.
  - `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"
  },
  "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 (`user_is_not_authorized`). 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`; 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: A field fails validation (`validation_failed`, details in `error.fields`), for example "The selected product.type is invalid." or a number that isn't a valid pair. Fix: Fix the named fields.
  - When: A business rule refuses the line: `cart_item_validation_error`, with `error.context.reason` naming it (`tax_type_conflict`, `duplicate_order_item`, `item_not_available`, `managed_invoice`, `auto_tax_unavailable`). Fix: Read `error.message`; see the rules.
  - When: A tax preset or Auto Tax address isn't found, or Auto Tax couldn't be calculated. These come back as a bare `{ "message": ... }` without the usual error envelope. Fix: Check the preset or address id; retry Auto Tax later.

## Notes

- Billing more than was ordered is allowed; the sales order line then shows as over-invoiced.
- Invoices have no locked or permanently "paid" state: you can change invoice lines even after payments are recorded. When an invoice total changes, YoPrint automatically redistributes (reallocates) the order's recorded payments across its invoices according to their updated balances.

## Related

- [List the lines of an invoice](https://developer.yoprint.com/reference/invoice-line-items/v2-invoice-item-index.md): `GET /v2/api/store/{team_slug}/v2/invoice/{unique_key}/item`
- [Add, change and remove invoice lines at once](https://developer.yoprint.com/reference/invoice-line-items/v2-invoice-item-bulk.md): `POST /v2/api/store/{team_slug}/v2/invoice/{unique_key}/item/bulk`
- [Change the tax on an invoice](https://developer.yoprint.com/reference/invoices/v2-invoice-tax-selection-update.md): `PUT /v2/api/store/{team_slug}/v2/invoice/{unique_key}/tax-selection`
- [Add a line item to a sales order or quote](https://developer.yoprint.com/reference/sales-order-line-items/v2-order-item-store.md): `POST /v2/api/store/{team_slug}/v2/sales_order/{order_unique_key}/order_item`