Skip to content

Tax Data Retrieval: Implementation Details

Some countries, like the United States or Canada, have very complex sales tax rules that are difficult to manage. JustOn allows for retrieving tax data from an external tax provider.

Info

The tax data retrieval is available as of JustOn 2.43.

Since tax providers are usually not free of charge, the tax data is retrieved automatically only when an invoice is finalized. It is also possible to retrieve draft tax data for draft invoices on demand, but this may involve additional costs, depending on the external tax provider. Also, the finalize process ignores draft tax data and retrieves the actual tax data to guarantee correct invoices. This is why draft invoices may not show the actual tax information.

Invoice Data Fields

The following fields on the Invoice object hold external tax provider information:

Field API Name Description
External Tax Status TaxStatus__c The status of the external tax provider
External Tax Provider Error TaxError__c Contains error messages that happened during communication with the external tax provider

Tax Data Processing on Invoice Finalization

When an invoice is finalized, the actual tax data for the invoice is retrieved. Any existing tax details of the invoice line items are replaced with new records.

The tax retrieval is done in two steps.

Step 1: Prior to the Finalization

Retrieves the actual tax data that will be used to finalize the invoice.

Actions

  • Retrieves the actual tax data and updates the invoice
  • Replaces existing tax details of the invoice line items
  • Sets the tax retrieval status to Draft

Error Handling

  • The invoice is not finalized
  • The field TaxStatus__c is unchanged
  • An error message is written to the TaxError__c field

Step 2: After the Finalization

Updates the external tax provider with the final invoice data. The tax data of the invoice is not modified. The tax retrieval status is set to Final.

Info

This step is not required for JustOn, but may be necessary when using further features of the tax provider. If this step fails, it can be fixed using the External Tax Provider button in the JustOn invoices list view.

Actions

  • Sends the actual invoice data to the tax provider
  • Sets the tax retrieval status to Final

Error Handling

  • The invoice is finalized
  • The tax retrieval status remains Draft
  • An error message is written to the TaxError__c field

Tax Data Processing With Cancellation Invoices

Info

With cancellation invoices, the behavior differs.

When a cancellation invoice is created (step 1 above), the tax data of the canceled invoice is used. The external tax provider is not called to retrieve tax data.

Depending on the external tax provider, some actions may be performed when a cancellation invoice is finalized (step 2 above). If AvaTax is used, for example, the AvaTax transaction for the canceled invoice is voided when the cancellation invoice is finalized.

In case of errors when finalizing a cancellation invoice:

  • The invoice is canceled
  • The tax retrieval status remains empty
  • An error message is written to the TaxError__c field