HomeDocumentationAPI Reference
Documentation
Start typing to search…

Reach Tax Quote API

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

Drop-In and Checkout API support tax quotes.

Step 1. Request a tax quote

The Reach Tax Quote API allows suppliers 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 an exclusive tax quote. For more details, see the Tax Quote API.

Exclusive tax flow

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.
    • (Optional) Include "TaxIncluded": true in the Items array. See TaxIncluded parameter for details.
  2. The /tax/quote response should include the following items:
    • The tax information.
    • A unique TaxQuoteId.
  3. Save the TaxQuoteId for later use for the Drop-In or Checkout API request.
✅

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.

curl --location 'https://api.sandbox.withreach.com/v1/tax/quote' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic cGF5c3RhY2s6WUlFO1BqOC1td0xjWHduVU4=' \
--data '{
    "Reference": "c43149ae-764a-4147-8bf2-cf574f5d5deb",
    "Currency": "CAD",
    "Items": [
        {
            "Amount": 45.9,
            "Sku": "SKU-1"
        }
    ],
    "ShippingAddress": {
        "Street": "86170 Mayer Ford",
        "City": "Micahfort",
        "Region": "AB",
        "Country": "CA",
        "Postcode": "t2t1g6"
    }
}
curl --location 'https://api.sandbox.withreach.com/v1/tax/quote' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic cGF5c3RhY2s6WUlFO1BqOC1td0xjWHduVU4=' \
--data '{
    "Reference": "9363c37a-2eb3-4040-92b1-6414e3869b78",
    "Currency": "CAD",
    "BusinessIdentifier": {
        "Type": "GST",
        "Number": "12345678"
    },
    "Items": [
        {
            "Amount": 105.1,
            "Sku": "SKU-1",
            "Name": "Item 1",
            "Description": "Description of Item 1",
            "Discounted": false,
            "TaxIncluded": false
        }
    ],
    "ShippingFromAddress": {
        "Street": "344 Maria Crest",
        "City": "South Crishaven",
        "Region": "NL",
        "Country": "CA",
        "Postcode": "A1B 1J1"
    },
    "ShippingAddress": {
        "Street": "86170 Mayer Ford",
        "City": "Micahfort",
        "Region": "NS",
        "Country": "CA",
        "Postcode": "E4L 0R6"
    },
    "Meta": {
        "Field1": "Meta Data",
        "Field2": "1234567890"
    }
}
curl --location 'https://api.sandbox.withreach.com/v1/tax/quote' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic cGF5c3RhY2s6WUlFO1BqOC1td0xjWHduVU4=' \
--data '{
    "Reference": "7ffc09fc-c1d9-46d3-bebf-b72a9170f406",
    "Currency": "CAD",
    "BusinessIdentifier": {
        "Type": "GST",
        "Number": "12345678"
    },
    "Items": [
        {
            "Amount": 45.9,
            "Sku": "Test",
            "Name": "Test",
            "Description": "Test",
            "Discounted": false,
            "TaxIncluded": true
        }
    ],
    "ShippingFromAddress": {
        "Street": "344 Maria Crest",
        "City": "South Crishaven",
        "Region": "NL",
        "Country": "CA",
        "Postcode": "A1B 1J1"
    },
    "ShippingAddress": {
        "Street": "86170 Mayer Ford",
        "City": "Micahfort",
        "Region": "NS",
        "Country": "CA",
        "Postcode": "E4L 0R6"
    },
    "Meta": {
        "Field1": "test",
        "Field2": "test"
    }
}
curl --location 'https://api.sandbox.withreach.com/v1/tax/quote' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic cGF5c3RhY2s6WUlFO1BqOC1td0xjWHduVU4=' \
--data '{
    "Reference": "6acb36f2-547e-4dfd-b566-b3a3e20d4c01",
    "Currency": "CAD",
    "BusinessIdentifier": {
        "Type": "GST",
        "Number": "12345678"
    },
    "Items": [
        {
            "Amount": 45.9,
            "Sku": "Test",
            "Name": "Test",
            "Description": "Test",
            "Discounted": true,
            "TaxIncluded": false
        }
    ],
    "ShippingFromAddress": {
        "Street": "344 Maria Crest",
        "City": "South Crishaven",
        "Region": "NL",
        "Country": "CA",
        "Postcode": "A1B 1J1"
    },
    "ShippingAddress": {
        "Street": "86170 Mayer Ford",
        "City": "Micahfort",
        "Region": "NS",
        "Country": "CA",
        "Postcode": "E4L 0R6"
    },
    "Meta": {
        "Field1": "test",
        "Field2": "test"
    },
    "Discounts":[
        {
            "Name": "Discount 1",
            "Amount": 10.00
        }

    ]
}

TaxIncluded parameter

The TaxIncluded parameter is an optional field that you can include in the items array when making a request to the Tax Quote API. This parameter indicates whether the price of the items in the cart includes tax.

Use cases

  • Scenario 1: If you set TaxIncluded to true, the Tax Quote API will understand that the customer views prices that already incorporate tax. The calculated tax returned in the response will be based on the net price (price excluding tax) derived from the total price provided.
  • Scenario 2: If you omit the TaxIncluded parameter or set it to false, the Tax Quote API will assume that the given item prices exclude tax, and it will calculate the applicable tax based on those prices and return the tax amount separately.

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. Follow the instructions in Create a Checkout API request.

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,
        }
      ],
      "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,
        }
    ],
    "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 3. Tax filing and remittance

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

Reach tax flow


Updated 4 days ago