Skip to content
YoPrintDevelopers

Add, change and remove invoice lines at once

Open .md

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

v2Operation ID v2_public_invoice_item_bulk

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

The body is an array of objects.

  • actionstringrequired
    • One of: "create", "update", "delete"
  • bidstringrequired

    Your label for this action, echoed in some errors.

  • cart_item_idstring

    The invoice line. Required for update and delete.

  • payloadobject

    Required for create and update: the line body, as on the single calls.

Response

200Successful response.

  • dataarray of objectsrequired

    Every line of the invoice after the call, one envelope each, all marked CREATED. has_changes is at the top level, next to data.

    Fields of each item (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.
    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; 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.

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