Action required: Production Taxes API Refactor on March 28, 2026

, ,
1

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)

{
  "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)

{
  "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.

{
	"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:

{
	"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.