Orders API Setup (Analytics)

TaxWisp provides comprehensive tax exemption reporting, audit logs, and revenue exemption analytics. To power these insights, TaxWisp connects to your ecommerce platform via a secure, read-only Orders API.

This guide explains how to configure TaxWisp to communicate with your custom Orders API endpoint.

---

How It Works

TaxWisp periodically queries your application's order endpoint to retrieve order data (order ID, date, tax amounts, line items, and customer exemption status).

sequenceDiagram
    autonumber
    participant TW as TaxWisp Analytics Worker
    participant Store as Your Ecommerce Orders API
    participant DB as Your Database

    TW->>Store: GET https://your-store.com/api/orders?page=1
    Note over TW,Store: Headers: X-Api-Key: YOUR_API_KEY
    Store->>DB: Query orders (page 1, limit N)
    DB-->>Store: Order records + total count
    Store-->>TW: 200 OK (Orders JSON + pageMetadata)
    Note over TW: TaxWisp ingests & maps tax analytics
    opt More pages exist
        TW->>Store: GET https://your-store.com/api/orders?page=2
        Store-->>TW: 200 OK (Orders JSON + pageMetadata)
    end

---

Configuring the Integration in TaxWisp

1. Log in to your TaxWisp Dashboard.
2. Navigate to Integrations → Analytics Sync.
3. Enter your platform's API connection parameters:

{
  "host": "https://your-store.com",
  "endPoints": {
    "orders": "/api/orders"
  },
  "headers": {
    "X-Api-Key": "YOUR_STORE_API_KEY"
  },
  "parameters": {
    "authToken": "YOUR_OPTIONAL_QUERY_TOKEN"
  }
}

Configuration Fields

Field	Type	Required	Description
host	String	Yes	The base HTTPS URL of your application (e.g., https://api.yourstore.com).
endPoints.orders	String	Yes	The relative path to your Orders API (e.g., /api/v1/orders).
headers	Object	No	Key-value pairs of HTTP headers TaxWisp will send on every request (e.g., X-Api-Key or Authorization: Bearer <token>).
parameters	Object	No	Query parameters appended to every request URL.

---

Security & Network Requirements

1. HTTPS Only: Your endpoint must be served over a secure TLS/HTTPS connection.
2. Read-Only Credentials: Generate an API token on your store that has read-only permissions for orders. Never use administrative write keys.
3. Idempotency & Safe Requests: TaxWisp only issues GET requests to this endpoint. The endpoint must not perform destructive mutations.
4. Rate Limits & Timeouts: Ensure your API can handle bursts of requests during periodic synchronization without dropping connections. A timeout limit of 30 seconds per page is recommended.

---

Verifying the Connection

Once saved in the dashboard, TaxWisp executes a test ping:

1. TaxWisp sends a GET request to ${host}${endPoints.orders}?page=1.
2. TaxWisp validates that:
   • The response status code is 200 OK.
   • The response contains an orders array.
   • The response includes a valid pageMetadata object containing pageNumber, totalPages, and totalRecords.

For full details on the required payload format, JSON schemas, and response structure, see the Analytics Order Data Sync Guide.