Release Notes
Important updates to the O Series REST APIs
For SaaS solutions, Vertex Release Notes communicate changes in behavior, enhancements, and features. In each release, Vertex also improves performance and quality and remediates security vulnerabilities. Release Notes are available on the Vertex Developer Network for all customers regardless of license. For specific information about a specific case, visit the Support section of Vertex Community or contact Customer Support.
O Series SR22 API Changes
New Tax Calculation API version
The Tax Calculation and Tax GIS RESTful API is updated to version 2.7.0.
JSON in the O Series Transaction Tester
In O Series, the Payload tab replaces the former XML tab in Transaction Tester and supports viewing calculation requests and responses in JSON (REST) format, alongside the existing XML (SOAP) option. You can now quickly access and share JSON payloads for REST API integrations, reducing manual effort and providing more precise results when testing transactions.
JSON support logging for the Tax Calculation API
The Tax Calculation and Tax GIS RESTful API now supports support logging for calculation requests. If you provide this attribute as part of your calculation requests, the API returns detailed logging results in your calculation request:
"applicationData": {
"messageLogging": {
"overrideLoggingThresholds": [
{
"logLevel": "SUPPORT"
}
],
"returnLogEntries": true
},
Logging results include full calculation details, situs logic, and response times. See Calculation API Requests for details.
New calculation fields
New fields and response values are added to calculation requests and responses in the Tax Calculation and Tax GIS RESTful API to support Conditional Procurement, Support logging for REST transactions, and tax calculation for Brazil. These changes impact tax calculation API requests and/or responses for sellers, buyers, and owners.
| Calculation API field | Calculation API field Description | Calculation API changes |
|---|---|---|
basisReductionPercentageOverride | double If basis reduction applies, this value (as a percentage) replaces the percentage of the original basis amount on which to calculate tax. This value must be between 0 and 100. | Added to the overridesarray in the pautaOverridesobject for requests and responses. |
considerDiscountOnTaxable | boolean Indicates to calculate tax based on the reduced basis amount. | Added to the overridesarray in the pautaOverridesobject for requests and responses. |
destinationRateOverride | boolean Adjusts the rate to the destination rate. When selected, the tax is calculated using the regular markup rate (MVA). | Added to the overridesarray in the pautaOverridesobject for requests and responses. |
icmsStLogicComparison | string The ICMS-ST Logic Comparison to use in Pauta calculations related to this imposition type. Applicable only when a Pauta Override is referencing the ICMS-ST imposition type. | Added to the overridesarray in the pautaOverridesobject for requests and responses. |
overrides | array of objects An array of override objects. | Added to the overridesarray in the pautaOverridesobject for requests and responses. |
pautaAmount | double The Pauta Amount to use in Pauta calculations related to this imposition type. | Added to the overridesarray in the pautaOverridesobject for requests and responses. |
pautaAdjustmentPercentage | double The percentage by which to change the Pauta value. This value must be between 0 and 100. | Added to the overridesarray in the pautaOverridesobject for requests and responses. |
pautaLockPercentage | double The maximum percentage allowed when changing the Pauta value, so changes do not exceed this cap. This value must be between 0 and 100. | Added to the overridesarray in the pautaOverridesobject for requests and responses. |
pautaOverride | The response object when a pautaOverride is applied to a calculation. | Added to the taxes element for responses. |
pautaOverrides | object One or more override arrays for Pauta calculation. | Added to the lineItems array for requests and responses |
pautaPmcAmount | double Specifies the Pauta PMC (Preço Médio ao Consumidor or Weighted Average Price to the Consumer), the maximum price to the final consumer set by the manufacturer and published in the CMED (Câmara de Regulação do Mercado de Medicamentos) list. | Added to the overridesarray in the pautaOverridesobject for requests and responses. |
pautaPmpfAmount | double Specifies the maximum price or Pauta PMPF (Preço Médio Ponderado ao Consumidor Final or Weighted Average Price to the Final Consumer) defined by the Brazilian tax authorities. | Added to the overridesarray in the pautaOverridesobject for requests and responses. |
quantityType | string enum- VOL- COMThe quantity type for a Pauta override. Pass VOL to calculate with quantity by volume. Pass COM to calculate with quantity by the number of units. | Added to the overridesarray in the pautaOverridesobject for requests and responses. |
strictPautaOverride | boolean Indicates whether the pautaAmount is a strict override. This will circumvent more complex Pauta calculations and use the provided amount directly in Pauta determination. | Added to the overridesarray in the pautaOverridesobject for requests and responses. |
taxableWithoutIPI | boolean Indicates whether the current pautaOverride is taxable without IPI. This can have an impact during Pauta determination for the associated imposition type. | Added to the overridesarray in the pautaOverridesobject for requests and responses. |
taxEvaluationActionResult | The action returned by the tax evaluation for a Conditional Procurement calculation. | Added at the transaction-level and to lineItems for calculation responses. |
taxEvaluationHoldReason | The reason returned why a Conditional Procurement calculation was flagged as HOLD. | Added at the transaction-level and to lineItems for calculation responses. |
taxEvaluationHoldFlag | Indicates whether the tax evaluation for a Conditional Procurement exceeds the hold threshold. | Added at the transaction-level and to lineItems for calculation responses. |
taxEvaluationResult | The results of a tax evaluation for a Conditional Procurement calculation. Possible values include: - Match- Undercharge- Overcharge- Zero Charged Tax- Delivered Duty Paid (DDP)- Reverse Charge (for Canada only) | Added at the transaction-level and to lineItems for calculation responses. |
Conditional Procurement message type
Note:
Conditional Procurement calculation is released for O Series calculation APIs. Additional configuration enhancements are planned for this feature in future releases. For O Series On-Premise deployments, Monthly Data Update (MDU) 266 or higher is required for Conditional Procurement calculation.
The Conditional Procurement message type is added to calculation requests and responses for buyers (Procurement) in the Tax Calculation and Tax GIS RESTful API. This new financial event allows you to process invoice verification and accrual in a single API call, eliminating the need for multiple calls with different message types.
A Conditional Procurement calculation evaluates the difference between Vendor Charged Tax (VCT) and O Series Calculated Tax (OCT), then it applies preconfigured decision rules to determine whether to accrue or distribute tax.
See Calculate Tax as a Buyer for details, including calculation scenarios.
Vertex Validator
New Tax Calculation API version
The Tax Calculation and Tax GIS RESTful API is updated to version 2.6.0.
New request fields to support Vertex Validator
Note
These fields are available only for Vertex Validator deployments.
New fields are added to calculation requests in the Tax Calculation and Tax GIS RESTful API to support Vertex Validator. These changes impact tax calculation API requests for sellers.
| Calculation API field | Calculation API field description | Calculation API changes |
|---|---|---|
cachedbKDx+bDnkcg= | boolean Boolean that indicates whether a cached validation was used or not. | Added to the validationResultobject |
cacheTimestamp | string If a cached value is returned, this field shows the time that the initial request was sent to the external service. | Added to the validationResultobject |
customerName | string A customer's name needs to be captured to be displayed on the invoice (when generated). It may also be required by an external validation service when validating tax registration. | Added to the customerobject |
isSyntaxValid | boolean Boolean that indicates whether the syntax is correct. | Added to the validationResultobject |
isValid | boolean Boolean that indicates if the Tax ID is valid or not. | Added to the validationResultobject |
taxNumberService | string An identifier for an external service responsible for validating the registration number. | Added to the validationResultobject |
taxRegistrationNumberNormalized | string The tax registration number in a normalized form that reflects the expected syntax. | Added to the validationResultobject |
validationInfo | string enumMore detailed information about the processing. Enum: - TAX_NUMBER_SERVICE_TEMPORARILY_UNAVAILABLE- TAX_NUMBER_VALIDATION_NOT_AVAILABLE- TAX_NUMBER_SYNTAX_VALID- TAX_NUMBER_SYNTAX_INVALID- TAX_NUMBER_SYNTAX_CONSIDERED_VALID_BUT_NOT_VERIFIED- TAX_NUMBER_VALID_ACCORDING_TO_EXTERNAL_SERVICE- TAX_NUMBER_INVALID_ACCORDING_TO_EXTERNAL_SERVICE | Added to the validationResultobject |
validationResult | object - isValid- isSyntaxValid- validationInfo- taxRegistrationNumberNormalized- cacheTimestamp- cached- taxNumberService | Added to the taxRegistrations array |
New response values to support Vertex Validator
New fields and response values are added to calculation responses in the Tax Calculation and Tax GIS RESTful API to support validation responses for Vertex Validator deployments. The changes impact tax calculation API responses for sellers.
O Series SR21 API Changes
New Tax Calculation API version
The Tax Calculation and Tax GIS RESTful API is updated to version 2.5.0.
Increased lookup range for coordinates
Lookups for Tax Area IDs using latitude and longitude coordinates are improved by increasing the date range of the lookups. The lookups now use data reaching back two years. O Series no longer returns Tax Area IDs that are not yet effective, avoiding associated calculation errors.
Jurisdiction ID added to override objects
To allow for more granularity when applying overrides to tax calculations, the Jurisdiction ID (jurisdictionId) field is added to override object arrays in the Tax Calculation and Tax GIS RESTful API. This change allows an override to be configured so it applies to a specific jurisdiction in O Series, while not applying to similar jurisdictions of the same Jurisdiction Level (jurisdictionType).
These override arrays now include the Jurisdiction ID (jurisdictionId) field:
- Citation Overrides (
citationOverrides) - Exemption Overrides (
exemptOverrides) - Imposition Types to Process (
impositionInclusions) - Nontaxable Overrides (
nonTaxableOverrides) - Rate Overrides (
rateOverrides) - Tax Deferred Percentage Overrides (
taxDeferredOverrides)
This change impacts calculation requests and responses for sellers, buyers, and owners.
New calculation fields to support Brazil calculations
New fields and response values are added to calculation requests and responses in the Tax Calculation and Tax GIS RESTful API to support tax calculation for Brazil. These changes impact tax calculation API requests and/or responses for sellers, buyers, and owners.
| Calculation API field | Calculation API field Description | Calculation API changes |
|---|---|---|
cfopTaxCode | The CFOP code returned by the Calculation Engine. Object - value- resultSource | Added to the taxes element for responses. |
cfopTaxCodeOverride | int32 0 to 9999Optional CFOP code at the line item level. When present, it overrides the Calculation Engine CFOP determination. | Added to the lineItems array for requests and responses. |
citation | string length between 1 and 512The citation value. This value references the legal document used to determine a tax rate. | Added for requests and responses: - To the transaction-level citationOverrides array- To the citationOverrides array in the lineItems array- To the taxes element for responses. |
citationOverrides | The array used to override the citation returned for an imposition during tax calculation. A citation references the legal document used to determine a tax rate. Array of objects [ - impositionType- jurisdictionType- citation- jurisdictionId] | Added as a transaction-level field and to the lineItems array for requests and responses. |
deferredTax | The deferred tax total returned for a transaction line. | Added to the taxes element for responses. |
informationOnly⚠️O Series On-Premise deployments must apply Monthly Data Update (MDU) 263 or later to configure the Information Only option for imposition types. | boolean Indicates whether the imposition type is information only. If true, the imposition type is not used to calculate tax totals, but is included to provide information about the transaction. | Added to theimpositionTypearray for requests and responses. |
resultSource | The source for the CFOP tax code value returned for a transaction line. | Added to the cfopTaxCode element for responses. |
taxDeferredFactor | double The factor that is used to calculate the deferred tax amount. The value is a decimal value that ranges from 0 to 1. For example, a value of 0.25 represents 25 percent. | Added for requests and responses: - To the taxDeferredOverrides array at the transaction level- To the taxDeferredOverrides array in the lineItems array |
taxDeferredOverrides | The array used to override deferred tax. Deferred tax is shown for informational purposes only and does not impact calculations. Array of objects [ - impositionType- jurisdictionType- taxDeferredFactor- jurisdictionId] | Added as a transaction-level field and to the lineItems array for requests and responses. |
taxDeferredPercentage | The percentage used to determine tax deferred totals that is returned by the Calculation Engine. | Added to the taxes element for responses. |
taxGovernRateReductionPercentage | The percentage value for the Govern Rate Reduction returned for a transaction line. | Added to the lineItems array for responses. |
totalDeferredTax | The total of deferred taxes returned for a calculation. | Added to responses. |
O Series SR20 API Changes
New Tax Calculation API version
The Tax Calculation and Tax GIS RESTful API is updated to version 2.4.0.
New message types and request for synchronization services
New message types and a new request are added to the Tax Calculation and Tax GIS RESTful API to initiate synchronization services for transactions. Synchronization services trigger financial events that modify your transactions in O Series so your financial host system and O Series show identical results.
Caution
Triggering synchronization services outside of the suggested time period can result in calculation errors or duplicate transactions:
- For On-Premise and On-Demand deployments, synchronization services must be triggered prior to initiating a Tax Journal Purge that includes impacted transactions.
- For Cloud deployments, synchronization services must be triggered within 90 days of tax calculation for impacted transactions.
This change impacts calculation requests and responses for sellers (Supplies) and buyers (Procurement).
| Message type or request | Endpoint | Purpose |
|---|---|---|
| ARBillingSync message type | /supplies | Modify existing Accounts Receivable transactions |
| APInvoiceSync message type | /procurement | Modify existing Accounts Payable transactions |
| APInvoiceSync message type | /procurement | Modify existing Accrual transactions |
| Rollback request | /transactions | Revert changes from previous synchronization events, restoring a transaction to its original state, prior to being modified |
New calculation fields to support 2026 Brazil tax reform
New fields and response values are added to calculation requests and responses in the Tax Calculation and Tax GIS RESTful API to support tax calculation for 2026 Brazil tax reform. These changes impact tax calculation API requests and/or responses for sellers, buyers, and owners.
| Field | Description | Changes |
|---|---|---|
additionalCommodityCode | object (CommodityCode)A standardized, unique code for the product or service. The commodityCodeType of this object must be different from the commodityCodeType of the CommodityCode object. | Added to thelineItemsarray for requests and responses |
buyerCondition | string [ 1 .. 40 ] charactersThe Buyer Condition is mandatory information for calculating taxes in Brazil. It represents the behavior of the entity that impacts tax calculation when buying goods or services. | Added for requests and responses: - As a transaction-level field - To the buyer object at the transaction level- To the buyer object in the lineItems array |
buyerCNAE | string [ 1 .. 40 ] charactersThe CNAE (National Classification of Economic Activities) five-digit numeric code that identifies optional information for calculating taxes in Brazil. This code: -Identifies what is being purchased by whom -Provides more granular information as compared to the Buyer Condition | Added for requests and responses: - As a transaction-level field - To the buyer object at the transaction level- To the buyer object in the lineItems array |
invoiceTextType | The text type of the invoice text applied to a transaction. | Added to the <InvoiceTexts> element in calculation responses for transactions with invoice text. |
InvoiceTotal | The sum of the Total Tax Included and Extended Price, which is the amount reported for the sale of services. This response value supports future functionality for tax calculation in Brazil. | Added to responses for the Quotation, Invoice, Purchase Order, and Invoice Verification message types. |
natureOfFiscalOperation | string [ 1 .. 40 ] charactersNatureOfFiscalOperation is mandatory information for calculating taxes in Brazil. A two-character alphabetical code that identifies the transaction type. | Added as a transaction-level field and to the lineItems array for requests and responses. |
sellerCondition | string [ 1 .. 40 ] charactersThe Seller Condition is mandatory information for calculating taxes in Brazil. It represents the behavior of the entity that impacts tax calculation when selling goods or services. | Added for requests and responses: - As a transaction-level field - To the seller object at the transaction level-To the seller object in the lineItems array |
sellerCNAE | string [ 1 .. 40 ] charactersThe CNAE (National Classification of Economic Activities) five-digit numeric code that identifies optional information for calculating taxes in Brazil. This code: -Identifies what is being sold by whom -Provides more granular information as compared to the Seller Condition | Added for requests and responses: - As a transaction-level field - To the seller object at the transaction level- To the seller object in the lineItems array |
taxCollectedFromParty | Identifies whether the buyer (BUYER) or the seller (SELLER) is responsible for tax collection. This response value supports future functionality for tax calculation in Brazil. | Added to the line-level Taxes element in responses for the Purchase Order message type. |
TaxRateReductionExempt | The amount of tax exempted by way of a Single Rate calculation tax rule with a rate reduction value. | Added to responses for calculations impacted by calculation tax rules with a Calculation Method set to Single Rate. |
TaxRateReductionPercentage | The rate reduction applied to a calculation via a Single Rate calculation tax rule. | Added to responses for calculations impacted by calculation tax rules with a Calculation Method set to Single Rate. |
TotalAcctPayAcctReceive | The Invoice Total less the Total Withheld, which is the amount paid to the supplier by the buyer. This response value supports future functionality for tax calculation in Brazil. | Added to responses for the Quotation, Invoice, Purchase Order, and Invoice Verification message types. |
TotalIncludedTax | The sum of all non-withholding (WHT) taxes, which is the amount the seller pays to the tax authorities. This response value supports future functionality for tax calculation in Brazil. | Added to responses for the Quotation, Invoice, Purchase Order, and Invoice Verification message types. |
TotalWHT | The sum of all withholding (WHT) taxes, which is the amount the buyer pays to the tax authorities. This response value supports future functionality for tax calculation in Brazil. | Added to responses for the Quotation, Invoice, Purchase Order, and Invoice Verification message types. |
Brazil Drivers added to Tax Configuration API
The O Series Tax Configuration API is updated with new Brazil Drivers. Requests and responses available via the /taxability-drivers endpoint are updated to support new taxability driver types for Brazil. These changes impact configuration requests and responses that:
- Create a Taxability Driver
- List Taxability Drivers
- Retrieve a Taxability Driver by ID
- Update a Taxability Driver
Correction - Audience for O Series Cloud authorization
Audience for O Series Cloud authorizationThe Audience parameter when authenticating O Series Cloud with the VERX IDP identity provider is verx://migration-api . This value is corrected for Authenticate O Series Cloud .
O Series SR19 API Changes
New field in the Calculation REST API
The Franchise Area Id (franchiseAreaId) field is added to Calculation API Requests and Responses in the Tax Calculation and Tax GIS RESTful API.
This change impacts calculation requests and responses for sellers, buyers, and owners. The new field is added at both the invoice level and the line level.
Updated 10 days ago