US and Canadian Tax Calculation

The tax calculation service uses the same request to calculate US and Canadian sales tax due to their similarities, but there are some distinguishing factors that should be known.

US Sales Tax

Sales tax is imposed on a transfer of property. Some states do not have sales tax. For US orders, the tax calculation service includes the total tax value for the transaction and tax values and rates per jurisdiction, divided into national, state, county, city, and special taxes. Some states do not have sales tax.

Canadian Taxes

The same procedures apply to calculating taxes for Canada as for the United States. Use only Canadian dollars for all Canadian taxes. The tax calculation service returns:
  • GST as a country-level tax
  • PST and QST as state-level taxes
  • HST as the sum of GST and PST
If you want the tax calculation service to return HST as one field, contact customer support to configure your account accordingly.

Calculating US and Canadian Tax

To receive the most accurate tax calculation, you will need specific information for the field values. Follow these steps to determine the values for the fields.
IMPORTANT
One tax service request should not include more than 50 line items. When you send a request with more than 50 line items, the request could time out.
The Tax Calculation Service uses line-level rounding.  Tax amounts for each jurisdictional detail will be rounded and then aggregated to the line. For example, 8.5% total tax that includes 1.25% city tax, 1.25% county tax, and 6% state tax, levied on a 10.00 item would result in a total tax of 0.86 based on amounts of 0.13 city tax, 0.13 county tax, and 0.60 state tax. 

Step 1: Nexus

Identify the location of your company’s nexus. Products are taxable only when the customer’s 
orderInformation.shipTo.administrativeArea
 field value matches a state or province in which your company has nexus. If the ship to fields are not included in the request, the service will use the bill to fields to determine the tax amount. Use the 
taxInformation.nexus
 field to list the states or provinces in which your company has nexus. Alternatively, you can use the 
taxInformation.noNexus
 field to list states that should not be taxed.
IMPORTANT
You cannot combine the 
taxInformation.nexus
 and 
taxInformation.noNexus
 fields in the same request.
When you do not specify your nexus locations, the tax calculation service processes your request as if every state or province is taxable.
  • When you do not specify your nexus locations, or when a value of the nexus field matches the value for the 
    orderInformation.shipTo.administrativeArea
     field, the service calculates the applicable tax for the product.
  • When the value for the 
    orderInformation.shipTo.administrativeArea
     field does not match any state or province where you have nexus, the service assigns zero tax.
For more information, see Tax Nexus.

Step 2: Product Codes

If the product has special tax considerations, you can provide the appropriate tax product code in the 
orderInformation.lineItems.productCode
 field in the request.
For more information, see Product Codes.

Step 3: Addresses

To receive the most accurate tax calculation possible, include the following address information in the request:
  • Ship-to address, in fields in the 
    orderInformation.shipTo
     object. When multiple cities are within a postal code area, the optional request field 
    orderInformation.shipTo.locality
     value improves the accuracy of the calculated tax. 
  • Ship-from address, in fields in the 
    orderInformation.shipFrom
     object.  
  • Point-of-order acceptance, in fields in the 
    orderInformation.orderAcceptance
     object.
  • Point-of-order origin, in fields in the 
    orderInformation.orderOrigin
     object.
  • Product code, in the 
    orderInformation.lineItems.productCode
     field.
  • Nexus, in the 
    taxInformation.nexus
     field—or if it is easier, you can use the 
    taxInformation.noNexus
     field to provide a list of states in which you do not have nexus. 
When the tax calculation service succeeds, the response includes the 
orderInformation.amountDetails.totalAmount
 field.
When the optional request-level field 
taxInformation.showTaxPerLineItem
 is set to 
yes
, the response also includes the following fields for each offer:
  • orderInformation.taxDetails.type
     with the value of 
    city
    , 
    country
    , 
    county
    , 
    special
    , or 
    state
    . 
  • orderInformation.lineItems.jurisdiction
     object fields that provide detailed tax information.
For more address-related information, see Address Requirement.

Step 4: When to Calculate Tax

Determine when you will provide tax calculations during the customer transaction. Tax calculation can occur before or after determining the final order total. See Tax Reporting to know how this service can impact when you would want to request the tax service.
For more information, see When to Calculate Taxes.

Endpoint

POST
https://api.cybersource.com
/vas/v2/tax

Required Fields for a Tax Calculation Using the
REST API

Use these fields to perform a tax calculation.
clientReferenceInformation.code
orderInformation.lineItems.unitPrice
orderInformation.billTo.country
orderInformation.billTo.postalCode
orderInformation.billTo.locality
orderInformation.billTo.administrativeArea
taxInformation.showTaxPerLineItem
taxInformation.nexus
If you include this field, do not include the
taxInformation.noNexus
 field.
taxInformation.noNexus
If you include this field, do not include the
taxInformation.nexus
 field.

Optional Fields for a Tax Calculation Using the
REST
 API

Use these optional fields to perform a tax calculation.
clientReferenceInformation.code
clientReferenceInformation.partner.developerId
clientReferenceInformation.partner.solutionId
orderInformation.amountDetails.currency
orderInformation.billTo.address1
orderInformation.billTo.address2
orderInformation.invoiceDetails.invoiceDate
orderInformation.lineItems.orderAcceptance.administrativeArea
orderInformation.lineItems.orderAcceptance.country
orderInformation.lineItems.orderAcceptance.locality
orderInformation.lineItems.orderAcceptance.postalCode
orderInformation.lineItems.orderOrigin.administrativeArea
orderInformation.lineItems.orderOrigin.country
orderInformation.lineItems.orderOrigin.locality
orderInformation.lineItems.orderOrigin.postalCode
orderInformation.lineItems.productCode
orderInformation.lineItems.productName
orderInformation.lineItems.productSku
orderInformation.lineItems.quantity
orderInformation.lineItems.shipFromAdministrativeArea
orderInformation.lineItems.shipFromCountry
orderInformation.lineItems.shipFromLocality
orderInformation.lineItems.shipFromPostalCode
orderInformation.lineItems.taxAmount
orderInformation.orderAcceptance.administrativeArea
orderInformation.orderAcceptance.country
orderInformation.orderAcceptance.locality
orderInformation.orderAcceptance.postalCode
orderInformation.orderOrigin.administrativeArea
orderInformation.orderOrigin.country
orderInformation.orderOrigin.locality
orderInformation.orderOrigin.postalCode
orderInformation.shippingDetails.shipFromAdministrativeArea
orderInformation.shippingDetails.shipFromCountry
orderInformation.shippingDetails.shipFromLocality
orderInformation.shippingDetails.shipFromPostalCode
orderInformation.shipTo.address1
orderInformation.shipTo.address2
orderInformation.shipTo.address3
orderInformation.shipTo.administrativeArea
orderInformation.shipTo.country
orderInformation.shipTo.locality
orderInformation.shipTo.postalCode
taxInformation.commitIndicator
Set field to
true
 to commit tax calculation.
taxInformation.dateOverrideReason
taxInformation.refundIndicator
taxInformation.reportingDate
taxInformation.showTaxPerLineItem

Example: Processing a Tax Calculation Using the REST API

Light Dark
Request
12345678910111213141516171819202122232425262728
{"clientReferenceInformation": {
    "code": "TAX_TC001"
  },
  "taxInformation": {
    "nexus": "[CA,TX,AL]",
    "showTaxPerLineItem": "Yes"
  },
  "orderInformation": {
    "amountDetails": {
      "currency": "USD"
    },
    "billTo": {
      "address1": "1 Market St",
      "locality": "San Francisco",
      "administrativeArea": "CA",
      "postalCode": 94105,
      "country": "US"
    },
    "lineItems": [
      {
        "productSKU": "07-12-00657",
        "productCode": "PO000000",
        "quantity": 1,
        "productName": "Chewing Gum",
        "unitPrice": 1200
      }
    ]
  }}
Response
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122
{"_links": {
    "void": {
      "method": "PATCH",
      "href": "/vas/v2/tax/6679349380866991503954"
    }
  },
  "clientReferenceInformation": {
    "code": "TAX_TC001"
  },
  "id": "6679349380866991503954",
  "orderInformation": {
    "lineItems": [
      {
        "taxableAmount": "1200.00",
        "taxDetails": [
          {
            "amount": "0.00",
            "type": "city"
          },
          {
            "amount": "28.50",
            "type": "special"
          },
          {
            "amount": "72.00",
            "type": "state"
          },
          {
            "amount": "3.00",
            "type": "county"
          },
          {
            "amount": "0.00",
            "type": "national"
          }
        ],
        "jurisdiction": [
          {
            "country": "US",
            "code": "06",
            "taxable": "1200.00",
            "rate": "0.060000",
            "name": "CALIFORNIA",
            "type": "State",
            "region": "CA",
            "taxAmount": "72.00",
            "taxName": "CA STATE TAX"
          },
          {
            "country": "US",
            "code": "075",
            "taxable": "1200.00",
            "rate": "0.002500",
            "name": "SAN FRANCISCO",
            "type": "County",
            "region": "CA",
            "taxAmount": "3.00",
            "taxName": "CA COUNTY TAX"
          },
          {
            "country": "US",
            "code": "EMBE0",
            "taxable": "1200.00",
            "rate": "0.013750",
            "name": "SAN FRANCISCO COUNTY DISTRICT TAX SP",
            "type": "Special",
            "region": "CA",
            "taxAmount": "16.50",
            "taxName": "CA SPECIAL TAX"
          },
          {
            "country": "US",
            "code": "EMTV0",
            "taxable": "1200.00",
            "rate": "0.010000",
            "name": "SAN FRANCISCO CO LOCAL TAX SL",
            "type": "Special",
            "region": "CA",
            "taxAmount": "12.00",
            "taxName": "CA SPECIAL TAX"
          }
        ],
        "exemptAmount": "0.00",
        "taxAmount": "103.50"
      }
    ],
    "taxableAmount": "1200.00",
    "taxDetails": [
      {
        "amount": "28.50",
        "type": "special"
      },
      {
        "amount": "72.00",
        "type": "state"
      },
      {
        "amount": "0.00",
        "type": "national"
      },
      {
        "amount": "3.00",
        "type": "county"
      },
      {
        "amount": "0.00",
        "type": "city"
      }
    ],
    "exemptAmount": "0.00",
    "taxAmount": "103.50",
    "amountDetails": {
      "totalAmount": "1303.50",
      "currency": "USD"
    }
  },
  "status": "COMPLETED",
  "submitTimeUtc": "2022-11-08T19:15:38Z",
  "taxInformation": {
    "commitIndicator": "true",
    "refundIndicator": "false"
  }}