> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.taxcloud.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.taxcloud.com/_mcp/server.

# Transaction Lifecycle

When integrating with TaxCloud, developers interact with two fundamental transactional objects: **Carts** and **Orders**.

These aren’t just arbitrary entities; they represent different states in the lifecycle of a transaction, and they drive the downstream processes of sales tax calculation, reporting, and filing. Understanding the distinction between carts and orders, how and when a transaction transitions between them, is critical to building correct, compliant, and maintainable integrations.

Whether you’re doing a real-time tax calculation or Order Upload of post-sale transactions for reporting, your system’s interaction with these objects will directly affect:

* What you can or cannot change later  
* When tax liability is created  
* How the transaction is handled for filing and audits  
* Which API endpoints you should call at each step

In this guide, we’ll walk through the full transaction lifecycle in TaxCloud, focusing on the two primary workflows you may use:

* **Real-time API Flow**: Real-time tax calculation during an online purchase, where you begin with a cart and convert it to an order.  
* **Order Upload Flow**: Bulk or post-sale reporting where you directly create converted orders, often from another system.

Understanding the rules and expectations around these models will help prevent data errors, tax miscalculations, and reporting failures.

## Cart vs. Order

A **cart** in TaxCloud is an editable snapshot of a potential transaction. Carts let you calculate taxes before a purchase is finalized.

* You can create, update, and recalculate a cart multiple times.
* Updating a cart replaces all prior values -— think of it as resubmitting the entire cart rather than patching specific fields.
* A cart is retrievable through the [Get Cart](https://docs.taxcloud.com/api-reference/api-reference/sales-tax-api/cart/get-cart) endpoint until it is converted, and is cached for up to 180 days from its last update. Converting a cart removes it: the resulting order becomes the record, and that cart can no longer be retrieved or modified. Sending the same `cartId` again creates a new cart under that ID and leaves the existing order untouched.

Use carts for in-progress transactions. Once finalized, convert to an order for permanent storage and reporting.

An **order**, on the other hand, is a converted, finalized transaction. Orders represent completed purchases and are included in tax reports and filings. Once an order is created, it is generally immutable, with the exception of marking them as complete if not done at creation.

You typically transition from a Cart to an Order by “converting” the Cart via the [**Create an order from a cartID**](https://docs.taxcloud.com/api-reference/api-reference/sales-tax-api/cart/create-orders) endpoint.

| Property | Cart | Order |
| ----- | ----- | ----- |
| Purpose | Estimate tax for draft sale | Record finalized transaction |
| Editable? | Yes (until converted) | No (with exceptions) |
| Included in reports? | No | Yes |
| Can be recalculated? | Yes (until converted) | No |

## Converting Carts to Orders

To “convert” a Cart into an Order is to signal that the transaction has occurred. This is done using the [**Create an order from a cartID**](https://docs.taxcloud.com/api-reference/api-reference/sales-tax-api/cart/create-orders) endpoint and results in the creation of a new Order object.

Converting a cart:

* Locks the transaction from further changes  
* Signals that it is ready for reporting  
* Removes the original cart, so [Get Cart](https://docs.taxcloud.com/api-reference/api-reference/sales-tax-api/cart/get-cart) no longer returns it; the resulting order is the record

### TaxCloud's Recommendation

We generally recommend converting a cart to an order once the customer has checked out or the order has been submitted. This aligns with when most states consider the sale to have occurred.

However, this is **not a tax advice**. You may choose to capture orders later, such as when payment is collected or when goods are transferred to the customer (e.g., shipped). The right approach depends on your business practices and accounting method.

## When Tax Liability is Created

Converting a cart into an order does not incur tax liability by itself. Liability is only recognized when the order is marked as `complete`. An order becomes complete when:

* `completed: true` is set during creation.  
* A `completedDate` is provided during creation, which takes precedence over `completed`.  
* A `completedDate` is provided later via the [Update Order](https://docs.taxcloud.com/api-reference/api-reference/sales-tax-api/orders/update-order) endpoint.

The `completedDate` determines the tax period the order falls into, whether you set it at creation or later.

The `transactionDate` field reflects when the order was created or submitted, but it does not affect tax filing.

### TaxCloud's Recommendations

We recommend that you complete an order when the transfer of ownership of the product or service occurs. The timing of this depends on your business model:

* **Immediate delivery**: If ownership transfers at the time the order is submitted (for example, digital downloads available right after checkout), you can complete the order when creating it from a cart.

* **Deferred delivery**: If fulfillment happens after the order is submitted (for example, shipping physical goods), you should complete the order at the time of delivery or when ownership legally transfers.

The `completedDate` you send to TaxCloud determines when the tax liability will be reported. For example, if the `completedDate` is **August 4, 2025**, that transaction will be included in your **August filing report**.

> **Note**
>
> This guidance is provided for technical integration purposes only and is **not tax advice**. Please consult your tax professional to confirm the appropriate treatment of order completion for your specific business.

## Lifecycle Stages by Workflow

TaxCloud supports two main integration workflows. While both result in converted transactions being reported and filed, how you get there varies based on your system design and operational model.

We’ll walk through the transaction lifecycle for each workflow separately.

### Real-Time API Flow

This is the most common workflow for real-time commerce platforms, such as e-commerce sites, mobile apps, or POS systems with online tax calculation.

In this flow, the transaction moves through four distinct stages, modeling the lifecycle from calculation to reporting.

#### Stage 1: Create Cart

Use the [Create Cart](https://docs.taxcloud.com/api-reference/api-reference/sales-tax-api/cart/create-cart) endpoint to begin the transaction lifecycle. This object is your working draft. You can update it with:

* Items being purchased  
* Customer address  
* Shipping cost  
* Discounts

TaxCloud uses this data to calculate tax based on jurisdictional rules. You’ll receive a tax quote in the response.

#### Stage 2: Modify or Recalculate Cart

As the user updates their cart: changes quantity, applies a promo code, updates address, you can recalculate tax by sending the updated cart to TaxCloud. Each call must include the full data needed for tax calculation, as TaxCloud does not support incremental updates to your cart.

You can provide a custom `cartId` to reference the cart later, and retrieve it with the [Get Cart](https://docs.taxcloud.com/api-reference/api-reference/sales-tax-api/cart/get-cart) endpoint. If you reuse the same `cartId`, the existing cart is overwritten with the new payload you send. If you provide a new `cartId`, a new cart is created. You can do this as many times as needed until the user is ready to check out.

Get Cart returns a cart only while it exists as a cart, and a cart is cached for up to 180 days from its last update. Converting a cart removes it, so Get Cart no longer returns it — reference the resulting order instead. Reusing a `cartId` after conversion creates a new cart under that ID and does not change the order already created. A request for a cart that has been converted, has expired, or never existed returns an error rather than a cart.

#### Stage 3: Convert Cart → Create Order

Once the customer checks out or submits the order and the transaction is final, convert the Cart by calling the [**Create an order from a cartID**](https://docs.taxcloud.com/api-reference/api-reference/sales-tax-api/cart/create-orders) endpoint.

This:

* Creates a new order object  
* Finalizes the tax calculation  
* Locks the data for reporting

Converting removes the original cart, so it can no longer be retrieved or modified; the new order is the record from this point on. Orders at this stage remain incomplete unless you set `completed` to `true` or provide a `completedDate` during creation. You can also set the `completedDate` later by calling the [Update Order](https://docs.taxcloud.com/api-reference/api-reference/sales-tax-api/orders/update-order) endpoint. If you send both, the `completedDate` takes precedence over `completed`.

> Only `completed` orders incur tax liability. Complete the order once the transfer of ownership is finalized (e.g., at digital delivery or shipping).

#### Stage 4: Reporting & Filing

All completed Orders are included in TaxCloud’s reporting and filing pipeline, if it’s part of your plan. The `completedDate` on your order dictates the tax reporting period. This includes:

* Monthly reports  
* State filings  
* Audit trails

Accuracy here is critical. Once reported, fixing errors is far more complex and may involve amended returns.

### Order Upload Flow

This workflow is designed for developers that:

* Complete the sale outside of TaxCloud integration.  
* Perform tax calculations using a different system.  
* Need to upload converted transactions into TaxCloud for **reporting**.

In this flow, you bypass the cart entirely and create converted orders directly.

#### **Stage 1: Create Converted Order**

* Use the [Create an Order](https://docs.taxcloud.com/api-reference/api-reference/sales-tax-api/orders/create-order) endpoint.  
* You submit a finalized transaction payload that includes:  
  * Line items  
  * Tax amounts (if calculated externally)

This action immediately creates a converted order, which is:

* Final  
* Reported for tax purposes  
* Not editable. To correct one, [void it](https://docs.taxcloud.com/api-reference/api-reference/sales-tax-api/orders/void-order) and upload a corrected order.

> **Tax Rate Compliance**
>
>When using this flow, send the tax you actually collected, and make sure it is as accurate as possible. TaxCloud calculates the tax it reports and files from the order's addresses, line items, TICs, and exemptions. If that differs from the tax you uploaded, the merchant owes the amount TaxCloud calculates. See [Uploading Pre-Calculated Tax](https://docs.taxcloud.com/guides/workflows/order-upload/handling-taxability#uploading-pre-calculated-tax).

#### **Stage 2: Reporting & Filing**

* Just like the Real-time API Flow, these orders enter the reporting pipeline.  
* They appear in your dashboards, audits, and filings.

There is **no cart stage**, no intermediate state, and no recalculation flow in this path.

## **Developer Tips & Common Pitfalls**

* **Never convert before a customer checks out.** This avoids liability for abandoned carts or failed payments.  
* **Treat converted orders as final.**  
* **Minimize reuse of carts.** Create a fresh cart for each transaction. It keeps state management simple.  
* **Monitor for duplicate cart conversion.** Re-converting the same cart can result in duplicate tax liabilities.

## **Conclusion**

Mastering the transaction lifecycle in TaxCloud means more than just calling the right API endpoints; it’s about understanding how and when your transaction state transitions matter for compliance.