diff --git a/docs/specification/catalog/index.md b/docs/specification/catalog/index.md index 4b3aec050..98dfb7441 100644 --- a/docs/specification/catalog/index.md +++ b/docs/specification/catalog/index.md @@ -189,7 +189,13 @@ Businesses determine market assignment—including currency—based on context signals. Price filter values are denominated in `context.currency`; when the presentment currency differs, businesses SHOULD convert before applying (see [Price Filter](search.md#price-filter)). Response prices include -explicit currency codes confirming the resolution. +explicit currency codes confirming the resolution. Where tax treatment +varies by market, `price_treatment.tax.inclusion` states whether the +amount includes tax as resolved for that market, so agents do not have +to infer it from the country. An absent field is equivalent to +`not_asserted`. Prices within a single product response **SHOULD** +share the same tax treatment. During checkout, the itemized `totals` +breakdown remains authoritative. When `context.eligibility` claims are present, Businesses that accept them **MAY** adjust `price` / `list_price` directly for strikethrough display and diff --git a/source/schemas/common/types/price.json b/source/schemas/common/types/price.json index d7b670789..160138f9f 100644 --- a/source/schemas/common/types/price.json +++ b/source/schemas/common/types/price.json @@ -17,6 +17,10 @@ "type": "string", "description": "ISO 4217 currency code (e.g., 'USD', 'EUR', 'GBP').", "pattern": "^[A-Z]{3}$" + }, + "price_treatment": { + "$ref": "price_treatment.json", + "description": "How the amount should be interpreted for display and downstream calculation. When omitted, treatment follows the resolved market." } } } diff --git a/source/schemas/common/types/price_treatment.json b/source/schemas/common/types/price_treatment.json new file mode 100644 index 000000000..c2a59a14d --- /dev/null +++ b/source/schemas/common/types/price_treatment.json @@ -0,0 +1,13 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://ucp.dev/schemas/common/types/price_treatment.json", + "title": "Price Treatment", + "description": "How a price amount should be interpreted for display and downstream calculation.", + "type": "object", + "properties": { + "tax": { + "$ref": "tax_treatment.json", + "description": "Tax treatment of the amount." + } + } +} diff --git a/source/schemas/common/types/tax_treatment.json b/source/schemas/common/types/tax_treatment.json new file mode 100644 index 000000000..9a54d2c1c --- /dev/null +++ b/source/schemas/common/types/tax_treatment.json @@ -0,0 +1,22 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://ucp.dev/schemas/common/types/tax_treatment.json", + "title": "Tax Treatment", + "description": "Tax treatment of a price amount.", + "type": "object", + "required": [ + "inclusion" + ], + "properties": { + "inclusion": { + "type": "string", + "enum": [ + "included", + "excluded", + "not_applicable", + "not_asserted" + ], + "description": "Whether the amount includes tax (e.g. VAT, GST) as resolved for the market. 'included': tax is part of the amount. 'excluded': tax is added downstream. 'not_applicable': no tax applies to this amount. 'not_asserted': equivalent to omitting the field." + } + } +}