Class TaxHooks

TopLevel.Object
- dw.order.hooks.TaxHooks

This interface represents tax extension points for Commerce App tax providers.

These hooks provide integration points for external tax calculation services installed via the Commerce App framework. They are distinct from the legacy dw.order.calculateTax extension point.

IMPORTANT: These hooks should only be implemented and registered by Commerce Apps (applications installed via the Commerce App framework with a CAP file). They are not intended for custom merchant cartridges or storefront implementations. Merchants who want custom tax calculation logic should use the legacy dw.order.calculateTax extension point instead.

Hook Registration A function must be defined inside a JavaScript source and must be exported. The script with the exported hook function must be located inside a site cartridge. Inside the site cartridge a package.json file with a ‘hooks’ entry must exist:

The hooks entry links to a JSON file, relative to the package.json file. This file lists all registered hooks inside the hooks property:

A hook entry has a name and a script property:

The namecontains the extension point name (the hook name).
The scriptcontains the script path relative to the hooks file, with the exported hook function.

Function Naming Convention: The exported JavaScript function name must match the last segment of the extension point name, for example, calculate, commit, cancel..

Order Lifecycle Context Each hook fires at a specific point in the order lifecycle:

**calculate:**Fires during basket calculation on every basket operation (e.g., adding items, changing quantities, updating shipping). Calculates tax amounts for the basket line items.
**commit:**Fires immediately after successful order creation (order status CREATED). Notifies the tax provider that the order has been created and tax amounts should be committed.
**cancel:**Fires on order cancellation or failure. Notifies the tax provider to void or cancel previously committed tax amounts.

Hook Precedence

When sfcc.app.tax.calculateis registered, it takes precedence over the legacy dw.order.calculateTaxhook.
If the Commerce App hook is not registered, the platform falls back to dw.order.calculateTax(if registered).
If neither hook is available, the platform uses default platform tax calculation.

Important: If you override the dw.order.calculate hook (the parent basket calculation hook), the platform’s tax hook selection logic is bypassed entirely. In this case, if you want to use Commerce App tax providers, you must manually invoke the sfcc.app.tax.calculate hook from within your custom dw.order.calculate implementation.

SCAPI Behavior

SCAPI requests with ScapiHookExecutionEnabled disabled bypass all hooks (both Commerce App tax hooks and the legacy dw.order.calculateTax hook) and go straight to the default platform tax calculation.

Hook Arguments and Return Types

**calculate:**Receives a dw.order.LineItemCtnr(typically a dw.order.Basket) as the first argument. Must return a dw.system.Statusobject (or nullfor success).
**commit:**Receives a dw.order.Orderobject as the first argument. Must return a dw.system.Statusobject (or nullfor success).
**cancel:**Receives a dw.order.Orderobject as the first argument. Must return a dw.system.Statusobject (or nullfor success).

Error Handling For calculate hook:

**Always blocks on error:**Both returning a Status.ERRORand throwing an exception prevent the basket calculation from completing successfully. The platform logs the error and halts the current basket operation. Since order creation requires a successful basket calculation, this also prevents orders from being created with incorrect tax amounts.

For commit hook:

The Commerce App developer chooses whether errors should block order creation by how they handle errors in their hook implementation:

**Non-blocking error:**Catch exceptions and return a Status.ERROR. The platform logs the error as a warning and continues with the order lifecycle. Use this when the tax provider is temporarily unavailable but the order should still be created.
**Blocking error:**Let exceptions propagate (don’t catch them). The platform logs the error and rolls back the order lifecycle operation, preventing the order from being created.

For cancel hook:

The Commerce App developer chooses whether errors should block order cancellation by how they handle errors in their hook implementation:

**Non-blocking error:**Catch exceptions and return a Status.ERROR. The platform logs the error as a warning and continues with the order lifecycle. Use this when the tax provider is temporarily unavailable but the order cancellation should still proceed.
**Blocking error:**Let exceptions propagate (don’t catch them). The platform logs the error and rolls back the order cancellation operation.

Constant	Description
extensionPointAppCalculateTax: String = “sfcc.app.tax.calculate”	The extension point name sfcc.app.tax.calculate.
extensionPointAppCancelTax: String = “sfcc.app.tax.cancel”	The extension point name sfcc.app.tax.cancel.
extensionPointAppCommitTax: String = “sfcc.app.tax.commit”	The extension point name sfcc.app.tax.commit.

This class does not have a constructor, so you cannot create it directly.

Method	Description
calculate(LineItemCtnr)	The function is called by extension point extensionPointAppCalculateTax.
cancel(Order)	The function is called by extension point extensionPointAppCancelTax during OrderMgr.failOrder() or OrderMgr.cancelOrder().
commit(Order)	The function is called by extension point extensionPointAppCommitTax during order creation in the order creation transaction.

assign, create, create, defineProperties, defineProperty, entries, freeze, fromEntries, getOwnPropertyDescriptor, getOwnPropertyNames, getOwnPropertySymbols, getPrototypeOf, hasOwnProperty, is, isExtensible, isFrozen, isPrototypeOf, isSealed, keys, preventExtensions, propertyIsEnumerable, seal, setPrototypeOf, toLocaleString, toString, valueOf, values

extensionPointAppCalculateTax: String = "sfcc.app.tax.calculate": The extension point name sfcc.app.tax.calculate.

extensionPointAppCancelTax: String = "sfcc.app.tax.cancel": The extension point name sfcc.app.tax.cancel.

extensionPointAppCommitTax: String = "sfcc.app.tax.commit": The extension point name sfcc.app.tax.commit.

calculate(lineItemCtnr: LineItemCtnr): Status

The function is called by extension point extensionPointAppCalculateTax. It calculates tax amounts for the basket line items during basket calculation. This hook fires on every basket operation (e.g., adding items, changing quantities, updating shipping), not only before order creation.

Note: If the dw.order.calculate hook is overridden, the platform's automatic tax hook selection is bypassed. You must manually invoke this hook from within your custom dw.order.calculate implementation if you want to use Commerce App tax providers.

Error Handling: Both returning a Status.ERROR and throwing an exception will prevent the basket calculation from completing successfully. The platform logs the error and halts the current basket operation. Since order creation requires a successful basket calculation, this also prevents orders from being created with incorrect tax amounts.

SCAPI Behavior: When ScapiHookExecutionEnabled is disabled, SCAPI requests bypass this hook and use default platform tax calculation.

Sample Implementation:

Common APIs used: dw.order.TaxMgr (setProductLineTax, setShippingTax), dw.net.HTTPClient, dw.order.LineItemCtnr (getProductLineItems, getShipments), dw.order.ProductLineItem (getProductID, getTaxClassID), dw.order.OrderAddress (getAddress1, getCity, getStateCode).

Parameters:

lineItemCtnr - the line item container (basket) for which tax should be calculated.

Returns:

Status.OK or null for success; Status.ERROR to block the basket calculation with details about the failure. Throwing an exception will also block the basket calculation.

cancel(order: Order): Status

The function is called by extension point extensionPointAppCancelTax during OrderMgr.failOrder() or OrderMgr.cancelOrder(). It notifies the Commerce App tax provider that the order has been cancelled or has failed, and that previously committed tax amounts should be voided or cancelled in the tax provider.

Error Handling:

**Non-blocking error:**Return Status.ERROR. The platform logs the error as a warning and continues with the order lifecycle. Use this when the tax provider is temporarily unavailable but the order cancellation should still proceed.
**Blocking error:**Throw an exception. The platform logs the error and rolls back the order lifecycle operation.

SCAPI Behavior: When ScapiHookExecutionEnabled is disabled, SCAPI requests bypass this hook.

Sample Implementation:

Common APIs used: dw.net.HTTPClient, dw.order.Order (getOrderNo, custom attributes), dw.system.Status.

Parameters:

order - the order that has been cancelled and for which tax should be voided.

Returns:

Status.OK or null for success; Status.ERROR to log a warning without blocking the order cancellation. Throwing an exception will roll back the order cancellation operation.

commit(order: Order): Status

The function is called by extension point extensionPointAppCommitTax during order creation in the order creation transaction. It notifies the Commerce App tax provider that the order has been successfully created and that tax amounts should be committed to the tax provider. The order is in CREATED status at this point (before being placed).

Error Handling:

**Non-blocking error:**Return Status.ERROR. The platform logs the error as a warning and continues with the order lifecycle. Use this when the tax provider is temporarily unavailable but the order should still be created.
**Blocking error:**Throw an exception. The platform logs the error and rolls back the order lifecycle operation, preventing the order from being created.

SCAPI Behavior: When ScapiHookExecutionEnabled is disabled, SCAPI requests bypass this hook.

Sample Implementation:

Common APIs used: dw.system.Transaction, dw.net.HTTPClient, dw.order.Order (getOrderNo, getProductLineItems, getDefaultShipment, custom attributes), dw.order.ProductLineItem (getAdjustedTax).

Parameters:

order - the order that has been created and for which tax should be committed.

Returns:

Status.OK or null for success; Status.ERROR to log a warning without blocking the order. Throwing an exception will roll back the order creation.