TaxCloud Integration Skill

https://docs.taxcloud.com/openapi.json

https://docs.taxcloud.com/openapi.yaml

https://api.v3.taxcloud.com/tax/connections/{connectionId}

https://docs.taxcloud.com

Which Reference to Read First

references/01-authentication-and-setup.md

references/02-core-concepts.md

references/03-real-time-cart-workflow.md

references/04-order-upload-workflow.md

references/05-refunds-and-credits.md

references/06-tic-codes-and-search.md

references/07-exemption-certificates.md

references/08-address-and-utilities.md

references/09-error-handling.md

references/10-typescript-client.md

references/11-migration-from-v1.md

references/12-nexus-management.md

references/13-integration-patterns.md

Two Core Workflows at a Glance

Real-Time API Flow (online checkout)

POST /carts          → calculate tax, get cartId
  ↓ (customer checks out)
POST /carts/orders   → convert cart → order (completed: true or false)
  ↓ (if deferred)
PATCH /orders/{id}   → set completedDate to lock in filing period

Order Upload Flow (external/imported orders)

POST /orders         → create order directly (with tax amounts you calculated)
  or
POST /orders (kind: "credit") → standalone tax credit not tied to any order

Key Rules to Always Follow

1. completedDate

   drives tax filing period, not

   transactionDate

   . Set it to the date of actual delivery/ownership transfer.
2. Only completed orders create tax liability and appear in filings.
3. One cart/order per unique destination address — TaxCloud does not support multi-destination within a single request.
4. Sending the same

   cartId

   overwrites the existing cart entirely (UPSERT semantics).
5. Never convert a cart before payment is confirmed — it creates irrevocable tax records.
6. Send all transactions to TaxCloud even when tax is zero — no-nexus states still contribute to economic nexus threshold tracking.

7. excludeFromFiling: true

   on imported orders that were already filed elsewhere to prevent double-filing.
8. Direct

   exemptionId

   attach is preferred over

   isExempt: true

   auto-match — auto-match leaves orders "Exempt—No certificate" if no cert is found.

Endpoint Quick Reference

/ping

/carts

/carts/orders

/orders

/orders/{orderId}

/orders/{orderId}

/orders/refunds/{orderId}

/exemption-certificates

/exemption-certificates

/exemption-certificates/{id}

/exemption-certificates/{id}

https://api.v3.taxcloud.com/tax/tic/search

/verify-address

Two API Base URLs

https://api.v3.taxcloud.com/tax/connections/{connectionId}

X-API-KEY

https://api.v3.taxcloud.com/mgmt

https://api.v3.taxcloud.com/tax/health

Security: Server-Side Only

X-API-KEY

POST /api/cart/tax

POST /api/orders

Common Patterns (TypeScript)

// server-side only — never in Vue components
const BASE_URL = `https://api.v3.taxcloud.com/tax/connections/${process.env.TAXCLOUD_CONNECTION_ID}`;
const HEADERS = {
  'X-API-KEY': process.env.TAXCLOUD_API_KEY!,
  'Content-Type': 'application/json',
};

async function taxcloud<T>(path: string, method = 'GET', body?: unknown): Promise<T> {
  const res = await fetch(`${BASE_URL}${path}`, {
    method,
    headers: HEADERS,
    body: body ? JSON.stringify(body) : undefined,
  });
  if (!res.ok) {
    const err = await res.json().catch(() => ({}));
    throw Object.assign(new Error(`TaxCloud ${res.status}: ${err.detail ?? res.statusText}`), { status: res.status, body: err });
  }
  return res.json();
}

references/10-typescript-client.md