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 a temporary, 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.
• Carts are ephemeral: once a cart is converted to an order, the cart is removed from the system and can’t be retrieved.

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 for a cartID endpoint.

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 for a cartID 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
• Deletes the original Cart from the system

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 later via the Update Order endpoint. The completedDate determines the tax period the order falls into.

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

TaxCloud’s Recommendations

We recommend that that 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 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.

We do however cache carts referenceable for 90 days, and you can provide a custom cartID to reference the cart later. If you reuse the same CartID, the existing cart will be 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.

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 for a cartID endpoint.

This:

• Creates a new Order object
• Finalizes the tax calculation
• Locks the data for reporting

The original Cart is no longer used at this point and is removed from the system. However, orders at this stage remain incomplete except you set the completed field to be true during creation. Alternatively, you can update the order by calling the Update Orders endpoint to set the completedDate field for that order.

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 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

Tax Rate Compliance

When using this flow, you are responsible for ensuring the tax amounts are accurate and compliant. TaxCloud will not validate the input and assumes the transaction is complete.

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.