Monitor tax processors

Commerce uses a fallback method for calculating taxes when it cannot connect to your tax processor’s web service in the event of an outage.

The fallback tax logic automatically applies a default tax rate (that you set with the Admin API) to all orders if a specified number of calls to the tax processor fail within a specified time span. This prevents errors at the tax calculation step of order processing and allows orders to progress to the payment processing step.

Note: During the initial configuration of your environment, Oracle sets certain settings that trigger the fallback tax calculation, including the number of consecutive failed tax calls, the time span over which to count failed tax calls, and the time period after which Commerce should try calling the tax processor’s service again.

Commerce uses the fallback logic to calculate taxes only when calls to the tax processor fail. That is, when the tax processor’s web service responds to a call with a 500-level status code. Fallback tax calculation is not used when any other type of response is received. For example, if your Commerce tax settings contain the wrong postal code for your tax nexus, the tax processor will reply with an error, but that error will not trigger fallback tax calculation logic.

Set the default tax rate

You use the Commerce Admin API to set the defaultTaxRate property, an integer that specifies the tax rate to apply when fallback tax processing is used. The default value for defaultTaxRate is 0, which means that no tax is charged. However, you could set it to a rate that is higher than any jurisdiction where your store charges tax. The default tax rate is applied to all prices in an order, including shipping costs.

Note: During the initial configuration of your environment, Oracle sets certain settings that trigger the fallback tax calculation, including the number of consecutive failed tax calls, the time span over which to count failed tax calls, and the time period after which Commerce should try calling the tax processor’s service again. You cannot change these settings. If you find that the settings are not appropriate for your store, you can file a support ticket and to change the settings. For example, if orders are failing at the tax processing step, it might be appropriate to allow fewer failed calls over a shorter time span.

To set the defaultTaxRate property, issue a PUT request to one of the following endpoints:

• /ccadmin/v1/taxProcessors/vertex-p if your tax processor is Vertex O Series
• /ccadmin/v1/taxProcessors/ava-p if your tax processor is Avalara AvaTax

The following example shows a PUT request that sets the default tax rate for a store that uses Avalara AvaTax to process taxes. When the fallback logic indicates that the AvaTax web service is down, Commerce stops making calls to it and automatically applies a tax rate of 10% to all orders.

PUT /ccadmin/v1/taxProcessors/ava-p HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access_token>

{
   "type":"avalara",
   "url": "<dedicated_host_instance_url>",
   "defaultTaxRate": 10,
}

Disable fallback tax calculation

The fallback tax calculation settings are enabled by default, but you can disable them. If you disable fallback tax calculation and Commerce cannot reach your tax processor’s web service, for example in the case of an outage, shoppers will see an error during checkout and will not be able to complete their orders.

You use the Commerce Admin API to set the fallbackEnabled property, a Boolean that specifies whether fallback tax processing is used. The default value for fallbackEnabled is true.

To set this property, issue a PUT request to one of the following endpoints:

• /ccadmin/v1/taxProcessors/vertex-p if your tax processor is Vertex O Series
• /ccadmin/v1/taxProcessors/ava-p if your tax processor is Avalara AvaTax

The following example shows a PUT request that disables fallback tax processing for a store that uses Avalara AvaTax to process taxes.

PUT /ccadmin/v1/taxProcessors/ava-p HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access_token>

{
   "type":"avalara",
   "url": "<dedicated_host_instance_url>",
   "fallbackEnabled": false,
}

Track fallback tax calculation on orders

A Boolean property on Commerce order objects, TaxCalculated, indicates how tax was calculated for the order:

• If the value of TaxCalculated is true, tax was calculated normally by your specified tax processor.
• If the value of TaxCalculated is false, the default tax rate you set was applied to the order.

This property is also included in the data Commerce sends in the Order Submit webhook. You can use this information to identify orders to which the default tax rate was applied so you can decide how to handle them in your order management system.