REST API v1 to v2 Code Changes Summary
Learn about code changes between the Vertex REST v1 API and the O Series 9.0 REST v2 API.
End of Support for Vertex Cloud REST APIs v1
As part of Vertex’s commitment to providing the best possible service and support, our team will be ending support of REST v1 endpoints after December 31, 2025.
We encourage you to transition to the latest version of our API to continue receiving the best possible support and to take advantage of new features and improvements. Note that, after December 31, 2025, Vertex will no longer provide support, updates, or bug fixes for REST v1.
In addition to this summary, we have prepared the Vertex® Cloud Indirect Tax RESTful API v1 to v2 Code Changes Guide to lead you through the process. There are field changes between REST v1 and REST v2 that must be made for continuity in the flow of your integration. The guide highlights the before and after values of fields that have changed. You can use the guide to find and replace the values you are using in your integration.
If you have questions about this change, contact Vertex Customer Support via Vertex Community.
Authentication changes
Identity provider
VERX IDP is now available as an identity provider for API credentials in O Series Cloud. VERX IDP is the Vertex-recommended Open Authorization (OAuth) identity provider (IDP) for O Series. Select this IDP when creating an API credential to take advantage of OAuth capabilities, including token caching.
The Legacy IDP is deprecated and will be shut down in September 2025. If you are currently using the Legacy IDP, you need to start using the VERX IDP before this date. When the Legacy IDP is shut down, it will no longer create credentials.
API credentials in O Series Cloud cannot be modified. To change the identity provider for an API credential, you must create a new credential. See Authenticate O Series Cloud for details on creating credentials and for other O Series authentication tasks.
O Series Cloud endpoints
Dedicated endpoint URLs are added for O Series Cloud.
These REST v1 endpoint URLs are changed:
| Vertex Cloud REST v1 endpoint | Endpoint URL |
|---|---|
| Authorization | https://auth.vertexsmb.com/identity/connect/token |
| Sales calculation | https://restconnect.vertexsmb.com/vertex-restapi/v1/sale |
| Purchase calculation | https://restconnect.vertexsmb.com/vertex-restapi/v1/purchase |
| Address lookup | https://restconnect.vertexsmb.com/vertex-restapi/v1/addresslookup |
| Transaction adjustments | https://api.vertexsmb.com |
The following are the new REST v2 endpoint URLs for the O Series Cloud APIs:
| O Series Cloud REST v2 endpoint | O Series Cloud REST v2 endpoint URL |
|---|---|
| Authorization - VERX IDP | https://auth.vertexcloud.com/oauth/token |
| Authorization - Legacy IDP | https://auth.vertexsmb.com/identity/connect/token |
| Sales calculation | https://calcconnect.vertexsmb.com/vertex-ws/v2/supplies |
| Purchase calculation | https://calcconnect.vertexsmb.com/vertex-ws/v2/procurement |
| Address lookup | https://calcconnect.vertexsmb.com/vertex-ws/v2/address-lookup |
| Transaction adjustments | https://calcconnect.vertexsmb.com/vertex-ws/v2/transactions |
Parameters
These parameters are no longer required in the request body:
- Username
- Password
- Scope
These required REST v1 parameters are changed:
| Parameter name | Parameter definition | Data type |
|---|---|---|
client_id | The client ID provided by Vertex for the custom integration | String, required |
client_secret | The client secret provided by Vertex for the custom integration | String, required |
username | The username is the API key from Vertex Cloud for the client on whose behalf the calls will be made | String, required |
password | The password is the API password from Vertex Cloud for the client on whose behalf the calls will be made | String, required |
scope(Address Cleansing and Tax Calculation) | The scope for Address Cleansing and Tax Calculation is the string calc-rest-api | String, required |
scope(Adjustment File API) | The scope for the Adjustment File API is the string vtms-public-api openid profile | String, required |
grant_type | The grant type is the string password | String, required |
The following REST v2 parameters are now required:
| Rest v2 parameter name | Rest v2 parameter definition | Data type |
|---|---|---|
client_id | The client ID provided by Vertex for the custom integration | String, required |
client_secret | The client secret provided by Vertex for the custom integration | String, required |
grant_type | The grant type is the string client_credentials | String, required |
audience | The audience for the token, which is verx://migration-api | String, required |
Note:
Authentication parameters are subject to change. Always make parameter values configurable so they can be updated as needed to accommodate future changes.
For details on obtaining or using an access token, see:
Tax Area Lookup changes
Lookup response type
AddressLookupResponseType is renamed to TaxAreaLookupResponseType to align with the v2/coordinateslookup service response model.
Jurisdiction type
The jurisdictionLevel field is changed to jurisdictionType to align with the abstract JurisdictionLevel concept introduced in the configuration API (country, mainDivision, subDivision, city, and district).
Coordinates lookup
A new v2/coordinateslookup API is added for latitude and longitude lookups.
Purchase/Procurement calculation changes
Path element
The path element is changed from purchase to procurement to align with interface terminology and to better fit the range of supported transaction types.
Backward compatibility
All remaining O Series 7.0 fields, 8.0 fields, and new 9.0 fields are added.
Buyer
nexusIndicator and nexusReasonCode are changed to isTaxExempt and exemptionReasonCode.
Imposition type
The imposition type is changed from a primitive string to a structure object to support user-defined impositions and a new withholdingType field.
Overrides
jurisdictionOverrides is removed and replaced with the more explicit exemptOverrides, nonTaxableOverrides, and rateOverrides.
Market value
fairMarketValue is removed.
Jurisdiction type
impositionInclusions value is renamed to jurisdictionType.
Posting date
postingDate is removed at the line level because it is not in the domain API.
Vendors
exemptionCertificate, exemptionReasonCode, and isTaxExempt are removed.
For vendorCode, isBusinessIndicator is removed.
For vendorTaxes:
jurisdictionLevelfield is changed tojurisdictionTypeto align with the configuration API.- The unused
locationCustomsStatusfield is removed. vendorTaxesis removed from the response object.
Entity ID
All impositionId, impositionTypeId, and ruleId entity ID fields are changed from long to string.
Taxes
For taxes.jurisdiction, the jurisdictionLevel field is changed to jurisdictionType to align with the configuration API.
taxRuleId is renamed to calculationRuleId to be consistent with the configuration API.
Purchase message
To resolve an inconsistency in the v1 schema where request used purchaseMessageType but response used purchaseMessage, purchaseMessage is renamed to purchaseMessageType for the PurchaseResponseType object.
Sales/Supplies calculation changes
Path element
The path element is changed from sale to supplies to align with interface terminology and to better identify the range of supported transaction types.
Backward compatibility
All remaining O Series 7.0 fields, 8.0 fields, and new 9.0 fields are added.
Imposition type
The imposition type is changed from a primitive string to a structure object to support user-defined impositions and a new withholdingType field.
Jurisdiction type
impositionInclusionsvalue is renamed to jurisdictionTypeOverrides.
Posting date
postingDate is removed at the line level because it is not in the domain API.
Entity ID
All impositionId, impositionTypeId, and ruleId entity ID fields are changed from long to string.
Taxes
taxRuleId is renamed to calculationRuleId to be consistent with the configuration API.
Sale message
To resolve an inconsistency in the v1 schema where the request used saleMessageType but the response used saleMessage, saleMessage is renamed to SaleMessageType for the SaleResponseType object.
Other changes
Boolean
For Boolean type fields in the response, the v2 API always returns a value.
Tax type
IMPORT_VAT is removed because it is not in the domain API.
Tax structure
These new values are added:
- QUANTITY_TIERED
- QUANTITY_RATE_TIERED
- TIERED_MODIFIER
- QUANTITY_TIERED_MODIFIER
- QUANTITY_RATE_TIERED_MODIFIER
- QUANTITY_TIERED_FLAT
- TIERED_FLAT
- QUANTITY_RATE_TIERED_EQUIVALENT
Detailed changes
For a detailed list of all code changes displayed side-by-side for easy comparison, see this PDF: Vertex® Cloud Indirect Tax RESTful API v1 to v2 Code Changes Guide.
Updated 2 days ago