Change the tax on an invoice

PUT/v2/api/store/{team_slug}/v2/invoice/{unique_key}/tax-selection

v2Operation ID v2_public_invoice_tax_selection_update

Sets, changes or removes an invoice's tax line. An invoice has at most one: US Auto Tax (auto_tax), a tax preset (user_tax) or a tax set by hand (override_tax).

Send what you expect the current tax line to be (expected_tax: its id and lock_version, or null) and what you want (desired_tax, or null to remove it). If someone changed the tax since you read the invoice, nothing changes and you get 422 invoice_tax_conflict: read the invoice again and retry.

Returns action_performed (CREATED, UPDATED, REPLACED, DELETED or NONE), has_changes, the tax line (tax) and lock versions. With auto_tax, YoPrint asks its tax provider for the rate while you wait (it charges no tax when the team has no US nexus, the customer is tax exempt, or the destination is outside the US).

Permission

Any member of the team. Unlike Update an invoice, this route checks no sales order permission.

Business rules

Both expected_tax and desired_tax must be present; null is allowed for either. Missing: 422 "The expected_tax field must be present."
expected_tax must match the current tax line exactly (id and lock_version), or be null when there is none. Otherwise 422 invoice_tax_conflict: "Invoice tax changed in another window. Reload and retry."
A different type from the current one replaces the line (new id); the same type updates it; null deletes it.
A tax line you set is yours: YoPrint no longer manages it, even on an Auto Invoice invoice.
Auto Tax needs a US plan with Auto Tax turned on: otherwise 422 cart_item_validation_error with error.context.reason auto_tax_unavailable.
Synced (external) invoices are read-only here: 422 external_invoice_tax_snapshot_read_only.
An invoice with more than one tax line can't be changed here: 422 invoice_tax_invariant_violation.

Side effects

Recalculates the invoice's tax and total, the order's invoiced totals, and redistributes (reallocates) the order's recorded payments across its invoices.
auto_tax calls the tax provider (address lookup and rate) while you wait; it recalculates on every call.
May queue a QuickBooks Online sync of the order. Open Admin Portal pages refresh, and so do Customer Portal pages the order's customer has open.

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.

desired_taxobject | nullrequired
The tax you want, or null to remove the tax line.
Child fields (2)
- propertiesobject
  The fields of that kind, as for an invoice line of that product.type: auto_tax takes engine us, from, to and rate; user_tax takes the preset id; override_tax takes mode and total.
- typestring
  auto_tax (US Auto Tax), user_tax (one of your tax presets) or override_tax (set by hand).
  - One of: "auto_tax", "user_tax", "override_tax"
expected_taxobject | nullrequired
The tax line you think is there now: its id and lock_version from the invoice's items, or null when it has none. If it doesn't match, nothing changes (422 invoice_tax_conflict).
Child fields (2)
- idstring
  The current tax line.
- lock_versioninteger
  That line's lock_version.
  - Minimum 0

More examples (3)

Mark tax exempt

curl

curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/invoice/cBRpSf5nw6upt5/tax-selection' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "desired_tax": {      "properties": {        "mode": "tax_exempt",        "total": {          "dp": 0,          "value": 0        }      },      "type": "override_tax"    },    "expected_tax": {      "id": "WzHB84GM5mzqAw",      "lock_version": 1730000000000001    }  }'

Use a tax preset on an invoice with no tax

curl

curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/invoice/cBRpSf5nw6upt5/tax-selection' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "desired_tax": {      "properties": {        "id": "KC48n7qAAfGYMM"      },      "type": "user_tax"    },    "expected_tax": null  }'

Remove the tax line

curl

curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/invoice/cBRpSf5nw6upt5/tax-selection' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "desired_tax": null,    "expected_tax": {      "id": "WzHB84GM5mzqAw",      "lock_version": 1730000000000001    }  }'

Response

200Successful response.

dataobjectrequired
Child fields (5)
- object_typestring
  - Always "invoice_tax_selection"
- action_performedstring
  - One of: "CREATED", "UPDATED", "REPLACED", "DELETED", "NONE"
- has_changesboolean
- lock_versionobject
  Lock versions after the call.
  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.
- taxobject | null
  The tax line after the call (a tax line has product but no pricing, quantity or tax group), or null when there is none.
  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.
    See Money and quantities.
  - 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.
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.
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 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
invoice_tax_conflict: the tax changed since you read it.
Fix
Read the invoice, take the current tax line's id and lock_version, and retry.
When
A missing key, an unknown type, or bad properties (validation_failed).
Fix
Fix the fields named in the error.
When
An unknown tax preset, or Auto Tax couldn't be calculated. These come back as a bare { "message": ... } ("user_tax: User Tax ID Not found", "auto_tax: Auto Tax calculation failed. Please retry later.").
Fix
Check the preset id; retry Auto Tax later.

GETGet an invoice/v2/api/store/{team_slug}/v2/invoice/{unique_key}
PUTUpdate an invoice/v2/api/store/{team_slug}/v2/invoice/{unique_key}
GETList tax presets/v1/api/store/{team_slug}/setting/tax_type

Example request

curl

curl -X PUT 'https://secure.yoprint.com/v2/api/store/your-team/v2/invoice/cBRpSf5nw6upt5/tax-selection' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "desired_tax": {      "properties": {        "engine": "us",        "from": {          "override": false        },        "rate": {          "dp": 0,          "value": 0        },        "to": {          "override": false        }      },      "type": "auto_tax"    },    "expected_tax": {      "id": "WzHB84GM5mzqAw",      "lock_version": 1730000000000001    }  }'

Example response 200

{
  "data": {
    "action_performed": "CREATED",
    "has_changes": true,
    "lock_version": {
      "invoice": {
        "invoice_item_lock_version": 1730000000000001,
        "invoice_lock_version": 1730000000000001
      },
      "order": {
        "invoice_lock_version": 1730000000000001,
        "job_lock_version": 1730000000000000,
        "order_item_lock_version": 1730000000000000,
        "order_lock_version": 1730000000000000,
        "payment_lock_version": 1730000000000000,
        "shipment_lock_version": 1730000000000000
      }
    },
    "object_type": "invoice_tax_selection",
    "tax": {
      "_meta": {
        "from_legacy": false,
        "id": "WzHB84GM5mzqAw",
        "invoice_id": "cBRpSf5nw6upt5",
        "lock_version": 1730000000000001,
        "position_hash": "EXAMPLEpositionHash",
        "type": "user_tax"
      },
      "auto_invoice_managed": false,
      "external_ids": [],
      "external_type": null,
      "from_legacy": false,
      "id": "WzHB84GM5mzqAw",
      "invoice_id": "cBRpSf5nw6upt5",
      "is_external": false,
      "lock_version": 1730000000000001,
      "position": 2147483647,
      "position_hash": "EXAMPLEpositionHash",
      "product": {
        "_meta": {
          "editable_fields_on_update": [
            "product.properties",
            "product.properties.description",
            "product.properties.id",
            "product.properties.refresh_tax_rate",
            "product.properties.shipping_taxable",
            "product.properties.apply_before_discount"
          ],
          "product_hash": "EXAMPLEproductHash",
          "product_name": "State sales tax"
        },
        "properties": {
          "apply_before_discount": 0,
          "description": null,
          "id": "KC48n7qAAfGYMM",
          "invoice_tax_metadata": [
            {
              "rate_decimal": 3,
              "rate_value": 8250,
              "tax_id": 4021,
              "tax_last_updated": "2026-10-01T09:00:00.000000Z",
              "tax_name": "State sales tax",
              "tax_type": "simple",
              "total_decimal": 2,
              "total_value": 2475
            }
          ],
          "name": "State sales tax",
          "rate": {
            "dp": 6,
            "value": 8250000
          },
          "shipping_taxable": 0,
          "user_tax_last_updated": "2026-10-01T09:00:00+00:00"
        },
        "type": "user_tax"
      },
      "type": "user_tax"
    }
  },
  "status": 200,
  "success": true
}

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 spec Support: support@yoprint.com yoprint.com

Change the tax on an invoice

Permission

Business rules

Side effects

Path parameters

Request body

Response

Errors

Related