The Most Important Step: Order Completion

Review

Before we jump into this guide, let's review what we have already accomplished (if you are progressing sequentially through our how-to guides):

  • [x] 1. Address verification (API: VerifyAddress) - Done
  • [x] 2. Tax Amount lookup (API: Lookup) - Done
  • [ ] 3. Order completion (APIs: Authorized and Captured; or AuthorizedWithCapture) - You are here
  • [ ] 4. Merchandise returns (API: Returned) - On Deck

Part 1. Introduction to Our Order Completion APIs

Our Order Completion APIs include Authorized & Captured (or our combined AuthorizedWithCapture). These are our easiest-to-implement APIs because they are the most important!

We know what many of you may be thinking, because we have heard it before:

"We don't need to do the Authorized and Captured steps, because we only need to figure out the sales tax due."

OR

"We aren't using TaxCloud to file our sales tax returns, so we can skip the order completion APIs."

BOTH OF THESE STATEMENTS REVEAL A MISUNDERSTANDING ABOUT SALES TAX COMPLIANCE

While it is true that determining the amount of sales tax to collect is difficult (although TaxCloud makes it very easy), the flip-side of the sales tax compliance coin is the obligation to periodically report and remit the sales tax collected to the various jurisdictions of record.

This is why our Order Completion APIs are required for all TaxCloud API implementations. Because without implementing these API calls, everyone that ever uses your implementation will have to re-create every transaction just to figure out the exact amount of sales tax to report and remit to the various tax jurisdictions. However, by using our very easy-to-use Order Completion APIs, this task is also performed by TaxCloud through our automatically generated sales tax reports.

IMPORTANT: If you do not call our order completion APIs, TaxCloud will think all of your orders were abandoned before completion, and those orders will not be included in our sales tax reports.

Part 2. Authorized

Once a customer has completed checkout (pressed the "Confirm Purchase" button) and the purchase has been authorized by the payment processor, it's time to let TaxCloud know the transaction was authorized. A corresponding Lookup API call must have been made before the Authorized API call will succeed because one of the required parameters is the cartID from the previous Lookup.

IMPORTANT: The contents of the shopping cart must NOT change between the last Lookup API call and the Authorized API call. If anything has changed since the last Lookup, such as the application of a discount coupon, just do another Lookup with the adjusted item prices to get the adjusted tax amounts. This is exactly why TaxCloud does not charge fees for API Lookup calls. Because such a practice would discourage frequent use (and may lead developers to implement crazy caching schemes).

Authorized API's Parameters

Parameter Description Required
apiLoginID This is your website's API ID Yes
apiKey This is your website's API KEY Yes
customerID The unique identifier for the customer entity making a purchase. Yes
cartID This must be the cartID from a previous Lookup Yes
orderID This is the immutable unique transaction/order identifier issued by your commerce system when the order was placed. Yes
dateAuthorized Date the transaction was authorized with the payment processor. Yes

The POST

Once you have your parameters assembled, your HTTP POST to https://api.taxcloud.com/1.0/TaxCloud/Authorized is ready to go!

Here is a sample request:

{
  "apiLoginId": "XXXXXXXXX",
  "aipKey":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "customerID": "CustomerX",
  "cartID": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "orderID": "100024",
  "dateAuthorized":"2016-03-27"
}

The Response

If successful, TaxCloud will respond with a standard ResponseType of 3 (Success) and an empty Messages array.

If the ResponseType is 0 (Error) there will be a Messages array, with one or more Message elements describing what went wrong — usually:

This transaction has already been marked as authorized (CartID : TheDuplicateCardID)

OR

A matching lookup could not be found for this transaction (CartID : TheMissingCardID)

The first error is self-explanatory, but the second error indicates the preceeding Lookup failed. This second error should cause immediate concern. If the Lookup failed, then no tax was determined or charged!

Part 3. Captured

This is the final call in a typical TaxCloud transaction. The Captured API call completes the transaction. IMPORTANT: The orderID passed into Captured must match that passed into the previous Authorized API call.

Usually, our Captured API is called when an order is marked as shipped or completed in the online store or the order management system's admin interface.

Captured API's Parameters

Parameter Description Required
apiLoginID This is your website's API ID Yes
apiKey This is your website's API KEY Yes
orderID This is the immutable unique transaction/order identifier passed into the previous Authorized API call Yes

The POST

Once you have your parameters assembled, your HTTP POST to https://api.taxcloud.com/1.0/TaxCloud/Captured is ready to go!

Here is a sample request:

{
  "apiLoginId": "XXXXXXXXX",
  "aipKey":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "orderID": "100024"
}

The Response

If successful, TaxCloud will respond with a standard ResponseType of 3 (Success) and an empty Messages array.

If the ResponseType is 0 (Error) there will be a Messages array, with one or more Message elements describing what went wrong — usually:

This transaction has already been captured (orderID : TheDuplicateOrderID)

OR

This transaction must be authorized before it can be captured (CartID : TheMissingCardID)

The first error is self-explanatory, but the second error indicates the preceeding Authorized API call failed. This second error should cause immediate concern. If the Authorized and Captured have now both failed, then the tax amount collected will not be included in your sales tax reports!

Part 4. AuthorizedWithCapture

If you have already implemented Authorized and Captured, you can skip ahead.

OK, so this one (AuthorizedWithCapture) is basically a shortcut for those who use a payment processor that allows Authorize and Capture payment API calls to happen in a single call (a so-called AuthCap).

As with the previously described Authorized API call, a corresponding Lookup API call must have been made before the AuthorizedWithCapture call will succeed because one of the required parameters is the cartID from the previous Lookup.

IMPORTANT: Also, just like the previously described Authorized API call, the contents of the shopping cart must NOT change between the last Lookup API call and the AuthorizedWithCapture API call.

AuthorizedWithCapture API's Parameters

Parameter Description Required
apiLoginID This is your website's API ID Yes
apiKey This is your website's API KEY Yes
customerID The unique identifier for the customer entity making a purchase. Yes
cartID This must be the cartID from a previous Lookup Yes
orderID This is the immutable unique transaction/order identifier issued by your commerce system when the order was placed. Yes
dateAuthorized Date the transaction was authorized with the payment processor. Yes
dateCaptured Date the transaction was captured with the payment processor. Yes

The POST

Once you have your parameters assembled, your HTTP POST to https://api.taxcloud.com/1.0/TaxCloud/AuthorizedWithCapture is ready to go!

Here is a sample request:

{
  "apiLoginId": "XXXXXXXXX",
  "aipKey":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "customerID": "CustomerX",
  "cartID": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
  "orderID": "100024",
  "dateAuthorized":"2016-03-27",
  "dateCaptured":"2016-03-27"
}

The Response

If successful, TaxCloud will respond with a standard ResponseType of 3 (Success) and an empty Messages array. Any errors will be reported as described for the Authorized and Captured APIs.

Part 5. What's Next?

Congratulations all around. You have now implemented sales tax.

Let's review where we are at:

  • [x] 1. Address verification (API: VerifyAddress) - Done
  • [x] 2. Tax Amount lookup (API: Lookup) - Done
  • [x] 3. Order completion (APIs: Authorized and Captured; or AuthorizedWithCapture) - Done
  • [ ] 4. Merchandise returns (API: Returned) - Up Next

If your implementation doesn't need to support Order Returns, you are done! If you do need to support returns, you will want to continue to our next how-to on Returns (coming soon).