# Action required: Production Taxes API Refactor on March 28, 2026 **URL:** \ **Category:** Uncategorized\ **Tags:** breaking-change, econ-models, production-taxes\ **Created:** [March 20, 2026, 9:29pm UTC](https://forum.api.combocurve.com/t/action-required-production-taxes-api-refactor-on-march-28-2026/470 "2026-03-20T21:29:12Z")\ **Posts on this page:** 1\ **Page:** 1
**Author:** ![Angel\_Torres](https://yyz1.discourse-cdn.com/flex035/user_avatar/forum.api.combocurve.com/angel_torres/32/88_2.png) [@Angel\_Torres](https://forum.api.combocurve.com/u/Angel_Torres)\ **Post date:** [March 20, 2026, 9:29pm UTC](https://forum.api.combocurve.com/t/action-required-production-taxes-api-refactor-on-march-28-2026/470/1 "2026-03-20T21:29:12Z")
**Effective date: Saturday, March 28, 2026** We are releasing a breaking change to the Production Taxes econ model endpoints. If your integration reads or writes production taxes via the ComboCurve API, you will need to update your payloads before this date to avoid disruption. * * * ## What’s changing The production taxes schema has been redesigned from two separate top-level objects (`adValoremTax` and `severanceTax`) into a single unified structure under a `data` property. This new structure is row-based, giving you more granular control and a consistent pattern across all tax types. ### Old structure (deprecated after March 28) ```json { "adValoremTax": { "deductSeveranceTax": false, "shrinkageCondition": "shrunk", "calculation": "nri", "rateType": "gross_well_head", "rowsCalculationMethod": "non_monotonic", "rows": [...] }, "severanceTax": { "shrinkageCondition": "shrunk", "calculation": "nri", "rows": [...] } } ``` ### New structure (required after March 28) ```json { "data": { "state": "texas", "rows": [...] } } ``` * * * ## New schema overview | Field | Type | Required | Description | | --- | --- | --- | --- | | `data.state` | string | Yes | US state whose tax rules apply (e.g. `"texas"`, `"oklahoma"`) | | `data.rows` | array | Yes | Array of tax row objects (max 5,000) | Each row in `data.rows` represents a single tax entry: | Field | Type | Required | Description | | --- | --- | --- | --- | | `key` | string | Yes | Production stream: `oil`, `gas`, `ngl`, `drip_condensate`, `ad_valorem_tax` | | `category` | string | Yes | Tax category: `severance_tax`, `ad_val_tax`, or a PA impact fee variant | | `criteria` | string | Yes | Timing/rate basis: `entire_well_life`, `dates`, `offset_to_fpd`, `oil_rate`, etc. | | `period` | array | Yes\* | Schedule breakpoints (dates, months, or rates). \*Not provided for PA impact fee rows. | | `value` | array | Yes\* | Tax rates or amounts matching `period` length. \*Not provided for PA impact fee rows. | | `unit` | string | Yes\* | Unit for values: `pct_of_revenue`, `dollar_per_bbl`, `dollar_per_mcf`, `dollar_per_boe`, `dollar_per_month`. \*Not provided for PA impact fee rows. | | `calculation` | string | No | Working interest basis: `nri`, `wi`, `lease_nri`, etc. | | `shrinkageCondition` | string | Conditional | `"shrunk"` or `"unshrunk"`. Required when `unit` is `dollar_per_bbl` or `dollar_per_mcf`. | | `deductSeveranceTax` | boolean | No | Deduct severance tax before applying ad valorem rate. Only valid for `ad_val_tax`. | | `rateType` | string | No | `gross_well_head`, `gross_sales`, or `net_sales`. Only valid for rate-based criteria. | | `rateRowsCalculationMethod` | string | No | `monotonic` or `non_monotonic`. Only valid for rate-based criteria. | | `escalation` | string | No | Escalation model ID or `"none"`. | | `description` | string | No | Free-text annotation. Max 200 characters. | * * * ## Request payload example The following example creates a production taxes econ model for Texas with four rows: a flat severance tax on oil, a date-segmented severance tax on gas, a rate-based severance tax on NGL, and an ad valorem tax with a per-BOE rate. ```json { "name": "Texas Production Taxes - 2026", "data": { "state": "texas", "rows": [ { "key": "oil", "category": "severance_tax", "criteria": "entire_well_life", "period": ["Flat"], "value": [4.6], "unit": "pct_of_revenue", "calculation": "nri" }, { "key": "gas", "category": "severance_tax", "criteria": "dates", "period": ["2024-01-01", "2025-01-01"], "value": [7.5, 7.5], "unit": "pct_of_revenue", "shrinkageCondition": "unshrunk", "calculation": "nri", "escalation": "none" }, { "key": "ngl", "category": "severance_tax", "criteria": "oil_rate", "period": [3, 6, 9], "value": [7.5, 5.0, 2.5], "unit": "dollar_per_bbl", "shrinkageCondition": "unshrunk", "calculation": "nri", "rateType": "gross_well_head", "rateRowsCalculationMethod": "non_monotonic" }, { "key": "ad_valorem_tax", "category": "ad_val_tax", "criteria": "offset_to_fpd", "period": [20], "value": [100], "unit": "dollar_per_boe", "calculation": "nri", "deductSeveranceTax": false } ] } } ``` ### Pennsylvania Impact Fee example For PA impact fee rows (`pa_if_h_2021`, `pa_if_h_2022_2024`, `pa_if_v_2021`, `pa_if_v_2022_2024`), `period`, `value`, and `unit` must **not** be included: ```json { "key": "ad_valorem_tax", "category": "pa_if_h_2022_2024", "criteria": "spud_date_from_headers" } ``` * * * ## Supported states `custom`, `alaska`, `alabama`, `arkansas`, `arizona`, `california`, `colorado`, `florida`, `idaho`, `indiana`, `kansas`, `kentucky`, `louisiana`, `maryland`, `michigan`, `mississippi`, `montana`, `north_dakota`, `nebraska`, `new_mexico`, `nevada`, `new_york`, `ohio`, `oklahoma`, `oregon`, `pennsylvania`, `south_dakota`, `tennessee`, `texas`, `utah`, `virginia`, `west_virginia`, `wyoming` * * * ## Action required - **Review your integration** for any calls to the production taxes econ model endpoints (both the standalone econ model route and the project-scoped route). - **Update your request payloads** to use the new `data.state` + `data.rows` structure before **March 28, 2026**. - **Check key/category/unit constraints** — not all combinations are valid. Refer to the updated API documentation for the full constraint tables. If you have questions or need help migrating your payloads, please reply to this thread or reach out to our support team.