The Adjustment File API allows you to upload transactions or alter transactions already in the system. The API can be used as a standalone application or integrated as an automated solution to upload the adjustment file and download the success and error files.
Each O Series API endpoint requires distinct OAuth credentials to access the API. Be sure you have an appropriate credential to use this endpoint.
| API | Root URI |
|---|---|
| Security token | https://auth.vertexsmb.com |
| Adjustment files | https://api.vertexsmb.com |
The adjustment file might not be successfully processed due to data integrity, file type, etc. The Vertex Cloud web API reports an error condition status. The adjustment file can then be corrected and resubmitted.
Access to the Vertex web API is denied if the current access token is expired or if no access token was supplied when trying to access the API. A valid access token must be supplied with each request to the Vertex Cloud web API.
A Quotation adjustment file is used to estimate taxes on a proposed sale by the seller. A Quotation adjustment file does not post to any Vertex Cloud configured returns. The Quotation endpoint allows for the uploading of a Sales/Seller’s Use Tax Quotation type adjustment file.
The file using the Sales/Seller’s Use Tax template must be uploaded in the request body using the multi-part/form-data content type.
POST /public/1/adjustmentfiles/quotation/upload
Posting to the Quotation endpoint requires the transaction file in the Sales/Seller’s Use Tax file format. The Authentication header must contain the AccessToken.
The resulting file object is returned upon a successful call as a JSON object. This object has the following properties:
| Property | Definition |
|---|---|
| file | The object containing upload information. |
| file.id | Unique identifier of the uploaded file for future reference. |
Example:
{
"file": {
"id": "fe266003-2a06-4281-8c92-57351f9e269f"
}
}
An Invoice adjustment file is used to calculate tax at the time of shipping, billing, or invoicing from the seller’s perspective. The Invoice endpoint allows for the uploading of a Sales/Seller’s Use Tax Invoice type adjustment file.
POST /public/1/adjustmentfiles/invoice/upload
A Distribute Tax adjustment file is used to accept a combined total tax amount and distribute that tax to the appropriate jurisdictions. The Distribute Tax endpoint allows for the uploading of a Sales/Seller’s Use Tax Distribute Tax type adjustment file.
POST /public/1/adjustmentfiles/distributetax/upload
The Returns Only adjustment file allows users with a Returns Only subscription to upload bulk transactions. Uploaded transactions are transferred to the returns that were added to a company’s configuration. The Returns Only Sales endpoint allows for the uploading of a Sales/Seller’s Use Tax Returns Only type adjustment file.
POST /public/1/adjustmentfiles/returnsonlysales/upload
An Accrual adjustment file is used to calculate tax at the time of shipping, billing, or invoicing from the buyer’s perspective. The Accrual endpoint allows for the uploading of a Consumer Use Tax Accrual type adjustment file.
POST /public/1/adjustmentfiles/accrual/upload
Posting to the Accrual endpoint requires the transaction file in the Consumer Use Tax file format. The Authentication header must contain the AccessToken.
An Asset/Goods Movement adjustment file is used to calculate tax on movement of fixed assets from one tax jurisdiction to another. The Asset Movement endpoint allows for the uploading of a Consumer Use Tax Asset/Goods Movement type adjustment file.
POST /public/1/adjustmentfiles/assetmovement/upload
An Inventory Removal adjustment file is used to calculate consumer use tax when withdrawing inventory for a specific internal project or task. The InventoryRemoval endpoint allows for the uploading of a Consumer Use Tax Inventory Removal type adjustment file.
POST /public/1/adjustmentfiles/removal/upload
A Purchase Order adjustment file is used to estimate the tax on intended purchases made by the buyer. The PurchaseOrder endpoint allows for the uploading of a Consumer Use Tax Purchase Order type adjustment file.
POST /public/1/adjustmentfiles/purchaseorder/upload
A Distribute Tax adjustment file is used to accept a combined total tax amount and distributes that tax to the appropriate jurisdictions. The Distribute Tax Procurement endpoint allows for the uploading of a Consumer Use Tax Distribute Tax type adjustment file.
POST /public/1/adjustmentfiles/distributetaxprocurement/upload
The Returns Only adjustment file allows users with a Returns Only subscription to upload bulk transactions. Uploaded transactions are transferred to the returns that were added to a company’s configuration. The Returns Only Use endpoint allows for the uploading of a Consumer Use Tax Returns Only type adjustment file.
POST /public/1/adjustmentfiles/returnsonlyuse/upload
After a file is uploaded, a customer can inquire on the processing status to determine success or failure.The Adjustment File Status endpoint is used to issue status inquiries of previously uploaded adjustment files using any of the upload endpoints.
GET /public/1/adjustmentfiles/{id:guid}/status
| Parameter Name | Definition |
|---|---|
| Id | The file unique identifier obtained from the upload response. |
The resulting status object is returned upon a successful call as a JSON object. This object has the following properties:
| Property | Definition |
|---|---|
| status | The object containing processing information. |
| status.id | The status identifier: -98 – Permanent Error (did not complete due to errors) 2 – In Progress 3 – Complete (no error file available) 4 – Complete with Error (error file; may or may not have a success file) |
| status.message | Textual description of the status identifier. |
| reports | The object containing success/error report information. |
| reports.successFileId | The success report file unique identifier. |
| reports.errorFileId | The error report file unique identifier. |
Example: In progress
{
"status": {
"id": "2",
"message": "In Progress"
}
}
The File endpoint is used to retrieve adjustment files from the Vertex public API. These files can be the originally uploaded file or the success and/or error files if produced.
After a file is uploaded, a customer can download the file. Once a file is processed, a customer can download the resulting success and error reports.
GET /public/1/files/{id:guid}/
| Parameter Name | Definition |
|---|---|
| Id | Unique file identifier of the original adjustment file obtained from the upload response, or the unique file identifier of the success/error file obtained from a status inquiry. |
The response contains the raw contents of the requested file. Additional information can be obtained by inspecting the response headers.
| Header | Definition |
|---|---|
| Content-Length | Number of bytes in the file. |
| Content-Type | The format of the response content. (for example, application/octet-stream). |
| Content-Disposition | File name (for example. attachment; filename=Adjust-123.csv). |
| Status | Code | Title | Detail |
|---|---|---|---|
| 200 | Success | Success | The object was returned from a successful request. |
| 400 | Bad Request | Bad Request | The request is invalid and cannot be processed. |
| 401 | Unauthorized | Unauthorized | Authorization was denied for this request. |
| 403 | Forbidden | Forbidden | You do not have permission to access this resource. |
| 500 | Internal server error | Internal server error | The server encountered an internal server error on misconfiguration. |
Error: Missing Authorization Header.
Error: Unexpected Character.