> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.taxcloud.com/api-v-3/guides/workflows/real-time-api/convert-carts-to-orders/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.taxcloud.com/_mcp/server.

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

```py
import requests
connection_id = "your-connection-id"
api_key = "your-api-key"
cart_id = "your-cart-id"
url = f"https://api.v3.taxcloud.com/tax/connections/{connection_id}/carts/orders"
headers = {"X-API-KEY": api_key, "Content-Type": "application/json"}
payload = {
    "orderId": "order-2021",
    "cartId": cart_id,
    "completed": True
}

response = requests.post(url, json=payload, headers=headers)

if response.status_code == 201:
    print("Order created successfully")

    data = response.json()
    
    connection_id = data.get("connectionId")
    transaction_date = data.get("transactionDate")
    
    print(f"Connection ID: {connection_id}")
    print(f"Transaction Date: {transaction_date}")
    
    print("Full Response:")
    print(data)

else:
    print("Error creating order")
    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.

> **Tip**
>
> If the completion date is at or before the request time (for example, a digital download delivered at checkout), pass `completedDate` directly in the `POST /carts/orders` request to lock in the tax in one call and skip the follow-up PATCH. A future `completedDate` is rejected with a `422`.
>
> You don’t need to send `completed` as well. When `completedDate` is present, it takes precedence over `completed`, so an order created with both `completed: false` and a `completedDate` is still complete.
>
> When fulfillment happens later — you know the ship date but it has not occurred yet — create the order with `completed: false` and add the `completedDate` by PATCH once it does.

### 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](https://docs.taxcloud.com/api-reference/api-reference/sales-tax-api/orders/update-order) when you’re ready to finalize:

```shell
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](https://docs.taxcloud.com/guides/workflows/order-upload/creating-orders) 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](https://docs.taxcloud.com/guides/getting-started/testing-and-going-live) to verify data in the dashboard, separate test versus production keys, and walk through the final launch checklist.