Order Completion

The most important step for sales tax compliance is recording when sales tax proceeds have been collected by the seller from the customer. Without completing this important step, no sales tax proceeds can be included in subsequent sales tax reports and returns. Given the importance of this step, it is the easiest class of APIs to implement, requiring only two parameters (cartID and orderID) beyond the basic API credentials.

Order Completion Options

Developers have two choices for order completion, we recommend using the simplified approach unless your payment flow requires separate authorization and capture:

• Simplified order completion via AuthorizedWithCapture API call.

• Articulated order completion via separate Authorized and Captured API calls.

Simplified Order Completion (Recommended)

Simplified order completion is accomplished using our AuthorizedWithCapture API. Conceptually, before adding TaxCloud to your simplified checkout process you have three basic steps:

1. Customer puts items in the shopping cart

2. Customer provides payment information and presses the “buy” button

3. Commerce platform processes payment, then the Seller ships the order to the customer

After adding TaxCloud to your checkout process there, two steps will be added:

1. Customer puts items in the shopping cart

2. Commerce platform performs a tax Lookup API call to calculate tax amounts due (if any)

3. Customer provides payment information and presses the “buy” button

4. Commerce platform processes payment, then the Seller ships the order to the customer

5. Commerce platform performs an AuthorizedWithCapture API call to ensure such tax proceeds will be reported in the next sales tax return.

Articulated Order Completion

Articulated order completion breaks the Authorized and Captured API calls into distinct steps to align with your payments process. Some payment platforms offer lower payment processing fees if you separate payment authorization from payment capture. Conceptually, before adding TaxCloud to your articulated checkout process you have four basic steps:

1. Customer puts items in the shopping cart

2. Customer provides payment information and presses the “buy” button

3. Commerce platform authorizes payment with the payment processor

4. Commerce platform captures payment, then ships the order to the customer

After adding TaxCloud to your checkout process three steps will be added:

1. Customer puts items in the shopping cart

2. Commerce platform performs a tax Lookup API call to calculate tax amounts due (if any)

3. Commerce platform authorizes payment with the payment processor when the customer presses the “buy” button

4. Commerce platform performs a tax Authorized API

5. Commerce platform captures payment, then ships the order to the customer

6. Commerce platform performs a Captured API call to ensure such tax proceeds will be reported in the next sales tax return.

Required Parameters

IMPORTANT: orderID is not interchangeable with customerID. Each orderID must be globally unique for the given API credentials and cannot be reused once the order has been captured or completed.

We’ve seen implementations that mistakenly conflate orderID with customerID. While this may appear to work initially, problems arise when the same customer places a new order. In that scenario, Lookup calls will still return valid tax amounts, but subsequent calls to Authorized, Captured, or AuthorizedWithCapture will fail with a blocking error: OrderID ({OrderID}) has already been captured.

This error means the tax amount was presented to the customer and potentially collected during checkout, but the transaction record remains incomplete (no captured date on file). As a result, the transaction will be excluded from sales tax reporting.

NOTE: Ensure that you have a unique orderID for each connection to avoid rejecting a valid order by mistake.

Example request and response

Request

HTTPS POST api.taxcloud.net/1.0/TaxCloud/AuthorizedWithCapture

1
{
2
    "apiLoginID": "XXXXXXX",
3
    "apiKey": "XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
4
    "customerID": "WonderfulCustomer33",
5
    "cartID": "B0DABCEE-34EE-4A76-B4C5-B5F32F430B74",
6
    "orderID": "order23",
7
}

Response (success)

1
{
2
  "ResponseType": 3,
3
  "Messages": []
4
}

Response (error)

1
{
2
  "ResponseType": 0,
3
  "Messages": [
4
    {
5
      "ResponseType": 0,
6
      "Message": "This Order ID (order23) has already been captured."
7
    }
8
  ]
9
}

About ResponseTypes and Messages

ResponseType 3 = SUCCESS. If the ResponseType is anything other than 3, the request has failed and your commerce platform should log all errors, not just for development purposes, but more importantly for audit purposes. If the ResponseType is not 3, TaxCloud will provide a Message which will be either a single string message, or an array of string messages. All response messages should be added to your commerce platform error log, and may optionally be presented to the customer.