Convert Carts to Orders

After your customer has finished checking out, it’s time to finalize the transaction by turning the cart into an official order. This is a crucial step; once an order is created, it becomes part of your taxable record and is eligible for reporting and filing in TaxCloud.

We call this process Converting the order.

Create an order from a cart

Having already created a valid cart using the carts endpoint with its valid cartID, you can now convert it into an order using the orders endpoint.

This tells TaxCloud:

The sale actually happened.
The tax should now be considered real.
The transaction should be included in your return (if marked completed).

The fastest way is to complete the order at the time of creation by setting completed: true.

Sample Request (Python)

1 import requests
2 connection_id = “your-connection-id”
3 api_key = “your-api-key”
4 url = f”https://api.v3.taxcloud.com/tax/connections/{connection_id}/carts/orders” 
5 headers = {“X-API-KEY”: api_key, “Content-Type”: “application/json”}
6 payload = {
7 “orderId”: “order-2021”,
8 “cartId”: cart_id,
9 “completed”: True
10 }
11 
12 response = requests.post(url, json=payload, headers=headers)
13 
14 if response.status_code == 201:
15     print("Order created successfully")
16 
17     data = response.json()
18     
19     connection_id = data.get("connectionId")
20     transaction_date = data.get("transactionDate")
21     
22     print(f"Connection ID: {connection_id}")
23     print(f"Transaction Date: {transaction_date}")
24     
25     print("Full Response:")
26     print(data)
27 
28 else:
29     print("Error creating order")
30     print(response.status_code, response.text)

Regarding orderID

Make sure the orderID is unique for this connection. However, if an order doesn’t upload successfully, the orderID can be reused.

What happens when `completed: true`?

TaxCloud immediately marks the order as finalized, which means:

It will show up in your order history.
It becomes part of your tax liability.
It will be included in your filing cycle, if enabled.

Delaying order completion

If you don’t want to complete the order right away, for example, if you’re waiting on payment, shipment, or fraud checks, you can set completed: false during creation. The order will be stored but won’t be reported yet.

Later, you can PATCH the order to add a completedDate. Until then, the order is in a “pending” state.

Use cases for delayed complete

Cash-basis accounting: You want to recognize tax only after payment clears.
Fulfillment-based workflows: You prefer to trigger tax liability only when items ship.
Pre-orders or subscriptions: Orders may sit in draft for days or weeks before becoming active.

Update an order later

Use this PATCH endpoint when you’re ready to finalize:

$ PATCH https://api.v3.taxcloud.com/tax/connections/{connectionId}/orders/{orderId}
> Headers:
> X-API-KEY: your-api-key
> Content-Type: application/json
> Body:
> {
> “completedDate”: “2024-01-15T09:30:00Z”
> }

This marks the order as complete and locks in the tax.

Important

Orders that have no completedDate are not included in tax filings.

Bulk order creation

If you’re uploading orders from a third-party system or capturing marketplace sales (where no cart existed), don’t use the real-time API workflow. Instead, use the upload orders endpoint directly. See the Creating Orders Without Carts guide for that workflow.

Common mistakes

Using a duplicate orderID: Must be unique per connection.
Forgetting to complete: No tax is reported unless completed: true or a completedDate is set.
Passing the wrong cartID: Only carts created under the same connection can be used.
Misinterpreting “order” as “invoice”: Think of it as “taxable transaction” instead.

Best practices

Complete the order immediately if your checkout process is real-time and complete.
Defer order completion if your flow includes manual approval, fraud screening, or fulfillment delay.
Always store the orderId in your system to match TaxCloud reports later.
Use ISO 8601 for all completedDate values (e.g. 2025-07-01T16:00:00Z).

Next step

Once the cart is created and converted, your order is now on record and ready for reporting. Review Testing and Going Live to verify data in the dashboard, separate test versus production keys, and walk through the final launch checklist.