Analytics Order Data sync

Orders API

Your application must expose an HTTP GET endpoint.

Example:

GET https://your-store.com/api/orders

The actual URL is configured in TaxWisp.

API Configuration

The integration is configured with the following information:

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

Configuration Fields

Field	Required	Description
`host`	Yes	Base URL of your application
`endPoints.orders`	Yes	Path to the Orders API
`headers`	No	HTTP headers required by your API
`parameters`	No	Query parameters required by your API

TaxWisp combines host and endPoints.orders.

For example:

host:
https://your-store.com

orders:
 /api/orders

Final URL:
https://your-store.com/api/orders

Authentication

If your Orders API requires authentication, authentication details can be configured as headers or query parameters.

For example:

{
  "headers": {
    "X-Api-Key": "YOUR_API_KEY"
  }
}

TaxWisp will send the configured headers with each request.

Example:

GET /api/orders?page=1 HTTP/1.1
Host: your-store.com
X-Api-Key: YOUR_API_KEY

Your application should use HTTPS and should not return credentials in the API response.

Pagination

TaxWisp sends a page query parameter when requesting orders.

Example:

GET https://your-store.com/api/orders?page=1

The next request will be:

GET https://your-store.com/api/orders?page=2

Each response must include pagination information.

Orders API Response

The Orders API should return the following structure:

{
  "orderData": [
    {
      "id": "16841713156466",
      "createdAt": "2026-05-18T06:48:44Z",
      "updatedAt": "2026-05-18T06:48:45Z",
      "taxExempt": false,
      "customer": {
        "id": "26915021390194",
        "email": "customer@example.com",
        "displayName": "Bulah Adams"
      },
      "lineItems": [
        {
          "id": "45432744116594",
          "quantity": 1,
          "taxable": true,
          "totalPrice": {
            "amount": 729.95,
            "currencyCode": "USD"
          },
          "taxLines": [
            {
              "ratePercentage": 0.0,
              "taxable": false,
              "price": {
                "amount": 0.0,
                "currencyCode": "USD"
              }
            }
          ]
        }
      ],
      "totalPrice": {
        "amount": 744.95,
        "currencyCode": "USD"
      },
      "billingAddress": {
        "city": "Jber",
        "provinceCode": "AK",
        "countryCode": "US"
      },
      "shippingAddress": {
        "city": "Jber",
        "provinceCode": "AK",
        "countryCode": "US"
      }
    }
  ],
  "pageMetadata": {
    "pageNumber": 1,
    "totalPages": 10,
    "totalRecords": 95,
    "currentRecords": 10
  }
}

Order Fields

Field	Type	Required	Description
`id`	String	Yes	Unique and stable order ID
`createdAt`	String	Yes	Order creation timestamp
`updatedAt`	String	Yes	Last order modification timestamp
`taxExempt`	Boolean	Yes	Whether the order is tax exempt
`customer`	Object	No	Customer information
`lineItems`	Array	Yes	Items included in the order
`totalPrice`	Object	Yes	Total order amount
`billingAddress`	Object	No	Billing address
`shippingAddress`	Object	No	Shipping address

Timestamp Format

Timestamps must use ISO-8601 format.

Example:

2026-05-18T06:48:44Z

Customer

{
  "id": "26915021390194",
  "email": "customer@example.com",
  "displayName": "Bulah Adams"
}

Field	Type	Required	Description
`id`	String	Yes	Unique customer ID
`email`	String	No	Customer email
`displayName`	String	No	Customer display name

Line Items

Each order should contain its individual line items.

{
  "id": "45432744116594",
  "quantity": 1,
  "taxable": true,
  "totalPrice": {
    "amount": 729.95,
    "currencyCode": "USD"
  },
  "taxLines": [
    {
      "ratePercentage": 0.0,
      "taxable": false,
      "price": {
        "amount": 0.0,
        "currencyCode": "USD"
      }
    }
  ]
}

Field	Type	Required	Description
`id`	String	Yes	Unique line-item ID
`quantity`	Integer	Yes	Quantity purchased
`taxable`	Boolean	Yes	Whether the line item is taxable
`totalPrice`	Object	Yes	Total price of the line item
`taxLines`	Array	No	Tax information

Money

Monetary values use the following structure:

{
  "amount": 729.95,
  "currencyCode": "USD"
}

Field	Type	Required	Description
`amount`	Number	Yes	Monetary amount
`currencyCode`	String	Yes	ISO currency code

Example:

{
  "amount": 100.50,
  "currencyCode": "USD"
}

Tax Lines

Tax information can be provided through taxLines.

{
  "ratePercentage": 7.5,
  "taxable": true,
  "price": {
    "amount": 54.75,
    "currencyCode": "USD"
  }
}

Field	Type	Required	Description
`ratePercentage`	Number	Yes	Tax rate percentage
`taxable`	Boolean	Yes	Whether the tax line is taxable
`price`	Object	Yes	Tax amount

Addresses

Billing and shipping addresses use the following structure:

{
  "city": "Jber",
  "provinceCode": "AK",
  "countryCode": "US"
}

Field	Type	Required	Description
`city`	String	No	City
`provinceCode`	String	No	State/province code
`countryCode`	String	No	Country code

Pagination Response

The pageMetadata object tells TaxWisp how many pages are available.

{
  "pageMetadata": {
    "pageNumber": 1,
    "totalPages": 10,
    "totalRecords": 95,
    "currentRecords": 10
  }
}

Field	Type	Description
`pageNumber`	Integer	Current page number
`totalPages`	Integer	Total number of pages
`totalRecords`	Long	Total number of orders
`currentRecords`	Integer	Number of orders in the current page

Complete Request and Response Example

Request

GET https://your-store.com/api/orders?page=1
X-Api-Key: YOUR_API_KEY

Response

{
  "orderData": [
    {
      "id": "16841713156466",
      "createdAt": "2026-05-18T06:48:44Z",
      "updatedAt": "2026-05-18T06:48:45Z",
      "taxExempt": false,
      "customer": {
        "id": "26915021390194",
        "email": "customer@example.com",
        "displayName": "Bulah Adams"
      },
      "lineItems": [
        {
          "id": "45432744116594",
          "quantity": 1,
          "taxable": true,
          "totalPrice": {
            "amount": 729.95,
            "currencyCode": "USD"
          },
          "taxLines": [
            {
              "ratePercentage": 0.0,
              "taxable": false,
              "price": {
                "amount": 0.0,
                "currencyCode": "USD"
              }
            }
          ]
        }
      ],
      "totalPrice": {
        "amount": 744.95,
        "currencyCode": "USD"
      },
      "billingAddress": {
        "city": "Jber",
        "provinceCode": "AK",
        "countryCode": "US"
      },
      "shippingAddress": {
        "city": "Jber",
        "provinceCode": "AK",
        "countryCode": "US"
      }
    }
  ],
  "pageMetadata": {
    "pageNumber": 1,
    "totalPages": 1,
    "totalRecords": 1,
    "currentRecords": 1
  }
}

Important Integration Requirements

Stable Order IDs

Every order must have a stable and unique id.

For example:

16841713156466

The same order must return the same ID on subsequent API requests.

Stable Line Item IDs

Each line item should have a stable id.

Accurate Timestamps

createdAt should represent when the order was created.

updatedAt should represent the latest modification time of the order.

If an order changes, its updatedAt value should be updated.

Valid JSON

The endpoint must always return valid JSON using the documented response structure.

HTTPS

The Orders API should be accessible over HTTPS.

HTTP Status Codes

Successful requests should return:

200 OK

Authentication failure:

401 Unauthorized

Access denied:

403 Forbidden

Server-side failure:

500 Internal Server Error

Recommended API Behavior

For reliable synchronization, we recommend that your Orders API:

Support GET requests.
Support the page query parameter.
Return paginated results.
Return stable order IDs.
Return accurate createdAt and updatedAt timestamps.
Return monetary values with amount and currencyCode.
Use HTTPS.
Require authentication.
Return standard HTTP status codes.
Return only the requested page.
Keep response times reasonably low.

Future Incremental Synchronization

The initial integration uses page-based synchronization.

TaxWisp may support incremental synchronization using the updatedAt timestamp.

For example:

GET /api/orders?page=1&updatedAfter=2026-05-18T00:00:00Z

This allows TaxWisp to request only orders that have been created or updated since the previous synchronization.

If your API already supports filtering by update time, this can be incorporated into the integration.

Summary

The integration requires your application to expose a single Orders API:

GET /your/orders/endpoint

TaxWisp handles pagination, synchronization, and processing of the returned order data. Your application is responsible for exposing the Orders API and returning data in the documented format.

Analytics Order Data sync

Orders API​

API Configuration​

Configuration Fields​

Authentication​

Pagination​

Orders API Response​

Order Fields​

Timestamp Format​

Customer​

Line Items​

Money​

Tax Lines​

Addresses​

Pagination Response​

Complete Request and Response Example​

Request​

Response​

Important Integration Requirements​

Stable Order IDs​

Stable Line Item IDs​

Accurate Timestamps​

Valid JSON​

HTTPS​

HTTP Status Codes​

Recommended API Behavior​

Future Incremental Synchronization​

Summary​

Orders API

API Configuration

Configuration Fields

Authentication

Pagination

Orders API Response

Order Fields

Timestamp Format

Customer

Line Items

Money

Tax Lines

Addresses

Pagination Response

Complete Request and Response Example

Request

Response

Important Integration Requirements

Stable Order IDs

Stable Line Item IDs

Accurate Timestamps

Valid JSON

HTTPS

HTTP Status Codes

Recommended API Behavior

Future Incremental Synchronization

Summary