Tax V1 Captured Facts

Tax v1 adds nullable tax-code, tax-profile, discount, and captured price fields so integrations can preserve facts from their source. These fields are supplied and read back in v1. They are not calculation inputs for a Jungle tax engine.

Captured Fact Semantics

• Product tax defaults, line-item tax codes, tax profiles, registrations, line discounts, line prices, line totals, and document totals are available only when the caller supplies them.
• Omitting a v1 tax or captured price field leaves it unset. Clearing a supported update field with null removes the value.
• Legacy fields such as Product.gst, Supplier.taxNumber, Supplier.gstRegistered, LineItem.auTaxApplied, LineItem.discountPercentage, LineItem.adjustments, LineItem.unitPrice, LineItem.subtotalPrice, LineItem.totalPrice, Order.priceTotal, PurchaseOrder.price, and PurchaseOrder.totalPrice keep their existing behavior.
• The API does not derive v1 captured fields from legacy fields. For example, LineItem.auTaxApplied: GST does not populate taxCode, and discountPercentage does not populate discountType.

Field Groups

Product:

• taxCodeSaleDefault
• taxCodePurchaseDefault

Line item and order line item:

• taxCode
• discountType
• unitPriceTaxExclusive
• unitPriceTaxInclusive
• unitDiscountAmount
• lineSubtotalTaxExclusive
• lineDiscountTotal
• lineTaxTotal
• lineTotalTaxInclusive

Order and purchase order:

• subtotalTaxExclusive
• discountTotal
• taxTotal
• totalTaxInclusive

Supplier, customer, company, and location:

• taxProfile

Tax profile:

• countryCode
• taxCodeSaleDefault
• taxCodePurchaseDefault
• registrations
• attributes

Tax profiles are read through their owning supplier, customer, company, or location. Use taxProfileSet with the owner typename and identifier to create or update that owner's profile.

Discount Validation

discountType is a captured line-level structure:

• Percent requires percent and rejects amount.
• Flat requires amount and rejects percent.

The API validates this shape and returns the accepted value. It does not allocate the discount across a document or derive line totals from it in v1.

Out Of Scope In V1

The following work is intentionally not part of v1:

• provider mappings such as TaxJar or Avalara mappings
• tax snapshot tables
• AU GST or other tax calculation engines
• rounding, discount allocation, inclusive/exclusive extraction, or tax total derivation
• provider payload generation
• document-level structured discount objects
• migration or backfill from existing tax, price, or discount fields

Compatibility Expectations

Existing product, order, purchase-order, supplier, customer, company, and location flows must continue to work when all v1 tax and captured price fields are omitted. In that case, the v1 fields should read back as null, while legacy fields should retain their existing values and calculations.