Tax Extension

br.dev.bcp.shopping.tax extends checkout and order.

Overview

This extension carries the Brazilian tax breakdown in the transaction: tax type, rate, calculation base, amount, destination authority, and product fiscal classification (NCM) per line item.

The tax type vocabulary is intentionally open. Brazil's 2026-2033 tax reform changes the mix over time, with ICMS, ISS, and DIFAL transitioning out and IBS, CBS, and IS transitioning in. A closed enum would require schema changes at each phase.

The authority field exposes the federative level funded by each tax (federal, state, municipal, and subnational for shared taxes such as IBS). This supports consumer price-transparency requirements and future split payment flows.

Discovery

{
  "capabilities": {
    "br.dev.bcp.shopping.tax": [
      {
        "version": "2026-07-14",
        "extends": ["br.dev.bcp.shopping.checkout", "br.dev.bcp.shopping.order"],
        "spec": "https://bcp.dev.br/2026-07-14/specification/tax",
        "schema": "https://bcp.dev.br/2026-07-14/schemas/shopping/tax.json"
      }
    ]
  }
}

The capability does not declare profile config. Tax calculation runs behind a seller-side tax calculation port; the seller's tax regime is an identity or AgentFacts concern, not a tax capability setting.

Schema Composition

• checkout.line_items[] and order.line_items[] are extended with ncm and taxes[].
• Aggregated tax totals use the existing tax total category.
• Schema: schemas/shopping/tax.json.

Fields

tax_detail entries in line_item.taxes[]

Field	Type	Required	Description
type	open string	Yes	Well-known values include icms, iss, difal, ibs, cbs, and is.
rate	number	No	Applied rate as a decimal fraction, such as 0.009 for 0.9%.
base	integer	No	Calculation base in minor currency units.
amount	integer	Yes	Tax amount in minor currency units.
authority	open string	No	Federative level funded by this tax.

New line item fields

Field	Type	Required	Description
ncm	string	No	Eight-digit Mercosur fiscal classification.
taxes	array of tax_detail	No	One entry per tax incidence.

Normative Rules

1. With this capability active, every checkout and order response MUST include at least one tax entry in totals with the approximate total tax amount.
2. Prices shown to consumers MUST already include taxes.
3. Clients MUST tolerate unknown tax type and authority values.

Example

Checkout response excerpt:

{
  "line_items": [
    {
      "id": "li_1",
      "item": { "id": "prod_1", "title": "Ceramic vase", "price": 10000 },
      "quantity": 1,
      "ncm": "69120000",
      "taxes": [
        { "type": "cbs", "rate": 0.009, "base": 10000, "amount": 90, "authority": "federal" },
        { "type": "ibs", "rate": 0.001, "base": 10000, "amount": 10, "authority": "subnational" }
      ],
      "totals": [{ "type": "subtotal", "amount": 10000 }]
    }
  ],
  "totals": [
    { "type": "subtotal", "amount": 10000 },
    { "type": "tax", "display_text": "Estimated taxes", "amount": 100 },
    { "type": "total", "amount": 10000 }
  ]
}