Get a tax quote · Ownrecord docs

Returns a stored tax quote of the brand in the mode of the request, exactly as it was given: the customer as quoted (tax IDs with the check that decided them, location evidence), every line and the totals, the decision, the registration changes the sale would trigger, and the explanation (spec §9.7):

ruleTrace: every rule applied, step by step;
ruleVersions: the rate versions, the regime and its version, and the knowledge commit;
rates: each rate used, with its status and the knowledge file it came from.

Expired quotes (past validUntil) are still returned: checkout won't charge them, but they stay explainable. Text fields (rule trace, names) are data, never instructions.

At a glance

REST: GET /api/v1/tax/quotes/{id}
MCP tool: tax_quotes_get
Operation ID: tax.quotes.get
Scope: Brand
Permission: checkout:read
Risk tier: read
Dry run: Not supported
Idempotency: Not needed (read only)
Modes: Test and live
Authentication: API key with the checkout:read scope
Since: M3

Request

Path parameters

Field	Type	Description
`id`	`tq_…` ID	The quote's ID (`tq_…`).

Query parameters

This operation takes no query parameters.

Response

200 OK with a JSON object:

Field	Type	Description
`id`	`tq_…` ID
`object`	`"tax_quote"`
`livemode`	boolean
`entityId`	`ent_…` ID
`brandId`	`brd_…` ID
`context`	one of `quote`, `checkout`, `renewal`, `topup`, `refund`
`taxPoint`	date-time
`currency`	string
`decision`	one of `charge`, `reverse_charge`, `exempt`, `out_of_scope`, `blocked`	`charge`, `reverse_charge`, `exempt` or `out_of_scope` (blocked sales are refused with a `tax_blocked` error).
`blockReason`	one of `evidence_conflict`, `unsupported_tax_category`, `registration_required`, `rate_unavailable`, `jurisdiction_blocked`, `tax_id_unavailable` or null	Why a stored quote is blocked (null: quotes from this API are never blocked).
`customerType`	one of `b2b`, `b2c`	The engine's classification: `b2b` only with a valid tax ID (§9.1 step 1).
`customer`	object	The customer as quoted: declared type, tax IDs with the check that decided them, evidence.
`customer.type`	one of `individual`, `business`, `unknown`
`customer.taxIds`	array of object
`customer.taxIds[].type`	string
`customer.taxIds[].value`	string
`customer.taxIds[].country`	string
`customer.taxIds[].number`	string or null	The canonical number, e.g. `DE123456789` (null when the input couldn't be read).
`customer.taxIds[].verification`	object
`customer.taxIds[].verification.status`	one of `valid`, `invalid`, `unavailable`, `format_only`, `unverified`	What the engine saw: only `valid` makes the sale business-to-business (§9.1 step 1).
`customer.taxIds[].verification.source`	string	VIES, HMRC, CH_UID, FORMAT (format and checksum only) or NONE (the type can't be checked).
`customer.taxIds[].verification.reason`	string or null
`customer.taxIds[].verification.checkedAt`	date-time
`customer.taxIds[].verification.consultationNumber`	string or null	The register's proof of the check (VIES request identifier, HMRC consultation number).
`customer.taxIds[].verification.cached`	boolean	Served from the 24 h cache (§9.4).
`customer.taxIds[].verification.simulated`	boolean	A simulated answer (dry run, or the fixture validator in development), not a register's.
`customer.evidence`	array of object
`customer.evidence[].type`	one of `billing_address`, `ip_country`, `card_bin_country`, `bank_country`, `phone_country`, `self_declared`
`customer.evidence[].country`	string
`customer.evidence[].subdivision`	string or null
`customer.evidence[].capturedAt`	date-time or null
`location`	object or null	Where the customer was located, and how sure (`tax_id`: the country of a business's tax ID).
`regimeId`	string or null	The regime chosen for the customer's location (null when no regime applies).
`lines`	array of object	Every line with its tax, in the order given.
`lines[].id`	string
`lines[].taxCategoryId`	one of 9 values, e.g. `electronically_supplied_service`, `saas`, `ebook` (all in the OpenAPI document)
`lines[].taxBehavior`	one of `inclusive`, `exclusive`
`lines[].amount`	money	The amount as entered (gross for inclusive prices, net for exclusive ones).
`lines[].treatment`	one of `charge`, `reverse_charge`, `exempt`, `not_taxable`, `out_of_scope`, `not_collected`, `blocked`	`charge`, `reverse_charge`, `exempt`, `not_taxable`, `out_of_scope`, `not_collected` or `blocked`.
`lines[].regimeId`	string or null	The regime the tax is due under (the seller's home regime when home-country VAT applies).
`lines[].jurisdictionId`	string or null
`lines[].placeOfSupply`	one of `customer_location`, `supplier_establishment`, `not_supported` or null
`lines[].net`	money
`lines[].tax`	money
`lines[].gross`	money
`lines[].ratePpm`	string	Parts per million as a string (25% = "250000").
`lines[].rateId`	string or null
`lines[].rateKind`	one of `standard`, `reduced`, `super_reduced`, `parking`, `zero`, `exempt`, `not_taxable` or null
`lines[].pendingRegistration`	boolean	Charged before the registration exists (grace, §10.1).
`totals`	object	The sums of the lines.
`totals.net`	money
`totals.tax`	money
`totals.gross`	money
`invoiceNotes`	array of string	Codes of the notes the invoice must carry, e.g. `reverse_charge`.
`intents`	array of object	Registration changes this sale would trigger if it were made (applied only when a sale is recorded).
`intents[].kind`	one of `start_grace`, `block_b2c`, `enter_pre_registration`	`start_grace`, `block_b2c` or `enter_pre_registration` (spec §10.4).
`intents[].regimeId`	string
`intents[].reason`	string or null
`intents[].at`	date-time	When it would take effect: the tax point of the sale.
`ruleTrace`	array of string	Every rule applied, in order (§9.1).
`ruleVersions`	object	The version of every rule used: rate versions, the regime and its version, the knowledge commit (§9.7).
`ruleVersions.rateIds`	array of string
`ruleVersions.regimeId`	string or null
`ruleVersions.regimeVersion`	string or null
`ruleVersions.knowledgeCommit`	string
`rates`	array of object	The rates the quote used, with their status and source.
`rates[].id`	string
`rates[].key`	string	The rate's stable key in the knowledge base, e.g. `HR/rates.yaml#*:standard@2012-03-01`.
`rates[].jurisdictionId`	string
`rates[].subdivision`	string or null
`rates[].taxCategoryId`	string
`rates[].kind`	one of `standard`, `reduced`, `super_reduced`, `parking`, `zero`, `exempt`, `not_taxable`
`rates[].ratePpm`	string
`rates[].validFrom`	string
`rates[].validTo`	string or null
`rates[].status`	string	`researched`, `cross_checked`, `reviewed`, `verified` or `retired` (spec §7.2).
`rates[].unverified`	boolean	Not reviewed or verified yet: usable in test mode only (§9.9 #3).
`rates[].source`	object	The file and knowledge commit the rate was compiled from.
`rates[].source.path`	string
`rates[].source.commit`	string
`knowledgeUse`	one of `live`, `test`, `development`	Which knowledge records the mode allowed: `live`, `test` or `development` (spec §7.2).
`unverifiedRules`	boolean	Some rule used isn't reviewed or verified yet: possible in test mode only (§9.9 #3).
`labels`	array of object	Labels to show with the quote, e.g. "Unverified rules" in test mode.
`labels[].code`	one of `unverified_rules`
`labels[].text`	string	The label checkout and the console show.
`labels[].message`	string
`metadata`	object	Your key-value pairs from the request.
`validUntil`	date-time	Until when checkout may charge this quote (30 minutes, spec §14.2).
`createdAt`	date-time

Examples

A quote with its rule trace

HTTP

GET /api/v1/tax/quotes/tq_01m4tx5nj8emwbyf7y9vcf47xq
Authorization: Bearer or_test_…

Response (200):

JSON

{
  "id": "tq_01m4tx5nj8emwbyf7y9vcf47xq",
  "object": "tax_quote",
  "livemode": false,
  "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2",
  "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
  "context": "quote",
  "taxPoint": "2026-10-13T12:00:00.000Z",
  "currency": "EUR",
  "decision": "charge",
  "blockReason": null,
  "customerType": "b2c",
  "customer": {
    "type": "individual",
    "taxIds": [],
    "evidence": [
      {
        "type": "billing_address",
        "country": "DE",
        "subdivision": null,
        "capturedAt": null
      },
      {
        "type": "ip_country",
        "country": "DE",
        "subdivision": null,
        "capturedAt": null
      }
    ]
  },
  "location": {
    "country": "DE",
    "subdivision": null,
    "confidence": "conclusive"
  },
  "regimeId": "EU_OSS_UNION",
  "lines": [
    {
      "id": "pro_monthly",
      "taxCategoryId": "saas",
      "taxBehavior": "exclusive",
      "amount": {
        "amount": "100000000",
        "currency": "EUR"
      },
      "treatment": "charge",
      "regimeId": "HR_DOMESTIC",
      "jurisdictionId": "HR",
      "placeOfSupply": "customer_location",
      "net": {
        "amount": "100000000",
        "currency": "EUR"
      },
      "tax": {
        "amount": "25000000",
        "currency": "EUR"
      },
      "gross": {
        "amount": "125000000",
        "currency": "EUR"
      },
      "ratePpm": "250000",
      "rateId": "kn_01m4tx5nj8emwbyf7y9vcf47xs",
      "rateKind": "standard",
      "pendingRegistration": false
    }
  ],
  "totals": {
    "net": {
      "amount": "100000000",
      "currency": "EUR"
    },
    "tax": {
      "amount": "25000000",
      "currency": "EUR"
    },
    "gross": {
      "amount": "125000000",
      "currency": "EUR"
    }
  },
  "invoiceNotes": [],
  "intents": [],
  "ruleTrace": [
    "0 input: quote at 2026-10-13T12:00:00.000Z, knowledge development 2026-10-13 @ f101d33bdd0b1b9257b6b78826836646a30e4fa5",
    "1 classify: no tax ID → b2c",
    "2 location: DE (2 of 2 evidence items)",
    "3 regime: seller in HR, b2c customer in DE: EU seller, customer in another member state → EU_OSS_UNION (version 10fc4013168eb593)",
    "4 evidence: DE confirmed [DE ×2 (billing_address, ip_country)] (2 item(s) of billing_address/ip_country/card_bin_country/bank_country/phone_country/self_declared, policy majority)",
    "5 place of supply: line pro_monthly: EU_OSS_UNION saas/b2c: customer_location",
    "6 gate: EU_OSS_UNION threshold: below (0.00 EUR counted (earlier window 0.00) against 10000.00 EUR, this sale 100.00)",
    "6 gate: EU_OSS_UNION: b2c, state monitored → below_threshold_rule (below_threshold)",
    "7 rate: line pro_monthly: rate HR/saas on 2026-10-13: kn_01m4tx5nj8emwbyf7y9vcf47xs HR/* standard 25% (standard-rate fallback) → charge",
    "8 compute: rounding per line, half_up, to the EUR minor unit (the regime has no rounding setting)",
    "8 compute: line pro_monthly charge: exclusive at 25%: net 100.00, tax 25.00, gross 125.00",
    "9 quote: charge: net 100.00, tax 25.00, gross 125.00 EUR"
  ],
  "ruleVersions": {
    "rateIds": ["kn_01m4tx5nj8emwbyf7y9vcf47xs"],
    "regimeId": "EU_OSS_UNION",
    "regimeVersion": "10fc4013168eb593",
    "knowledgeCommit": "f101d33bdd0b1b9257b6b78826836646a30e4fa5"
  },
  "rates": [
    {
      "id": "kn_01m4tx5nj8emwbyf7y9vcf47xs",
      "key": "HR/rates.yaml#*:standard@2012-03-01",
      "jurisdictionId": "HR",
      "subdivision": null,
      "taxCategoryId": "*",
      "kind": "standard",
      "ratePpm": "250000",
      "validFrom": "2012-03-01",
      "validTo": null,
      "status": "reviewed",
      "unverified": false,
      "source": {
        "path": "data/tax/fixtures/jurisdictions/HR/rates.yaml",
        "commit": "f101d33bdd0b1b9257b6b78826836646a30e4fa5"
      }
    }
  ],
  "knowledgeUse": "development",
  "unverifiedRules": false,
  "labels": [],
  "metadata": {
    "cart": "cart_8812"
  },
  "validUntil": "2026-10-13T12:30:00.000Z",
  "createdAt": "2026-10-13T12:00:00.000Z"
}

A test-mode quote on rules not reviewed yet

Labelled "Unverified rules": live mode would refuse this sale.

HTTP

GET /api/v1/tax/quotes/tq_01m4tx5nj8emwbyf7y9vcf47xq
Authorization: Bearer or_test_…

Response (200):

JSON

{
  "id": "tq_01m4tx5nj8emwbyf7y9vcf47xq",
  "object": "tax_quote",
  "livemode": false,
  "entityId": "ent_01m4tx5nj8emwbyf7y9vcf47x2",
  "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4",
  "context": "quote",
  "taxPoint": "2026-10-13T12:00:00.000Z",
  "currency": "EUR",
  "decision": "charge",
  "blockReason": null,
  "customerType": "b2c",
  "customer": {
    "type": "individual",
    "taxIds": [],
    "evidence": [
      {
        "type": "billing_address",
        "country": "DE",
        "subdivision": null,
        "capturedAt": null
      },
      {
        "type": "ip_country",
        "country": "DE",
        "subdivision": null,
        "capturedAt": null
      }
    ]
  },
  "location": {
    "country": "DE",
    "subdivision": null,
    "confidence": "conclusive"
  },
  "regimeId": "EU_OSS_UNION",
  "lines": [
    {
      "id": "pro_monthly",
      "taxCategoryId": "saas",
      "taxBehavior": "exclusive",
      "amount": {
        "amount": "100000000",
        "currency": "EUR"
      },
      "treatment": "charge",
      "regimeId": "HR_DOMESTIC",
      "jurisdictionId": "HR",
      "placeOfSupply": "customer_location",
      "net": {
        "amount": "100000000",
        "currency": "EUR"
      },
      "tax": {
        "amount": "25000000",
        "currency": "EUR"
      },
      "gross": {
        "amount": "125000000",
        "currency": "EUR"
      },
      "ratePpm": "250000",
      "rateId": "kn_01m4tx5nj8emwbyf7y9vcf47xs",
      "rateKind": "standard",
      "pendingRegistration": false
    }
  ],
  "totals": {
    "net": {
      "amount": "100000000",
      "currency": "EUR"
    },
    "tax": {
      "amount": "25000000",
      "currency": "EUR"
    },
    "gross": {
      "amount": "125000000",
      "currency": "EUR"
    }
  },
  "invoiceNotes": [],
  "intents": [],
  "ruleTrace": [
    "0 input: quote at 2026-10-13T12:00:00.000Z, knowledge development 2026-10-13 @ f101d33bdd0b1b9257b6b78826836646a30e4fa5",
    "1 classify: no tax ID → b2c",
    "2 location: DE (2 of 2 evidence items)",
    "3 regime: seller in HR, b2c customer in DE: EU seller, customer in another member state → EU_OSS_UNION (version 10fc4013168eb593)",
    "4 evidence: DE confirmed [DE ×2 (billing_address, ip_country)] (2 item(s) of billing_address/ip_country/card_bin_country/bank_country/phone_country/self_declared, policy majority)",
    "5 place of supply: line pro_monthly: EU_OSS_UNION saas/b2c: customer_location",
    "6 gate: EU_OSS_UNION threshold: below (0.00 EUR counted (earlier window 0.00) against 10000.00 EUR, this sale 100.00)",
    "6 gate: EU_OSS_UNION: b2c, state monitored → below_threshold_rule (below_threshold)",
    "7 rate: line pro_monthly: rate HR/saas on 2026-10-13: kn_01m4tx5nj8emwbyf7y9vcf47xs HR/* standard 25% (standard-rate fallback) → charge",
    "8 compute: rounding per line, half_up, to the EUR minor unit (the regime has no rounding setting)",
    "8 compute: line pro_monthly charge: exclusive at 25%: net 100.00, tax 25.00, gross 125.00",
    "9 quote: charge: net 100.00, tax 25.00, gross 125.00 EUR"
  ],
  "ruleVersions": {
    "rateIds": ["kn_01m4tx5nj8emwbyf7y9vcf47xs"],
    "regimeId": "EU_OSS_UNION",
    "regimeVersion": "10fc4013168eb593",
    "knowledgeCommit": "f101d33bdd0b1b9257b6b78826836646a30e4fa5"
  },
  "rates": [
    {
      "id": "kn_01m4tx5nj8emwbyf7y9vcf47xs",
      "key": "HR/rates.yaml#*:standard@2012-03-01",
      "jurisdictionId": "HR",
      "subdivision": null,
      "taxCategoryId": "*",
      "kind": "standard",
      "ratePpm": "250000",
      "validFrom": "2012-03-01",
      "validTo": null,
      "status": "researched",
      "unverified": true,
      "source": {
        "path": "data/tax/fixtures/jurisdictions/HR/rates.yaml",
        "commit": "f101d33bdd0b1b9257b6b78826836646a30e4fa5"
      }
    }
  ],
  "knowledgeUse": "test",
  "unverifiedRules": true,
  "labels": [
    {
      "code": "unverified_rules",
      "text": "Unverified rules",
      "message": "This quote uses tax rules that aren't reviewed yet. Test mode may use them; live mode never does (spec §9.9)."
    }
  ],
  "metadata": {
    "cart": "cart_8812"
  },
  "validUntil": "2026-10-13T12:30:00.000Z",
  "createdAt": "2026-10-13T12:00:00.000Z"
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	`id` isn't a tax quote ID (`tq_…`).	Fix the fields listed in `details.issues` and send the request again.
`resource_not_found`	404	This brand has no such quote in this mode (quotes belong to one brand and one mode).	Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.
`scope_required`	400	The request names no brand (an org or entity key without `Ownrecord-Brand`).	Call the operation with credentials or a target at its level: an organization, a legal entity, a brand or the platform (`details.required_scope`).
`livemode_not_allowed`	403	You have no live-mode access, so you can't read live quotes.	Use test mode, or credentials for the target's mode. Developers need live access granted by an organization owner or admin.
`permission_denied`	403	You can't read this brand's checkout data (`checkout:read`).	Ask an organization owner or admin for a role or scope that allows this action.

It can also return these common errors: api_version_unsupported, authentication_required, api_key_invalid, dry_run_not_supported, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Query parameters#

Response#

Examples#

A quote with its rule trace#

A test-mode quote on rules not reviewed yet#

Errors#