HomeDocumentationAPI Reference
Documentation
Start typing to search…

Integrating tax with Reach

This guide provides a streamlined approach for merchants integrating tax calculations into their systems using the Reach API.

Tax without the Hassle

By choosing Reach, we support you by handling:

  • Calculate rates with geolocation and product classification.
  • Automate returns, filing, and remittance.
  • Monitoring compliance with ever-changing international regulations and rates.
  • Provision of tax-compliant invoices to your customers regardless of location.
  • Enable solutions for complex, multinational operations.

Reach's Tax Solution in Action

When a shopper navigates to your checkout page with items in their cart, a simple API call from the storefront to Reach's powerful Tax Calculation API will return the precise tax amounts required to be charged based on that shopper's geolocation and the specific classifications of your product.

Understanding the Reach Tax Flow

This flowchart gives a more in-depth demonstration of how data flows back-and-forth between shopper, merchant, and Reach during the tax calculation and remittance process.


How to Call the Tax Quote API

The Reach Tax API allows merchants to request a Tax quote based on customers' items, state/country to retrieve a calculated Tax amount due for such an order.

The following steps include instructions for both Reach Drop-In & Reach's Checkout API.

Step 1

Request a Tax Quote

When the customer proceeds to your checkout:

  • Send a request to the Reach Quote API, including:

    • Cart details
    • Shipping information

  • The Quote API response will include:

    • Tax information
    • A unique TaxQuoteId

  • Save the TaxQuoteId for later use.

🚧

Note:

If the customer updates the Cart, it is recommended that you call the Reach Quote API with updated Cart details to get the new Tax API response.

curl --request POST \
     --url https://api.sandbox.withreach.com/v1/tax/quote \
     --header 'accept: application/json' \
     --header 'authorization: Basic cGVyYmwesssdThMMDBxckkio9=' \
     --header 'content-type: application/json' \
     --data '\
{
  "Items": [
    {
      "TaxIncluded": true,
      "Sku": "TX890",
      "Description": "Beauty Soap",
      "Quantity": 1,
      "Amount": 23.99
    }
  ],
  "ShippingAddress": {
    "Street": "Jefferson Street",
    "City": "Phoenix",
    "Region": "AZ",
    "Country": "US",
    "Postcode": "85005"
  },
  "Currency": "USD",
  "Reference": "TaxQuoteTest101"
}
'
{
  "Id": "99999999-b613-44f9-81b1-c82dd9552826",
  "Currency": "USD",
  "Items": [
    {
      "Id": "ac6d3657-e284-4e52-a2d7-32fb58cd834b",
      "Sku": "TX890",
      "Description": "Beauty Soap",
      "TaxCode": "P0000000",
      "TaxIncluded": true,
      "Quantity": 1,
      "Amount": 22.09,
      "TaxAmount": 1.9,
      "Tax": [
        {
          "Name": "AZ STATE TAX",
          "Type": "Sales",
          "TaxAmount": 1.24
        },
        {
          "Name": "AZ COUNTY TAX",
          "Type": "Sales",
          "TaxAmount": 0.15
        },
        {
          "Name": "AZ CITY TAX",
          "Type": "Sales",
          "TaxAmount": 0.51
        }
      ]
    }
  ],
  "ShippingAddress": {
    "Street": "Jefferson Street",
    "City": "Phoenix",
    "Region": "AZ",
    "Country": "US",
    "Postcode": "85005"
  },
  "Amount": 22.09,
  "TaxAmount": 1.9
}

Click here for full request example


❗️

Note:

In the Example Tax Quote Response - note the returned TaxQuoteId and the Tax Amount which will be used when making a Drop In or a checkout Request.


Step 2

Display Tax (Cart) Details

  • Use the tax information from the Quote API response to display an updated total, including taxes, to the customer on your checkout page.



For Checkout API

Step 3

Create a Checkout API Request

  • When creating a checkout request for the total amount (including taxes):

    • Include the TaxQuoteId from Step #1 above in the checkout payload\ 
"url": "http://checkout.rch.how/v2.21/checkout",
  "method": "POST",
  "redacted": true,
  "arguments": {
    "request": {
      "MerchantId": "372c86bb-c476-4ed7-b7f0-39da57872fb4",
      "ReferenceId": "upsell_V9ocQx3QZPwx7i65DcoxrUjIyVdRuRCDQKxIKUsGddU76kQe2wKe7UXj8EOytSzN_reach_1730195809",
      "DeviceFingerprint": "a533213f-3484-46ce-af6b-d6f3b9d570bd",
      "ConsumerCurrency": "USD",
      "Items": [
        {
          "Sku": "TX890",
          "ConsumerPrice": 22.09,
          "Quantity": 1
        }
      ],
      "Consumer": {
        "Name": "w***********c",
        "Email": "m**********m",
        "Address": "****************************",
        "City": "Washington DC",
        "Region": "DC",
        "PostalCode": "20036",
        "Country": "US"
      },
     "Consignee": {
        "Name": "w***********c",
        "Address": "****************************",
        "City": "Phoenix",
        "Region": "DC",
        "Country": "US"
      },      
      "Capture": true,
      "Shipping": {
        "ConsumerPrice": 22.09,
        "ConsumerTaxes": 1.9,
        "ConsumerDuty": 0
      },
      "TaxQuoteId": "99999999-b613-44f9-81b1-c82dd9552826"
    }
  }
}

For Drop-In API

Step 3

Create a Payment Session & Process the Payment

  • When creating a session for the total amount (including taxes):

    • Include the TaxQuoteId from Step #1 in the session payload.

  • Display Drop-in, Customer enters their payment details, the order is created and processed by Reach.


{
    "MerchantReference": "877hh-099-81jy",
    "Currency": "USD",
    "Items": [
        {
            "Name": "Item 1",
            "Amount": 10.00,
            "Quantity": 1
        }
    ],
    "BillingProfile": {
        "BillingProfileReference": "taxwaywewin98",
        "Name": "First Last",
        "Email": "[email protected]",
        "Address": {
            "Street": "123 Street",
            "City": "City",
            "Region": "AZ",
            "Postcode": "85005",
            "Country": "US",
            "Phone": "4031234567"
        }
    },
    "TaxQuoteId": "99999999-b613-44f9-81b1-c82dd9552826",
    "AutoCapture": true,
    "CompleteUrl": "https://www.send-user-here-after-success-redirect.com",
    "CancelUrl": "https://www.send-user-here-after-failed-redirect.com"
}

Step 4

Tax Filing and Remittance

  • Reach matches the transaction with the TaxQuoteId.

  • Taxes are:

    • Withheld
    • Filed
    • Remitted to the appropriate jurisdictions.\

Updated 4 days ago