From 3427e53d5993defc6c29c5b53ffa45b14b54cabc Mon Sep 17 00:00:00 2001 From: YanisMtcr Date: Thu, 6 Aug 2026 20:02:31 +0200 Subject: [PATCH 1/2] feat: add tax_included to the price type --- docs/specification/catalog/index.md | 4 +++- source/schemas/common/types/price.json | 4 ++++ 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/specification/catalog/index.md b/docs/specification/catalog/index.md index 4b3aec050..d94005c4e 100644 --- a/docs/specification/catalog/index.md +++ b/docs/specification/catalog/index.md @@ -189,7 +189,9 @@ 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, `tax_included` on a price states whether the amount is +tax-inclusive, so agents do not have to infer it from the country. 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..9ebaeb421 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}$" + }, + "tax_included": { + "type": "boolean", + "description": "Whether the amount includes tax (e.g. VAT, GST). When omitted, tax treatment is not asserted and follows the resolved market." } } } From 0572eb5c0b988be1712d60ea53e313de372ade93 Mon Sep 17 00:00:00 2001 From: YanisMtcr Date: Thu, 20 Aug 2026 19:55:52 +0200 Subject: [PATCH 2/2] feat: model tax inclusion as a price_treatment object Co-authored-by: Karan Goel --- docs/specification/catalog/index.md | 8 +++++-- source/schemas/common/types/price.json | 6 ++--- .../schemas/common/types/price_treatment.json | 13 +++++++++++ .../schemas/common/types/tax_treatment.json | 22 +++++++++++++++++++ 4 files changed, 44 insertions(+), 5 deletions(-) create mode 100644 source/schemas/common/types/price_treatment.json create mode 100644 source/schemas/common/types/tax_treatment.json diff --git a/docs/specification/catalog/index.md b/docs/specification/catalog/index.md index d94005c4e..98dfb7441 100644 --- a/docs/specification/catalog/index.md +++ b/docs/specification/catalog/index.md @@ -190,8 +190,12 @@ 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. Where tax treatment -varies by market, `tax_included` on a price states whether the amount is -tax-inclusive, so agents do not have to infer it from the country. +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 9ebaeb421..160138f9f 100644 --- a/source/schemas/common/types/price.json +++ b/source/schemas/common/types/price.json @@ -18,9 +18,9 @@ "description": "ISO 4217 currency code (e.g., 'USD', 'EUR', 'GBP').", "pattern": "^[A-Z]{3}$" }, - "tax_included": { - "type": "boolean", - "description": "Whether the amount includes tax (e.g. VAT, GST). When omitted, tax treatment is not asserted and follows the resolved market." + "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." + } + } +}