The Most Important Step: 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.

Frequently, developers will complete implementation of Lookup and believe their work done. However, without invoking TaxCloud order completion APIs (Authorized, Captured, or AuthorizedWithCapture) TaxCloud's most valuable compliance features are derailed—and someone in the accounting or tax department at the retailer will have to manually construct all of the jurisdiction and sub-jurisdiction details from external sources, rather than taking advantage of TaxCloud's automatically generated reports.

Because order completion is so important, we designed our APIs to make it the easiest to perform.

Order Completion Options

Developers have two choices for order completion, the one you choose should match your payment process:

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

Simplified Order Completion

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

Simplified Checkout before adding TaxCloud

  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:

Simplified Checkout after adding TaxCloud

  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:

Articulated Checkout before adding TaxCloud

  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:

Articulated Checkout after adding TaxCloud

  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

Parameter Description Example
apiLoginID Your unique 7 or 8 character API ID XXXXXXX
apiKey Your unique API KEY XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
customerID Your order management or e-commerce system generated unique customer identifier (not an email address) see about customerIDs
cartID Your order management or e-commerce system generated unique invoice or order number see about cartIDs
orderID The immutable Order identifier used by your order management or e-commerce system to idenitify unique orders. order23
IMPORTANT: orderID is not interchangeable with customerID. Mechanically, each orderID must be globally unique for a particular set of API credentials, and cannot be reused after the orderID has been captured/completed. We have seen implementations that conflate orderID with customerID which appear to be working at first. But the next time the same customer returns to make another purchase, Lookup responses will return accurate sales tax amounts. However, Authorized, Captured, and AuthorizedWithCapture will all respond with a blocking error: "Order ID ({OrderID}) has already been Captured". This is very bad because the customer was presented the tax amount due, and the payment process captured the tax amount due, but the sales tax record will be incomplete (no captured date on record) causing the transaction to be excluded from subsequent sales tax reporting.
 
Lesson: DO NOT USE CUSTOMERID AS ORDERID.

Optional Parameters

The optional parameters are dates which will ordinarily be inferred from the moment the API request is called. You should not use these parameters unless you are sure you know what you are doing.

For example, if you issue a Captured or AuthorizedWithCapture API call specifying a date from 6 months ago, you would be trigger a compulsory Amended Sales Tax Return for the period from six months ago, and possibly every intervening period. If this happens, each amended period will provoke late/amended fees from TaxCloud. If TaxCloud is not handling your compliance obligations, additional costs from your CPA or Tax Counsel should be expected to prepare and file amended returns.

Parameter Description Example
dateAuthorized Specify the authorization date (YYYY-MM-DD) 2019-8-15
dateCaptured Specify the captured date this is the actual moment of taxation 2019-8-15

Let's do this

REQUEST

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

{
    "apiLoginID": "XXXXXXX",
    "apiKey": "XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "customerID": "WonderfulCustomer33",
    "cartID": "B0DABCEE-34EE-4A76-B4C5-B5F32F430B74",
    "orderID": "order23",
}

RESPONSE (success)

{
  "ResponseType": 3,
  "Messages": []
}

RESPONSE (error)

{
  "ResponseType": 0,
  "Messages": [
    {
      "ResponseType": 0,
      "Message": "This Order ID (order23) has already been captured."
    }
  ]
}

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.

What's Next?

Nothing. You are done!

If you want to do more, you can implement our Returned API so that you can be sure to benefit from tax credits available when your customers return a purchase.

  • VerifyAddress
  • Lookup
  • AuthorizedWithCapture
  • Returned