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

You may also include:

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

Sample Request (Python)

1
import requests
2
3
url = "https://api.v3.taxcloud.com/tax/connections/{connectionId}/orders"
4
headers = {
5
    "X-API-KEY": "<your-api-key>",
6
    "Content-Type": "application/json"
7
}
8
9
payload = {
10
    "completedDate": "2024-01-15T09:30:00Z",
11
    "transactionDate": "2024-01-15T09:30:00Z",
12
    "orderId": "my-order-1",
13
    "customerId": "customer-453",
14
    "origin": {
15
        "line1": "323 Washington Ave N",
16
        "city": "Minneapolis",
17
        "state": "MN",
18
        "zip": "55401-2427"
19
    },
20
    "destination": {
21
        "line1": "323 Washington Ave N",
22
        "city": "Minneapolis",
23
        "state": "MN",
24
        "zip": "55401-2427"
25
    },
26
    "lineItems": [
27
        {
28
            "index": 0,
29
            "itemId": "item-1",
30
            "price": 10.75,
31
            "quantity": 1.5,
32
            "tax": {
33
                "amount": 1.31,
34
                "rate": 0.08125
35
            }
36
        }
37
    ]
38
}
39
40
response = requests.post(url, headers=headers, json=payload)
41
42
if response.status_code == 201:
43
    print("Order uploaded successfully")
44
    print(response.json())
45
else:
46
    print(f"Failed to upload order: {response.status_code}")
47
    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 exemptFromFiling 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. If you’re not sure how to calculate tax correctly before uploading, refer to our Handling Taxability and 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 section.