Adjustment File API


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

Process Flow

Submit File

  1. Customer’s tax application generates the adjustment file.
  2. Customer’s tax application submits the adjustment file to Vertex Cloud web API.
  3. Customer’s tax application retains the adjustment file unique identifier that is supplied by Vertex Cloud web API.
  4. Vertex Cloud receives and begins processing the adjustment file.

Check Status

  1. Using the adjustment file unique identifier, the customer’s tax application requests the file processing status from Vertex Cloud web API.
  2. Vertex Cloud web API reports that the adjustment file processing status is “In Progress”.
  3. Customer’s tax application requests the adjustment file processing status again from Vertex Cloud web API.
  4. Vertex Cloud’s web API reports that the adjustment file processing status is “Complete”.
  5. Customer’s tax application retains the success file unique identifier that is supplied by Vertex Cloud web API.
  6. Customer’s tax application retains the error file unique identifier that is supplied by Vertex Cloud API.

Get Report File(s)

  1. Using the success file unique identifier, customer’s tax application downloads the generated success report file.
  2. Using the error file unique identifier, customer’s tax application downloads the generated error report file.

Error Conditions

Adjustment file processing is unsuccessful

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.

Unauthorized access to Vertex web API

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.


Sales and Seller’s Use Tax

Quotation

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.

Uploading

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.

Definition

POST /public/1/adjustmentfiles/quotation/upload

Parameters

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.

Result

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"
    }
}

Invoice

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.

Definition

POST /public/1/adjustmentfiles/invoice/upload

Distribute Tax (Sales and Seller’s Use Tax)

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.

Definition

POST /public/1/adjustmentfiles/distributetax/upload

Returns Only (Sales and Seller’s Use Tax)

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.

Definition

POST /public/1/adjustmentfiles/returnsonlysales/upload


Consumer Use Tax (CUT)

Accrual

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.

Definition

POST /public/1/adjustmentfiles/accrual/upload

Parameters

Posting to the Accrual endpoint requires the transaction file in the Consumer Use Tax file format. The Authentication header must contain the AccessToken.

Assets/Goods Movement

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.

Definition

POST /public/1/adjustmentfiles/assetmovement/upload

Inventory Removal

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.

Definition

POST /public/1/adjustmentfiles/removal/upload

Purchase Order

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.

Definition

POST /public/1/adjustmentfiles/purchaseorder/upload

Distribute Tax (Consumer Use Tax)

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.

Definition

POST /public/1/adjustmentfiles/distributetaxprocurement/upload

Returns Only (Consumer Use Tax)

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.

Definition

POST /public/1/adjustmentfiles/returnsonlyuse/upload


Adjustment File Status

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.

Definition

GET /public/1/adjustmentfiles/{id:guid}/status

Parameter
Parameter Name Definition
Id The file unique identifier obtained from the upload response.

 

Result

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"
    }
}

File

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.

Download

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.

Definition

GET /public/1/files/{id:guid}/

Parameter
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.

 

Result

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).

 

Response Codes
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.

 

Validation Responses

Error: Missing Authorization Header.
Error: Unexpected Character.