tax_estimate
Preview the complete price breakdown including tax before ordering. Returns manufacturer quote, orchestration fee, tax on fee, and total.
Instructions
Preview the complete price breakdown — including tax — before placing an order.
Terms §7 contract: "Preview the tax for any order with the
``tax_estimate`` tool before placing it. We display the full
fee + tax breakdown before charging. No hidden fees."
This tool fulfills that contract by returning the same line
items the order will commit to at charge time. Per Terms §7
tax is computed on the orchestration fee ONLY — never on
the manufacturer's quoted total. The manufacturer is
responsible for any taxes on their own charges.
Two calling shapes are supported:
1. **Canonical preview** (recommended): pass
``manufacturer_quote_usd`` and the tool returns the
full breakdown — ``manufacturer_quote``,
``orchestration_fee``, ``tax_on_fee``, ``total`` — so
the agent can show the user the exact line items that
match the eventual charge. This is the shape Terms §7
commits to.
2. **Tax-only legacy** (compatibility): pass ``fee_amount``
with no ``manufacturer_quote_usd`` and the tool returns
the older ``{tax: {...}}`` shape, useful for callers
that already know the fee and only want the tax line.
Args:
fee_amount: Legacy — the platform fee amount (from the
quote's ``kiln_fee``). Used only when
``manufacturer_quote_usd`` is omitted.
jurisdiction: Where the buyer is located (e.g.
``"US-CA"``, ``"DE"``, ``"AU"``). Use
``tax_jurisdictions`` to see all supported codes.
When empty in canonical-preview mode, no tax is
applied (preview shows manuf + fee only).
business_tax_id: If the buyer is a business, their tax
ID (e.g. EU VAT number). In the EU, UK, Australia,
and Japan, businesses are exempt — the tax line
shows $0.00 with a note that reverse charge
applies.
manufacturer_quote_usd: Provider's quoted price (e.g.
from ``fulfillment_quote``). When non-zero,
triggers canonical-preview mode.
currency: Currency of the manufacturer quote (default
USD). Tax rates are applied at the standard
jurisdiction rate regardless.
user_email: Buyer's email — affects the free-tier
waiver (first 3 fulfillment orders/month per user
are fee-free). Available in canonical mode only.
Returns:
Canonical mode (``manufacturer_quote_usd > 0``):
``{success, manufacturer_quote, orchestration_fee,
tax_on_fee, total, currency, fee_waived,
fee_waiver_reason, tax_jurisdiction,
tax_rate_percent, tax_reverse_charge, note}``.
Legacy mode (``manufacturer_quote_usd == 0``):
``{success, tax: {...}}``.
Read-only — charges no card, contacts no provider.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| currency | No | USD | |
| fee_amount | No | ||
| user_email | No | ||
| jurisdiction | No | ||
| business_tax_id | No | ||
| manufacturer_quote_usd | No |