Shipping verification endpoints

Shipping verification endpoints

This section describes the APIs that are used for verifying compliance of alcoholic beverage transactions.

Parameters

The table below describes the parameters that are specified in the shipping verification request URLs.

ParameterDescription
companyCodeSpecify the code of the company that recorded this transaction.
transactionCodeSpecify the transaction code of the shipment that you want to verify.
documentTypeOptionally specify a document type of either SalesInvoice (default) or ReturnInvoice . This is required for ReturnInvoice transactions.

Verify shipment

The VerifyShipment endpoint is used to determine whether a beverage alcohol Sales Invoice transaction is compliant and can be shipped. AvaTax will look at the jurisdictions associated with each beverage alcohol line and validate the line's compliance against the rules in those jurisdictions. AvaTax will then return a response showing whether the transaction is compliant as well as any warning messages that help the integrator determine whether to make a different choice in the transaction. If the transaction is not compliant, thefailureMessages line will show the specific part(s) of the transaction that were not compliant.

AvaTax will take no other action with this transaction other than verifying compliance. This means that you still have to call the registration endpoint in order to get the volume recorded.

When verifying shipments for Return Invoices, be sure to includedocumentType=ReturnInvoice in the request URL as shown in the upcoming Refund purchase example. You will get a "Document not found" error if you omit this because the document type defaults toSalesInvoice.

Endpoint

GET /api/v2/companies/{companyCode}/transactions/{transactionCode}/shipment/verify

Request

curl
-X GET
-H 'Accept: application/json'
-H 'Authorization: Basic aHR0cHdhdQNoOmY='
-H 'Content-Type: application/json'
'https://sandbox-rest.avatax.com/api/v2/companies/DEFAULT/transactions/12343439084/shipment/verify'

Response

The response returns"compliant": true if the transaction is compliant, and thesuccessMessages describes how each check in the transaction passed compliance verification. If the transaction is not compliant, the response returns"compliant":false, and  thefailureMessages line in the response will describe the reason.

{
"compliant": true,
"warningCodes": [],
"message": "Transaction is compliant",
"successMessages": "Line \"1\": A current license exists for KENTUCKY; The recipient is older than 21 years of age; The purchaser is older than 21 years of age; The Per Individual volume limit in KENTUCKY is 90 Litre(s) per 1 month. Including registered shipments, 90 Litre(s) would be shipped to this Individual in a 1 month timeframe. Therefore, the volume in this transaction is under the volume limit.\n",
"failureMessages": "",
"failureCodes": [],
"lines": [
{
"resultCode": "Compliant",
"lineNumber": "1",
"message": "Line is compliant",
"successMessages": "A current license exists for KENTUCKY; The recipient is older than 21 years of age; The purchaser is older than 21 years of age; The Per Individual volume limit in KENTUCKY is 90 Litre(s) per 1 month. Including registered shipments, 90 Litre(s) would be shipped to this Individual in a 1 month timeframe. Therefore, the volume in this transaction is under the volume limit.",
"failureMessages": "",
"failureCodes": []
}
]
}

Register shipment

Use the RegisterShipment endpoint to tell AvaTax that a transaction has been verified and you want to commit it. Upon success, the transaction will get added to volume metrics on the AvaTax side. AvaTax will then add all of these registration transactions. In doing so, AvaTax will know that you shipped a certain amount of alcoholic beverages to a specific jurisdiction. This information is required for compliance verification.

This API can be used with both Sales Invoices and Return Invoices. And it is important to register return invoices in order to adjust volume metrics.

This API can be run multiple times against a single transaction. A best practice is to run this API for a transaction again if a previously registered transaction has been modified.

When running this API for Return Invoices, be sure to includedocumentType=ReturnInvoice in the request URL. You will get a "Document not found" error if you omit this because the document type defaults toSalesInvoice.

Endpoint

PUT /api/v2/companies/{companyCode}/transactions/{transactionCode}/shipment/registration

Request

curl
-X PUT
-H 'Accept: application/json'
-H 'Authorization: Basic aHR0cHdhdQNoOmY='
-H 'Content-Type: application/json'
'https://sandbox-rest.avatax.com/api/v2/companies/DEFAULT/transactions/123434390850/shipment/registration'

Response

The response will return 204 upon successful completion.

Register shipment if compliant

The RegisterShipmentIfCompliant endpoint is a combination of both the VerifyShipment and RegisterShipment endpoints. Run this to verify whether a transaction is compliant and then immediately commit that registration if it is compliant. You can use this method to avoid using both the VerifyShipment and RegisterShipment APIs.

When running this API for Return Invoices, be sure to includedocumentType=ReturnInvoice in the request URL. You will get a "Document not found" error if you omit this because the document type defaults toSalesInvoice.

Advice: Using this endpoint is not part of the recommended workflow. Instead, we recommend using the Verify endpoint followed by the Registration endpoint if the transaction is compliant.

Endpoint

PUT /api/v2/companies/{companyCode}/transactions/{transactionCode}/shipment/registerIfCompliant

Request

curl
-X PUT
-H 'Accept: application/json'
-H 'Authorization: Basic aHR0cHdhdQNoOmY='
-H 'Content-Type: application/json'
'https://sandbox-rest.avatax.com/api/v2/companies/DEFAULT/transactions/123434390845/shipment/registerIfCompliant'

Response

The response will return 204 upon successful completion.

Delete shipment registration

Use the DeleteShipmentRegistration endpoint to void a transaction that you previously registered. When running this API for Return Invoices, be sure to includedocumentType=ReturnInvoice in the request URL. You will get a "Document not found" error if you omit this because the document type defaults toSalesInvoice.

Endpoint

DELETE /api/v2/companies/{companyCode}/transactions/{transactionCode}/shipment/registration

Request

curl
-X DELETE
-H 'Accept: application/json'
-H 'Authorization: Basic aHR0cHdhdQNoOmY='
-H 'Content-Type: application/json'
'https://sandbox-rest.avatax.com/api/v2/companies/DEFAULT/transactions/123434390853/shipment/registration?documentType=ReturnInvoice'

Response

The response returns 204 upon successful completion.