Learn how the Square Orders API calculates consumption tax in a way that is compatible with Japan's Qualified Invoice System, including tax logic, rounding behavior, discount handling, and API request/response examples.
Order Calculation Guide for Japan
This guide explains how the Square Orders API handles consumption tax calculation in a way that is compatible with Japan's Qualified Invoice System (適格請求書等保存方式 / インボイス制度). It covers the tax calculation logic, rounding behavior, discount handling, and includes concrete API request/response examples.
All examples in this guide use the 10% standard consumption tax rate. For multi-rate scenarios (10% + 8%), see Multi-rate tax setup with blocklists.
Note
Key takeaway: Use scope: ORDER on all taxes — Square then performs per-rate-bucket tax calculation that is compliant with the Japan Invoice System.
Japan's Qualified Invoice System (effective October 1, 2023) requires the following:
- Per-rate-bucket calculation - Group all items by tax rate (10% or 8%), sum the amounts in each bucket, apply the tax rate once to that subtotal, and round once.
- Two tax rates:
- 10% standard rate - Applies to the majority of goods and services, including alcohol and dine-in catering.
- 8% reduced rate - Applies to food and non-alcoholic beverages (takeout or delivery), and specific newspaper subscriptions.
- Single rounding per rate per invoice - Fractional yen amounts are rounded once per tax-rate category, not per line item.
- Invoice must show - Tax amount breakdown by rate, taxable subtotal per rate, and items subject to the reduced rate must be marked.
Per-line-item calculation can produce 1-yen discrepancies:
Example: ¥333 × 2 + ¥666, 10% inclusive tax Per-line-item (WRONG for Invoice System): Item A (×2): floor(333 × 10/110) × 2 = 30 × 2 = 60 Item B (×1): floor(666 × 10/110) = floor(60.54) = 60 Total tax = 120 Per-rate-bucket (CORRECT for Invoice System): Bucket subtotal: (333 × 2) + 666 = 1,332 Tax: floor(1332 × 10/110) = floor(121.09) = 121 Total tax = 121 → 1-yen difference!
The OrderLineItemTax object has a scope field with two values:
| Scope | What Square does | Japan compliance |
|---|---|---|
ORDER | Square automatically applies the tax to all eligible line items, computes one bucket tax on the aggregate subtotal, then apportions the result back to individual line items. | Compliant with Japan Invoice System |
LINE_ITEM | The tax is only applied to line items the caller explicitly lists; each line is computed separately, with no bucket aggregation. | Not compliant — may produce 1-yen discrepancies |
Always use scope: ORDER for Japan.
When you submit an order with ORDER-scoped taxes, Square performs the following steps automatically:
- Square groups line items into tax-rate buckets. Based on which taxes are not blocked by
pricing_blocklists, Square assigns each line item to its applicable tax rate. - Square sums each bucket. For each tax rate, Square sums the post-discount line amounts into one subtotal.
- Square computes tax once per bucket. Square multiplies the bucket subtotal by the tax rate and truncates (floor) once. This single tax value per rate bucket is the authoritative tax.
- Square apportions the bucket tax back to line items. Square splits each bucket's tax total back to individual lines proportionally. Line-level tax amounts may shift depending on what else is in the order — this is expected behavior. The per-rate total and order total remain exact.
For JPY currency, Square uses truncation (round-down / floor), not round-half-up. This is determined by currency and is not configurable. The bucket-level tax computation uses floor for JPY, but per-line apportionment uses banker's rounding (round-half-to-even), with the residual 1 yen landing on one line.
floor(333 × 10/110) = floor(30.2727...) = 30 floor(1332 × 10/110) = floor(121.0909...) = 121
The OrderLineItemTax type field determines whether tax is embedded in the price or added on top:
| Type | What Square does | Japan usage |
|---|---|---|
INCLUSIVE (税込) | Tax is already included in base_price_money. Square extracts the tax portion from the listed price. | Standard for B2C — prices displayed to consumers include tax by law. |
ADDITIVE (税抜) | Tax is added on top of base_price_money. Square calculates additional tax and adds it to the total. | Used for B2B — some businesses quote tax-exclusive prices. |
Side-by-side comparison — same item at ¥1,100 list price:
INCLUSIVE (税込): base_price_money = ¥1,100 Square extracts tax: floor(1100 × 10/110) = ¥100 gross_sales_money = ¥1,000 (tax-excluded amount) total_tax_money = ¥100 total_money = ¥1,100 (same as base — customer pays this) ADDITIVE (税抜): base_price_money = ¥1,000 Square adds tax: floor(1000 × 10/100) = ¥100 gross_sales_money = ¥1,000 (same as base) total_tax_money = ¥100 total_money = ¥1,100 (base + tax — customer pays this)
Key difference in response fields:
- INCLUSIVE -
gross_sales_money<base_price_money(Square deducts tax from gross). Deducting the tax portion fromgross_sales_moneyis the default behavior. Only AU, ES, FR, GB, and IE retain the inclusive amount in gross sales; Japan, US, Canada, and all other countries follow the default and the tax portion is deducted. - ADDITIVE -
gross_sales_money=base_price_money(no deduction).total_money= base + tax.
In both cases, the ORDER-scope bucket calculation logic is identical — Square sums the applicable amounts per rate, computes tax once, truncates once, and apportions back.
For the dual-rate scenario (10% standard + 8% reduced), you create two ORDER-scoped taxes and use pricing_blocklists on line items to control which tax applies to which item. Square then automatically computes each tax on only its applicable items.
Each OrderLineItem can have a pricing_blocklists field that prevents specific taxes or discounts from being applied to that item:
{ "pricing_blocklists": { "blocked_taxes": [ { "uid": "blocked-tax-entry", "tax_uid": "tax-8" } ] } }
Set tax_uid to the uid of the ORDER-scoped tax you want to block on that line item (the uid field is the blocklist entry's own identifier):
- Items subject to the 10% standard rate → set
tax_uidto the 8% tax'suid. - Items subject to the 8% reduced rate → set
tax_uidto the 10% tax'suid.
Square then computes each ORDER-scoped tax on the aggregate subtotal of only its non-blocked items — achieving per-rate-bucket calculation.
Note
ORDER-scoped taxes are also automatically excluded from line items where item_type is GIFT_CARD or where taxable is false, in addition to items blocked via pricing_blocklists.
Discounts support ORDER and LINE_ITEM scopes:
| Scope | What Square does |
|---|---|
ORDER | Square distributes the discount proportionally across all non-zero line items. |
LINE_ITEM | Square applies the discount only to specified line items. |
Both ORDER and LINE_ITEM scoped discounts produce a correct Japan Invoice System breakdown — the underlying tax math is the same. The difference is attachment: with ORDER scope, Square applies the discount to all applicable line items automatically; with LINE_ITEM scope, the caller specifies which lines the discount applies to via apply_discount_uids / applied_discounts.
When you submit an order with discounts and taxes, Square processes them in this sequence:
- Square applies all tax-basis-reducing discounts before tax (at ORDER scope).
- For both fixed and percentage discounts, Square computes the discount on the entire order subtotal.
- Square apportions the total discount back to individual lines (using banker's rounding — the same path as tax apportionment — with any residual 1 yen landing on one line so that line-level discounts sum exactly to the discount total).
- Square applies percentage discounts first, then fixed-amount discounts.
- Square builds tax-rate buckets from the discount-adjusted amounts.
- For each rate, Square sums the post-discount line amounts into one subtotal bucket.
- Square computes tax per bucket and truncates once.
- For each tax rate, Square multiplies the bucket subtotal by the rate and truncates once.
- This single tax value per rate bucket is the authoritative tax and matches the Japan "sum first, then tax once, then round once" rule.
- Square apportions each bucket's tax back to line items.
- Square splits each bucket's tax back to lines in proportion to their contribution.
- Per-line apportionment uses banker's rounding (round-half-to-even), not floor; any residual 1 yen lands on one line.
- Line-level 1-yen differences are allowed; per-rate tax totals and the final order total remain exact.
| Type | Field | Example |
|---|---|---|
| Fixed amount | amount_money | ¥500 off |
| Fixed percentage | percentage | 10% off |
Scenario: 2 items, both at the 10% standard rate, inclusive tax (税込). You set the tax-inclusive price in base_price_money.
Note
For INCLUSIVE tax in Japan, Square reports gross_sales_money as the tax-excluded amount (¥3,000 and ¥2,000), while base_price_money and total_money show the tax-inclusive price that the customer pays.
Scenario: ¥500 fixed discount on an order with 10% inclusive tax. Square applies the discount first, then computes tax on the discounted subtotal.
Note
With INCLUSIVE tax, total_money per line is the amount the customer pays for that line (post-discount, tax-inclusive). For item-1: ¥3,300 base − ¥375 discount = ¥2,925 (customer pays this; ¥266 of tax is embedded within). Square recalculates tax on the post-discount subtotal — the discount reduces both the net revenue and the tax proportionally.
Scenario: Reproducing the partner's test case — ¥333 × 2 + ¥666 with 10% inclusive tax. This example demonstrates why ORDER scope produces a different (and correct) total tax than per-line-item calculation.
Note
The per-item tax amounts (¥60 and ¥61) differ from naive per-line calculation (¥60 and ¥60) because Square apportions the bucket total (¥121) back to lines. The 1-yen remainder lands on one item. The per-rate total (¥121) is what matters for Invoice System compliance — line-level variation is expected.
Scenario: A B2B order where prices are quoted tax-exclusive (税抜). You set the net price in base_price_money, and Square adds tax on top. The ORDER-scope bucket calculation works the same way.
Note
With ADDITIVE tax, gross_sales_money equals the base price total (no tax deduction), and total_money = gross + tax. Compare with INCLUSIVE where gross_sales_money is reduced by tax. The per-bucket calculation is the same: Square sums all applicable line amounts (¥61,665), applies 10% once (¥6,166), and apportions back. The 1-yen apportionment remainder lands on item-2 (¥1,667 — the bucket total of ¥6,166 minus item-1's floored share of ¥4,499 — rather than its own floored share of ¥1,666).
| Requirement | How to configure |
|---|---|
| Per-rate-bucket tax calculation | Set scope: ORDER on all taxes. |
| Multi-rate support (10% + 8%) | Create two ORDER-scoped taxes, use pricing_blocklists on each line item to block the inapplicable rate (see Multi-rate tax setup with blocklists). |
| Discount before tax | Set scope: ORDER on discounts. |
| Tax-inclusive pricing (B2C) | Set type: INCLUSIVE on taxes, put the tax-inclusive amount in base_price_money. |
| Tax-exclusive pricing (B2B) | Set type: ADDITIVE on taxes, put the net amount in base_price_money. |
| Behavior | Detail |
|---|---|
| JPY rounding = truncation | Square automatically uses floor for JPY — not configurable. |
| Per-bucket tax computation | Square sums applicable items per rate, applies tax once, truncates once. |
| Apportionment | Square splits the bucket tax back to lines proportionally, assigning any 1-yen remainder to one line. |
| Discount-before-tax ordering | Square applies percentage discounts first, then fixed-amount discounts, before computing tax. |
| Invoice System compliance | With ORDER scope, per-rate totals are exact. Line-level 1-yen variation due to apportionment is expected and compliant. |
- Scope is immutable - Once a tax or discount is created with a scope, it cannot be changed. To change scope, delete and recreate the tax/discount.
- ORDER-scoped auto-application - When you create an ORDER-scoped tax, Square automatically generates
applied_taxesreferences on all non-blocked line items. - INCLUSIVE tax in Japan - Square reports
gross_sales_moneyas the tax-excluded amount, whilebase_price_moneyandtotal_moneyinclude tax. - ADDITIVE tax in Japan - Square reports
gross_sales_moneyas the base amount (same as input), andtotal_moneyincludes the added tax.
- Orders API Overview
- Order Taxes — ORDER vs LINE_ITEM scope, apportionment
- Apply Taxes, Discounts, and Service Charges —
pricing_blocklistsfor controlling which items a tax applies to - Order Price Adjustments — Rounding rules (Bankers' Rounding default; JPY overrides to truncation)
- Order Discounts — Discount types and calculation order
- Create Orders — Full order creation guide
- CreateOrder API Reference
- Order Object Reference
- OrderLineItemTax Object Reference
- OrderLineItemDiscount Object Reference
- Catalog API Overview