DocumentationAPI Reference
Documentation

Reach Tax Quote API

Suggest Edits

This guide shows merchants how to request a tax quote using the Tax Quote API.

Both the Drop-In and Checkout API support tax quotes.

Step 1. Request a tax quote

The Reach Tax Quote API allows merchants to request a Tax quote based on customers' items and state/country to retrieve a calculated Tax amount due for such an order. The following image shows the request flow for a tax quote. For more details, see the Tax Quote API.

The following flow chart shows the Reach tax quote workflow.

The request flow for a tax quote

The request flow for a tax quote

Follow the instructions below to request a tax quote.

  1. Send a /tax/quote request and include the following information in the request body:
    • The cart details.
    • The shipping information.
    • Include "TaxIncluded": true in the Items array.
  2. The /tax/quote response should include the following items:
    • The tax information.
    • A unique TaxQuoteId.
  3. Save the TaxQuoteId for later use.

👍

Best practice

If the customer updates the cart, send a Tax Quote API call with the updated cart details to get the new Tax Quote API response.

Note that a Drop-In or Checkout request will use the Tax Quote ID returned in the tax quote 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": "d329e361-567c-40b9-8201-580483761f1d",
  "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": "85003"
  },
  "Amount": 22.09,
  "TaxAmount": 1.9
}

Step 2. Display the tax (cart) details

Use the tax information from the /tax/quote response to display the customer's updated total, including taxes, on your checkout page. Based on your integration solution, choose the appropriate option below.

Create a Checkout API request

When creating a checkout request for the total amount (including taxes), include the TaxQuoteId from Step 1 in the checkout payload.

{
  "url": "http://checkout.rch.how/v2.21/checkout",
  "method": "POST",
  "redacted": true,
  "arguments": {
    "request": {
      "MerchantId": "66666666-c476-4ed7-b7f0-39da57872fb4",
      "ReferenceId": "upsell_V9ocQx3QZPwx7i65khhygygyggRCDQKxIKUsGddU76kQe2wKe7UXj8EOytSzN_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": "Jefferson Street"
        "City": "Phoenix",
        "Region": "AZ",
        "PostalCode": "85003",
        "Country": "US"
      },
      "Capture": true,
      "ContractId": "44444444-3251-4e84-8202-8ce5fa5f149f",
      "Shipping": {
        "ConsumerPrice": 0,
        "ConsumerTaxes": 1.9,
        "ConsumerDuty": 0
      },
      "Consignee": {
        "Name": "w***********c",
        "Address": "****************************",
        "City": "Phoenix",
        "Country": "US"
      },
      "Notify": "https://api.sandbox.withreach.com/v1/notifications/merchant/372c86bb-c476-4ed7-b7f0-39da57872fb4",
      "TaxQuoteId": "d329e361-567c-40b9-8201-580483761f1d"
    },
    "signature": "FVS2onAKiBLRKCzXt+WfG95rEWiBE4htJN1jDh8YLh4="
  },
  "content_type": "application/x-www-form-urlencoded"
}

{
  "status": 200,
  "entity": {
    "raw": "response=<raw response>,
    "parts": {
      "response": {
        "OrderId": "88888888-e9e7-44ed-a054-214c7e5c1cb7",
        "UnderReview": false,
        "ContractId": "22222222-3251-4e84-8202-8ce5fa5f149f",
        "Authorized": true,
        "Completed": true,
        "Captured": true
      },
      "signature": "wjikSHJFnxCuY5fXceUjgfLZx5nHk209NVi165waFS3s="
    }
  },
  "content_type": "application/x-www-form-urlencoded; charset=utf-8"
}

Payment Session and process the payment

  1. When creating a session for the total amount (including taxes), include the TaxQuoteId from Step 1 in the session payload.
  2. The shopper will enter their payment details in the Reach Drop-In on the checkout page and submit the cart. This action creates the order, and Reach processes the payment. 
{
    "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"
}


{
    "SessionId": "7bc87adc-8110-4878-8207-096cf85e1d65",
    "State": "CREATED",
    "MerchantReference": "999999-51d0-4d9c-9476-31b2c847b806",
    "Items": [
        {
            "Name": "Item 1",
            "Amount": 10.00,
            "Quantity": 1
        }
    ],
    "Currency": "USD",
    "TotalAmount": 10.00,
    "BillingProfile": {
        "BillingProfileId": "8718177-a55e-4b5d-b5b6-394c418d577e",
        "BillingProfileReference": "taxwaywewin98",
        "Name": "First Last",
        "Email": "[email protected]",
        "Address": {
            "Street": "123 Street",
            "City": "City",
            "Region": "AZ",
            "Country": "US",
            "Postcode": "85005"
        }
    },
    "AutoCapture": true,
    "CompleteUrl": "https://www.send-user-here-after-success-redirect.com",
    "CancelUrl": "https://www.send-user-here-after-failed-redirect.com",
    "ViaAgent": false,
    "TaxQuoteId": "99999999-b613-44f9-81b1-c82dd9552826"
}

Step 4. Tax filing and remittance

Reach associates each transaction with its TaxQuoteId and properly withholds, files, and remits taxes to the corresponding jurisdictions..

Updated 3 days ago