When the shopping cart is priced with a request to include tax pricing, the External Tax Calculator webhook sends a POST request to the URL you specified when you configured the webhook. (Typically this is the URL where your tax processor’s web service listens for requests.) The body of the request contains the complete order data in JSON format.
The following example shows the body of an External Tax Calculation webhook POST request from Oracle Commerce Cloud. The request body is a JSON representation of the order.
{
"shippingGroups" : [ {
"priceInfo" : {
"amount" : 59.96,
"total" : 84.96,
"shipping" : 25,
"shippingSurchargeValue" : 0,
"tax" : 0,
"subTotal" : 59.96,
"currencyCode" : "USD",
"totalWithoutTax" : 84.96
},
"discountInfo" : {
"orderDiscount" : 0,
"shippingDiscount" : 0,
"discountDescList" : [ ]
},
"shippingMethod" : {
"shippingTax" : 0,
"cost" : 25,
"taxCode" : "",
"value" : "priorityShippingMethod",
"shippingMethodDescription" : "Priority"
},
"shippingGroupId" : "sg140414",
"shippingAddress" : {
"lastName" : "Smith",
"country" : "US",
"address3" : "",
"address2" : "",
"city" : "Syracuse",
"prefix" : "",
"address1" : "101 TNT Drive",
"postalCode" : "13202",
"companyName" : "",
"jobTitle" : "",
"county" : "",
"suffix" : "",
"firstName" : "Jean",
"phoneNumber" : "555-555-1212",
"faxNumber" : "",
"alias" : "Home",
"middleName" : "",
"state" : "NY",
"email" : null
},
"items" : [ {
"unitPrice" : 14.99,
"quantity" : 4,
"productId" : "Product_1Ci",
"commerceId" : "ci1443367",
"rawTotalPrice" : 59.96,
"returnedQuantity" : 0,
"salePrice" : 0,
"detailedItemPriceInfo" : [ {
"discounted" : false,
"amount" : 59.96,
"quantity" : 4,
"tax" : 0,
"orderDiscountShare" : 0,
"detailedUnitPrice" : 14.99,
"currencyCode" : "USD"
} ],
"shippingSurchargeValue" : 0,
"discountAmount" : 0,
"catRefId" : "Sku_1Di",
"discountInfo" : [ ],
"price" : 59.96,
"onSale" : false,
"stateDetailsAsUser" : "The item has been initialized within the shipping group",
"listPrice" : 14.99,
"status" : "INITIAL"
} ]
} ],
"creationTime" : 1486073446086,
"isTaxIncluded" : true,
"orderId" : "o130414",
"profile" : {
"firstName" : "Jean",
"lastName" : "Smith",
"taxExempt" : false,
"receiveEmail" : "yes",
"id" : "se-570031",
"locale" : "en",
"email" : "home@example.com",
"daytimeTelephoneNumber" : ""
},
"orderStatus" : "Incomplete",
"creationDate" : "2017-02-02T22:10:46.086Z",
"orderProfileId" : "se-570031",
"callType" : "SalesOrder",
"priceInfo" : {
"amount" : 59.96,
"total" : 59.96,
"shipping" : 25,
"shippingSurchargeValue" : 0,
"tax" : 0,
"subTotal" : 59.96,
"currencyCode" : "USD",
"totalWithoutTax" : 59.96
},
"discountInfo" : {
"unclaimedCouponMultiPromotions" : { },
"orderCouponsMap" : { },
"orderDiscount" : 0,
"shippingDiscount" : 25,
"orderImplicitDiscountList" : [ ],
"unclaimedCouponsMap" : { },
"claimedCouponMultiPromotions" : { }
},
"shipFromAddress" : {
"country" : "US",
"lastName" : null,
"address3" : null,
"address2" : null,
"city" : "Cambridge",
"address1" : "1 main st",
"prefix" : null,
"postalCode" : "02142",
"county" : null,
"ownerId" : null,
"suffix" : null,
"firstName" : null,
"middleName" : null,
"state" : "MA"
},
"shoppingCart" : {
"numberOfItems" : 4,
"items" : [ {
"unitPrice" : 14.99,
"quantity" : 4,
"productId" : "Product_1Ci",
"rawTotalPrice" : 59.96,
"salePrice" : 0,
"detailedItemPriceInfo" : [ {
"discounted" : false,
"amount" : 59.96,
"quantity" : 4,
"tax" : 0,
"orderDiscountShare" : 0,
"detailedUnitPrice" : 14.99,
"currencyCode" : "USD"
} ],
"displayName" : "Liberty Heights",
"shippingSurchargeValue" : 0,
"giftWithPurchaseCommerceItemMarkers" : [ ],
"discountAmount" : 0,
"isItemValid" : true,
"taxCode" : null,
"catRefId" : "Sku_1Di",
"skuProperties" : [ {
"propertyType" : "sku-base",
"name" : "Name",
"id" : "displayName",
"value" : null
}, {
"propertyType" : "sku-base",
"name" : "Active",
"id" : "active",
"value" : true
}, {
"propertyType" : "sku-base",
"name" : "Id",
"id" : "id",
"value" : "Sku_1Di"
} ],
"discountInfo" : [ ],
"price" : 59.96,
"variant" : [ ],
"onSale" : false,
"id" : "ci13000413",
"listPrice" : 14.99
} ]
},
"giftWithPurchaseInfo" : [ ],
"shippingAddress" : {
"lastName" : "Smith",
"country" : "US",
"address3" : "",
"address2" : "",
"city" : "Syracuse",
"prefix" : "",
"address1" : "101 TNT Drive",
"postalCode" : "13202",
"companyName" : "",
"jobTitle" : "",
"county" : "",
"suffix" : "",
"firstName" : "Jean",
"phoneNumber" : "",
"faxNumber" : "",
"alias" : "Home",
"middleName" : "",
"state" : "NY",
"email" : null
}
}When you configure the webhook, you need to supply a URL for your tax processor’s web service and the username and password you use to log into your tax processor account. You must also configure the external tax calculator service to read the data, calculate the tax, and send a response that includes the tax. You can configure webhooks on the Commerce Cloud administration interface or with the REST Admin API. See Use Webhooks for more information.
The following example shows a sample JSON response sent from a tax processor. Notice that the response breaks the total tax down into several individual components (state, city, and commuter) for each item in the order, including shipping.
"response": {
{
"shippingGroups": [
{
"taxPriceInfo": {
"cityTax": 0,
"amount": 22.99,
"valueAddedTax": 0,
"countyTax": 0,
"isTaxIncluded": false,
"miscTax": 0,
"districtTax": 0,
"stateTax": 0,
"countryTax": 0
},
"priceInfo": {
"amount": 89.94,
"total": 114.94,
"shipping": 25,
"taxable": 89.94,
"shippingSurchargeValue": 0,
"tax": 22.988,
"subTotal": 89.94,
"currencyCode": "USD",
"totalWithoutTax": 91.95
},
"shippingMethod": {
"shippingTax": 0,
"cost": 25,
"taxable": 25,
"taxDetails": [
{
"jurisType": "state",
"rate": "0.2000",
"tax": 2.5,
"taxName": "state tax"
},
{
"jurisType": "city",
"tax": 2.5,
"taxName": "city tax"
},
{
"jurisType": "commuter",
"tax": 1,
"taxName": "commuter tax"
}
],
"rate": 0,
"tax": 5,
"taxCode": "",
"value": "twoDayShippingMethod",
"shippingMethodDescription": "Two Day"
},
"shippingGroupId": "sg70413",
"items": [
{
"unitPrice": 14.99,
"quantity": 6,
"productId": "Product_1Ci",
"commerceId" : "ci1443367",
"rawTotalPrice": 89.94,
"taxable": 89.94,
"taxDetails": [
{
"jurisType": "state",
"rate": "0.2000",
"tax": 8.994,
"taxName": "state tax"
},
{
"jurisType": "city",
"tax": 8.994,
"taxName": "city tax
},
{
"jurisType": "commuter",
"tax": 1.9879999999999995,
"taxName": "commuter tax"
}
],
"returnedQuantity": 0,
"salePrice": 0,
"shippingSurchargeValue": 0,
"discountAmount": 0,
"tax": 17.988,
"catRefId": "Sku_1Di",
"discountInfo": [],
"rate": 0,
"price": 89.94,
"onSale": false,
"stateDetailsAsUser": "The item has been initialized within the shipping group",
"listPrice": 14.99,
"status": "INITIAL"
}
]
}
],
"creationTime": 1475951869000,
"isTaxIncluded": false,
"orderId": "o60413",
"orderStatus": "Incomplete",
"creationDate": "2016-10-08T18:37:49.000Z",
"orderProfileId": "se-570031",
"taxDate": "02-02-2017",
"callType": "SalesOrder",
"status": "success",
"timestamp": "2017-02-02T00:57:25.017"
}
}If the tax processor cannot calculate the tax based on the information in the POST request, it returns an error response. The following example shows a sample JSON error response sent from a tax processor for an order that contains an invalid shipping address.
{
"response": {
"status": "error",
"errors": [
{
"errorCode": 100123,
"description": "No taxing jurisdiction found.
Please check the address"}
]
}
}
