Instance · Ecommerce
Product Schema
Last updated 1 November 2026
This page documents how pricing and tax fields are stored on the Ecommerce product and product_variant schemas, and how the platform resolves the final price.
Tax handling on products
Each product and variant records how its price was entered so the platform can always resolve the correct net price and tax. The key field is is_tax_included.
is_tax_included is an entry convention, not a display setting. It tells the platform whether the figure entered against the product already includes tax.
Fields
| Field | Type | Purpose |
|---|---|---|
regular_price | number | The price entered for the product |
sale_price | number | The sale price, when on sale |
tax_amount | number | Tax rate (percentage) or a fixed tax figure |
is_fixed_tax_amount | boolean | Treat tax_amount as a fixed figure, not a percentage |
is_tax_included | boolean | Whether the entered regular price already includes tax |
is_sale_price_tax_included | boolean | Whether the entered sale price already includes tax |
is_on_sale | boolean | Whether the sale price is the active price |
On product_variant the sale price flag is named is_variant_sale_price_tax_included. The product schema keeps is_sale_price_tax_included.
How the price is resolved
On a product, when is_on_sale is true the platform uses sale_price and is_sale_price_tax_included. Otherwise it uses regular_price and is_tax_included.
is_tax_included = true (entered figure is gross):
- net = price / (1 + tax_amount / 100)
- tax = net × (tax_amount / 100)
- total = net + tax
is_tax_included = false (entered figure is net):
- net = price
- tax = net × (tax_amount / 100)
- total = net + tax
When is_fixed_tax_amount is true, tax_amount is used directly instead of a percentage.
Worked example
| Entered price | is_tax_included | Rate | Net | Tax | Total |
|---|---|---|---|---|---|
| 99 | true | 10% | 90 | 9 | 99 |
| 90 | false | 10% | 90 | 9 | 99 |
Both rows resolve to the same net, tax, and total.
Why the flag is per product
Pricing data often arrives in different conventions across supplier feeds and imports. Setting the convention per product lets merchants enter prices as the data arrives, while the platform normalises everything to consistent net, tax, and total values. For consistent storefront display, enter prices on a consistent basis across the catalogue.