Skip to content
YoPrintDevelopers

Add a line to an invoice

Open .md

POST/v2/api/store/{team_slug}/v2/invoice/{unique_key}/item

v2Operation ID v2_public_invoice_item_create

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_slugstringrequired

    Your team slug, shown as Team ID next to your API key in Profile.

    • Example your-team
  • unique_keystringrequired

    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

application/json, required.

What are you adding?

Send one of these 6 bodies.

Sales order lineShipping feeDiscountTax from a tax presetManual taxAuto Tax

Sales order line

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

  • productobjectrequired
    Child fields (2)
    • typestringrequired
      • Always "order_item"
    • propertiesobjectrequired
      Child fields (1)
      • idstringrequired

        The sales order line's id (a hash id). It must be on this invoice's order and not already on this invoice.

  • quantityobjectrequired

    How many to bill. Not negative; you may bill more than was ordered.

    Child fields (2)
    • typestringrequired
      • Always "unit"
    • totaldecimal pairrequired

      The quantity, up to 8 decimal places.

      • { "value": 1250, "dp": 2 } is 12.50: value holds the digits, dp the decimal places. See Money and quantities.
  • positionintegerrequired

    Where the line sits on the invoice; lower comes first. Not checked against other lines.

  • taxobject

    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.

    Child fields (1)
    • typestringrequired
      • One of: "taxable", "non_taxable"

Example request

curl
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

A shipping charge. Its quantity is always 1.

  • pricingobjectrequired
    Child fields (2)
    • typestringrequired
      • Always "fee"
    • productobjectrequired
      Child fields (1)
      • totaldecimal pairrequired

        The fee. Rounded half-up to 6 decimal places.

        • { "value": 1250, "dp": 2 } is 12.50: value holds the digits, dp the decimal places. See Money and quantities.
  • productobjectrequired
    Child fields (2)
    • typestringrequired
      • Always "shipment_fee"
    • propertiesobjectrequired
      Child fields (3)
      • descriptionstring
      • namestring

        Defaults to "Shipping Fee".

      • shipping_taxableboolean

        Stored, but not used by the invoice tax calculation: to tax shipping, set shipping_taxable on the tax line.

        • Default false
  • positionintegerrequired

    Where the line sits on the invoice; lower comes first. Not checked against other lines.

  • taxobject

    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.

    Child fields (1)
    • typestringrequired
      • One of: "taxable", "non_taxable"

Example request

curl
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

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

  • productobjectrequired
    Child fields (2)
    • typestringrequired
      • Always "invoice_discount"
    • propertiesobjectrequired
      Child fields (5)
      • applies_to_shippingbooleanrequired

        Also discount the shipping.

      • ratedecimal pairrequired

        The percentage or amount, up to 4 decimal places, not negative.

        • { "value": 1250, "dp": 2 } is 12.50: value holds the digits, dp the decimal places. See Money and quantities.
      • typestringrequired

        percent takes rate as a percentage (10 is 10%); total as an amount.

        • One of: "percent", "total"
      • descriptionstring
      • namestring

        Defaults to "Discount".

  • positionintegerrequired

    Where the line sits on the invoice; lower comes first. Not checked against other lines.

  • taxobject

    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.

    Child fields (1)
    • typestringrequired
      • One of: "taxable", "non_taxable"

Example request

curl
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

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

  • productobjectrequired
    Child fields (2)
  • positionintegerrequired

    Where the line sits on the invoice; lower comes first. Not checked against other lines.

  • taxobject

    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.

    Child fields (1)
    • typestringrequired
      • One of: "taxable", "non_taxable"

Example request

curl
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

A tax you set by hand.

  • productobjectrequired
    Child fields (2)
    • typestringrequired
      • Always "override_tax"
    • propertiesobjectrequired
      Child fields (5)
      • totaldecimal pairrequired

        The tax amount or rate, up to 6 decimal places, not negative.

        • { "value": 1250, "dp": 2 } is 12.50: value holds the digits, dp the decimal places. See Money and quantities.
      • apply_before_discountboolean

        Work out the tax before discounts.

      • descriptionstring
      • modestring

        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_taxableboolean

        Tax the shipping too. Required when mode is percent.

  • positionintegerrequired

    Where the line sits on the invoice; lower comes first. Not checked against other lines.

  • taxobject

    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.

    Child fields (1)
    • typestringrequired
      • One of: "taxable", "non_taxable"

Example request

curl
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

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

  • productobjectrequired
    Child fields (2)
    • typestringrequired
      • Always "auto_tax"
    • propertiesobjectrequired
      Child fields (8)
      • enginestringrequired
        • Always "us"
      • fromobjectrequired

        Where the goods ship from. Without an override, the invoice's billing address.

        Child fields (2)
      • ratedecimal pairrequired

        Required but not used: the provider sets the rate.

        • { "value": 1250, "dp": 2 } is 12.50: value holds the digits, dp the decimal places. See Money and quantities.
      • toobjectrequired

        Where they ship to. Without an override, the invoice's shipping address, then its billing address.

        Child fields (2)
      • apply_before_discountboolean

        Ignored: always false.

      • descriptionstring
      • namestring

        Defaults to "Auto Tax".

      • shipping_taxableboolean

        Ignored: the provider decides.

  • positionintegerrequired

    Where the line sits on the invoice; lower comes first. Not checked against other lines.

  • taxobject

    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.

    Child fields (1)
    • typestringrequired
      • One of: "taxable", "non_taxable"

Example request

curl
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

200Successful response.

  • dataobjectrequired

    What happened, and the line.

    Child fields (5)
    • object_typestring
      • Always "invoice_item"
    • action_performedstring

      NONE when nothing changed.

      • One of: "CREATED", "UPDATED", "DELETED", "NONE"
    • has_changesboolean
    • itemobject

      An invoice line.

      Child fields (15)
      • _metaobject

        Read-only: id, type, invoice_id, lock_version, from_legacy, position_hash.

      • auto_invoice_managedboolean

        YoPrint manages this line (Auto Invoice).

      • external_idsarray of objects

        Links to external systems; empty for lines made in YoPrint.

      • external_typestring | null
      • from_legacyboolean
      • idstring

        The invoice line.

      • invoice_idstring

        The invoice.

      • is_externalboolean
      • lock_versioninteger

        Send it back on Update an invoice line to detect a concurrent change.

      • positioninteger
      • pricingobject

        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.

        Child fields (1)
        • typestring
          • One of: "system", "fee"
      • productobject
        Child fields (3)
        • _metaobject

          Read-only details, always an object (with editable_fields_on_update); for order_item, parent describes the sales order line.

        • propertiesobject

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

        • typestring
          • One of: "order_item", "shipment_fee", "invoice_discount", "user_tax", "override_tax", "auto_tax", "invoice_surcharge"
      • quantityobject

        Absent on tax and discount lines.

        Child fields (2)
        • typestring
          • Always "unit"
        • totaldecimal pair

          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.

      • taxobject

        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.

        Child fields (1)
        • typestring
          • One of: "taxable", "non_taxable"
      • typestring

        Same as product.type.

    • lock_versionobject

      Lock versions after the change.

      Child fields (2)
      • invoiceobject

        The invoice's lock versions: invoice_item_lock_version, invoice_lock_version.

      • orderobject

        The order's lock versions: job_lock_version, invoice_lock_version, order_item_lock_version, shipment_lock_version, payment_lock_version, order_lock_version.

  • statusintegerrequired
  • successbooleanrequired

Errors

  • 401The API key is missing or wrong (unauthenticated).

  • 403You 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.

  • 404Not 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.

  • 422The 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.

AI agents: read /llms.txt; add .md to any page URL for its Markdown. Guides and concepts in one file: /llms-full.txt.

Download the OpenAPI specSupport: support@yoprint.comyoprint.com