Uploading Orders to TaxCloud

TaxCloud’s API enables you to upload completed orders one at a time, making it ideal for syncing data from external systems, migrating historical records, or automating post-sale compliance. Each request creates a single order, giving you full control over batching, error handling, and tax reporting accuracy.

⚠️Heads up! This guide is intended for uploading finalized or pre-existing orders, such as those from marketplaces, legacy systems, or bulk imports. If you’re creating new orders during checkout, use our Standard Checkout Flow instead to ensure proper tax calculation and exemption handling.

If you want to create, retrieve, and update orders, follow this guide to provide best practices that helps you build a resilient and efficient integration.

Prerequisites

Before you begin, ensure you have the following:

• A TaxCloud account and API credentials.
• Familiarity with making HTTP requests using tools like Postman, cURL, or a programming language of your choice.

Endpoints Overview

TaxCloud provides three key endpoints for managing orders:

Each endpoint is designed for single-order processing, simplifying the workflow and ensuring accuracy when handling tax compliance.

Integration Steps

Create the Order

To upload a new order, call the create-order endpoint. Each request creates one order at a time.

1
-X POST https://api.v3.taxcloud.com/tax/connections/25eb9b97-5acb-492d-b720-c03e79cf715a/orders 
2
    H "X-API-KEY: <apiKey>" 
3
    -H "Content-Type: application/json" 
4
    -d '{
5
  "completedDate": "2024-01-15T09:30:00Z",
6
  "currency": {},
7
  "customerId": "customer-453",
8
  "destination": {
9
    "city": "Minneapolis",
10
    "line1": "323 Washington Ave N",
11
    "state": "MN",
12
    "zip": "55401-2427"
13
  },
14
  "lineItems": [
15
    {
16
      "index": 0,
17
      "itemId": "item-1",
18
      "price": 10.75,
19
      "quantity": 1.5,
20
      "tax": {
21
        "amount": 1.31,
22
        "rate": 0.08125
23
      }
24
    }
25
  ],
26
  "orderId": "my-order-1",
27
  "origin": {
28
    "city": "Minneapolis",
29
    "line1": "323 Washington Ave N",
30
    "state": "MN",
31
    "zip": "55401-2427"
32
  },
33
  "transactionDate": "2024-01-15T09:30:00Z" 
34
}'

If the orderID for your new order already exists in our system, you’ll receive a 400 Bad request response.

Taxability

Assign a TIC to each line item in the items array to ensure correct tax treatment. If omitted, the default TIC set during your integration will apply. See the TaxCloud TIC reference for the full list.

Order exemptions

To exclude an order from tax returns and compliance reports, set excludeFromFiling to true. This is useful for orders processed through other systems or involving tax-exempt customers. Ensure any applicable customer exemption settings are also configured.

Customer Exemptions

You can use one of the following methods to associate an order with an exemption certificate for tax-exempt customers:

• Pass a exemptionID to reference a stored certificate.
• Let TaxCloud auto-match an existing certificate on file.
• Or, omit exemptionId now and upload the certificate later.

Make sure exemption settings are correctly configured at the customer level to apply exemptions accurately. In all cases, be sure to set isExempt: true on the order, even when TaxCloud auto-matches an existing certificate or you plan to add one later.

Key Notes:

• orderID must be unique within your account.
• Set exemptFromFiling to true if the order has already been filed elsewhere to prevent TaxCloud from duplicating the filing.
• Orders are created one at a time. If you need to ingest multiple orders, implement batching logic on the client side and process them sequentially.

Update the Order

Use the update-order endpoint to change the completedDate of an existing order. This may be necessary if the order’s completion date was not set when the cart was converted to an order.

1
-X PATCH https://api.v3.taxcloud.com/tax/connections/<connectionID>/orders/<orderId>
2
-H "X-API-KEY
3
H "Content-Type: application/json" 
4
-d '{
5
  "completedDate": "2024-01-15T09:30:00Z"
6
}'

Retrieving an Order

The PUT endpoint response includes your order details, but you may also call the get-order endpoint after creating an order to verify the details and ensure the data was stored as expected. This can be especially useful for validation, reporting, or troubleshooting workflows.

Implement Error Handling

TaxCloud provides clear error messages, making it easier to handle issues programmatically. Implement proper error handling and retries with exponential backoff for transient failures.

Common Error Responses:

• 400 Bad Request: Indicates invalid input. Double-check your payload.
• 422 Unprocessable Entity Error: Some properties of the order are missing.
• 500 Internal Server Error: Temporary server issue. Implement retry logic.

Best Practices

• Optimize Bulk Uploads: Since TaxCloud only supports single order creation per request, implement client-side batching to handle large imports.
• Error Handling: Implement robust error handling with retries for network failures.
• Use Exempt From Filing: Set exemptFromFiling to true for orders already filed elsewhere, preventing duplicate filing.

Conclusion

Uploading orders to TaxCloud is a straightforward process that ensures accurate tax compliance.By leveraging the get-order and update-order endpoints, you can build resilient integrations that handle order ingestion efficiently. For more details and advanced configurations, visit the TaxCloud API Reference.