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

# Creating Orders

TaxCloud’s Sales Tax API allows you to upload completed orders individually, making it well-suited for syncing data from external systems, migrating historical records, or automating post-sale compliance tasks. Each API request creates one order at a time, giving you precise control over batching, error handling, and tax reporting accuracy.

The [Create Order endpoint](https://docs.taxcloud.com/api-reference/api-reference/sales-tax-api/orders/create-order) creates **one order per request**. To upload multiple orders, implement client-side batching logic and process each order. You are also allowed to make multiple calls at once.

## Required Fields

Each uploaded order must include:

| Fields | Description |
| :---: | ----- |
| orderId | A unique identifier for the order. This uniqueness is enforced at the connection level. |
| transactionDate | The date the cart was converted to an order in TaxCloud (when the transaction record is initiated)|
| completedDate | The date the order was finalized, meaning ownership of the goods or services has transferred and the transaction is ready to be filed.|
| origin and destination | Address objects with line1, city, state, and zip. |
| lineItems | Each with itemId, price, quantity, and optional tax details. |
| customerId | The ID of the customer who made the order. |
| currency | The currency object, for example `{ "currencyCode": "USD" }`. |

You may also include:

* **excludeFromFiling**: Set to true if the order has already been filed elsewhere and should be excluded from any reports used for filing.

### **Sample Request (Python)**

```py
import requests

url = "https://api.v3.taxcloud.com/tax/connections/{connectionId}/orders"
headers = {
    "X-API-KEY": "<your-api-key>",
    "Content-Type": "application/json"
}

payload = {
    "completedDate": "2024-01-15T09:30:00Z",
    "transactionDate": "2024-01-15T09:30:00Z",
    "orderId": "my-order-1",
    "customerId": "customer-453",
    "currency": {"currencyCode": "USD"},
    "origin": {
        "line1": "323 Washington Ave N",
        "city": "Minneapolis",
        "state": "MN",
        "zip": "55401-2427"
    },
    "destination": {
        "line1": "323 Washington Ave N",
        "city": "Minneapolis",
        "state": "MN",
        "zip": "55401-2427"
    },
    "lineItems": [
        {
            "index": 0,
            "itemId": "item-1",
            "price": 10.75,
            "quantity": 1.5,
            "tax": {
                "amount": 1.31,
                "rate": 0.08125
            }
        }
    ]
}

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

if response.status_code == 201:
    print("Order uploaded successfully")
    print(response.json())
else:
    print(f"Failed to upload order: {response.status_code}")
    print(response.text)
```

This Python request sends a single completed order to TaxCloud’s API. If successful, you receive a confirmation message along with the order ID. You can then verify the order by fetching it via the get-order endpoint.

## Best Practices for Managing Uploaded Orders

* **Implement Client-Side Batching**: Each request creates only one order. To improve throughput, send multiple requests in parallel and rely on TaxCloud’s built-in rate limiting to manage concurrency.  
* **Mark Orders as Exempt When Necessary**: If you’re uploading orders that were filed in another system, always set `excludeFromFiling` to true. This prevents duplicate filing by TaxCloud.  
* **Avoid Recalculating Tax for Uploaded Orders**: The `create-order` endpoint assumes you’ve already calculated and applied tax. TaxCloud still calculates the tax it files; see [Uploading Pre-Calculated Tax](https://docs.taxcloud.com/guides/workflows/order-upload/handling-taxability#uploading-pre-calculated-tax). If you’re not sure how to calculate tax correctly before uploading, refer to our [Handling Taxability](https://docs.taxcloud.com/guides/workflows/order-upload/handling-taxability) and [Handling Exemptions](https://docs.taxcloud.com/guides/workflows/order-upload/handling-exemptions) sections.

## Next Steps

Once you’ve successfully uploaded an order, the next step is to ensure that the tax treatment of each item is accurate and compliant. Continue to the [Handle Taxability in Uploaded Orders](https://docs.taxcloud.com/guides/workflows/order-upload/handling-taxability) section.