Syncing Data

Trackstar keeps your data fresh by periodically pulling from each connected integration, normalizing the results, and making them available through the Trackstar API and webhooks. There are three ways a sync can happen:

Scheduled syncs run automatically at predefined intervals. Most of your data arrives this way.
Force syncs are manually triggered syncs of recent data, when you don’t want to wait for the next scheduled sync.
On-demand syncs backfill a specific data type over a custom time window, for example to pull historical data from before the initial sync.

Sync Types at a Glance

	Scheduled	Force	On-Demand
How it starts	Automatically, on a recurring schedule	Dashboard sync button, or `POST /connections/sync`	Dashboard, or `POST /connections/on-demand-syncs`
Time window	From the last sync to now	From the last sync to now	Custom `start_time` to `end_time`
Scope	Every data type, each on its own schedule	All data types, or specific ones via `functions_to_sync`	One function per sync job
Completion signal	Resource webhooks (e.g. `order.updated`)	`connection.force-sync-completed`	`connection.sync-job-completed`
Best for	Staying up to date	Getting fresh data right now	Backfilling historical data

Scheduled Syncs

Default Sync Frequencies

Different data types are synchronized at varying intervals to balance data freshness and system performance. Below is a breakdown of the default synchronization frequencies:

API	Data Type	Sync Frequency
WMS	Inventory	Hourly
WMS	Inbound Shipments	Hourly
WMS	Orders	Hourly
WMS	Products	Hourly
WMS	Returns	Hourly
WMS	Bills	Hourly
WMS	Inventory Ledger	Hourly
WMS	Shipping Methods	Every 12 hours
WMS	Warehouses	Every 12 hours
WMS	Warehouse Customers	Every 12 hours
WMS	Warehouse Locations	Every 12 hours
Cart	Orders	Hourly
Cart	Products	Hourly
Cart	Warehouses	Every 12 hours
Carrier	Invoice Line Items	Daily

Note: These frequencies are default settings and can be customized per connection. If you need to modify the synchronization interval for a particular data type or connection, please contact us for assistance.

Initial Sync Behavior

Upon establishing a new connection, Trackstar performs an initial synchronization that retrieves data from the past 30 days by default. This historical sync ensures that your system starts with a comprehensive dataset. To adjust the historical lookback window, go to your dashboard’s Connections Settings. New connections can sync up to three years of historical data. When each data type (e.g. inventory, orders) has finished syncing for the first time, we will send a connection.historical-sync-completed event. This indicates data is now available for that data type from our API. Example:

{
  "connection_id": "connection_id",
  "data": {
    "newest_data_date": "2025-05-01T00:00:00Z",
    "oldest_data_date": "2025-01-01T00:00:00Z",
    "resource": "orders"
  },
  "event_type": "connection.historical-sync-completed",
  "integration_name": "integration_name",
  "integration_type": "wms"
}

You can also check the sync status of a connection programmatically by calling GET /connections/{id}.

Force Syncs

A force sync is a manually triggered sync. It runs the same sync a schedule would, just immediately, without waiting for the next scheduled run.

A force sync does not sync historical data. To backfill a custom time window, use an on-demand sync.

You can trigger a force sync two ways:

Via the Dashboard: Go to the Connections Page, click on the connection you want to sync, and press the resync button for the desired data type.
Via the API: Call POST /connections/sync. By default it syncs every data type on the connection; pass functions_to_sync (e.g. ["get_orders", "get_inventory"]) to sync specific ones.

cURL

curl --request POST \
  --url https://production.trackstarhq.com/connections/sync \
  --header 'x-trackstar-api-key: your_api_key' \
  --header 'x-trackstar-access-token: your_access_token' \
  --header 'Content-Type: application/json' \
  --data '{
    "functions_to_sync": ["get_orders", "get_inventory"]
  }'

A few things to know:

The sync starts right away, but it may take a few minutes for new data to appear as it completes in the background.
If a data type is already mid-sync, the force sync leaves it alone rather than starting a duplicate.
When the sync finishes for a data type, Trackstar sends a connection.force-sync-completed event for it.

On-Demand Syncs

On-demand syncs let you trigger a backfill of a specific data type over a custom time window, outside of Trackstar’s normal sync schedule. They’re useful for re-syncing historical data or pulling a longer window of data than the default 30-day initial sync.

Supported Functions

Support is rolled out per integration + function. If you’d like support added for an integration or function, reach out to us and we’ll look into enabling it.

WMS

Available function names:

get_orders
get_inbound_shipments
get_returns
get_bills
get_inventory_ledger

get_inventory and get_products are intentionally not supported for on-demand syncs. Inventory always syncs as a full snapshot, and the full product catalog is retrieved on a connection’s first sync, so an on-demand sync over a custom range would not change what gets pulled. To refresh either, use a force sync or wait for the next scheduled sync.

Carrier

Available function names:

get_invoice_line_items

Cart

Available function names:

get_orders

get_products is intentionally not supported for on-demand syncs. The full product catalog is retrieved on a connection’s first sync, so an on-demand sync over a custom range would not change what gets pulled. To refresh products, use a force sync or wait for the next scheduled sync.

Usage

There are three endpoints for managing on-demand syncs:

Operation	Method	Path
Create a sync job	`POST`	`/connections/on-demand-syncs`
Get sync job status	`GET`	`/connections/on-demand-syncs/{sync_job_id}`
Cancel a sync job	`POST`	`/connections/on-demand-syncs/{sync_job_id}/cancel`

Like all Trackstar API calls, you’ll need to authenticate using your API key and the access token for the specific connection. You can manage on-demand syncs either through the API directly or through the Trackstar dashboard. Each section below shows both options — pick whichever fits your workflow.

Creating a Sync Job

The following parameters are required when creating a sync job via the API:

string

required

ISO 8601 timestamp marking the start of the time window to sync (e.g., 2025-12-01T00:00:00Z).

string

required

ISO 8601 timestamp marking the end of the time window to sync (e.g., 2026-01-01T00:00:00Z).

string

required

The data-fetching function to run. Must be one of the values listed in Supported Functions.

If you attempt to start an on-demand sync for an integration + function combination that isn’t currently enabled, you will receive a 400 response with the message:

On-demand sync is not enabled for {integration_name} {function_name}

Create via API
Create via Dashboard

import requests

TRACKSTAR_API_KEY = "your_api_key"
ACCESS_TOKEN = "your_access_token"

url = "https://production.trackstarhq.com/connections/on-demand-syncs"
headers = {
    "x-trackstar-api-key": TRACKSTAR_API_KEY,
    "x-trackstar-access-token": ACCESS_TOKEN,
    "Content-Type": "application/json"
}

payload = {
    "start_time": "2025-12-01T00:00:00Z",
    "end_time": "2026-01-01T00:00:00Z",
    "function_name": "get_orders"
}

response = requests.post(url, headers=headers, json=payload)
response.raise_for_status()
sync_job = response.json()

print(sync_job)

const axios = require('axios');

const TRACKSTAR_API_KEY = 'your_api_key';
const ACCESS_TOKEN = 'your_access_token';

const url = 'https://production.trackstarhq.com/connections/on-demand-syncs';
const headers = {
  'x-trackstar-api-key': TRACKSTAR_API_KEY,
  'x-trackstar-access-token': ACCESS_TOKEN,
  'Content-Type': 'application/json'
};

const payload = {
  start_time: '2025-12-01T00:00:00Z',
  end_time: '2026-01-01T00:00:00Z',
  function_name: 'get_orders'
};

const response = await axios.post(url, payload, { headers });

console.log(response.data);

curl --request POST \
  --url https://production.trackstarhq.com/connections/on-demand-syncs \
  --header 'x-trackstar-api-key: your_api_key' \
  --header 'x-trackstar-access-token: your_access_token' \
  --header 'Content-Type: application/json' \
  --data '{
    "start_time": "2025-12-01T00:00:00Z",
    "end_time": "2026-01-01T00:00:00Z",
    "function_name": "get_orders"
  }'

Open the Connections page and click into the connection you want to sync.
In the connection details drawer, switch to the On-Demand Syncs tab.
Click Create.
In the modal, pick a function, choose a start and end time (interpreted as your local timezone and converted to UTC on submit), and click Create Sync Job.

The new job will appear at the top of the list with status open.

Checking Sync Job Status

Use the sync_job_id returned from the create call to check progress. The response includes a status field with one of the following values:

Status	Meaning
`open`	The job has been created and is either queued or actively running.
`completed`	The job finished successfully. Synced data is now available via the standard Trackstar API.
`cancelled`	The job was cancelled before it could finish (see Cancelling a Sync Job).
`stuck`	The job stopped making progress for an extended period (see Stuck Syncs).

A typical successful lifecycle is open → completed. A cancelled job follows open → cancelled, and a job that stops progressing moves open → stuck. The full response also includes id, connection_id, function_name, requested_start_time, requested_end_time, and created_at.

Check via API
Check via Dashboard

Use the sync_job_id returned from the create call:

import requests

TRACKSTAR_API_KEY = "your_api_key"
ACCESS_TOKEN = "your_access_token"
SYNC_JOB_ID = "your_sync_job_id"

url = f"https://production.trackstarhq.com/connections/on-demand-syncs/{SYNC_JOB_ID}"
headers = {
    "x-trackstar-api-key": TRACKSTAR_API_KEY,
    "x-trackstar-access-token": ACCESS_TOKEN
}

response = requests.get(url, headers=headers)
response.raise_for_status()
status = response.json()

print(status)

const axios = require('axios');

const TRACKSTAR_API_KEY = 'your_api_key';
const ACCESS_TOKEN = 'your_access_token';
const SYNC_JOB_ID = 'your_sync_job_id';

const url = `https://production.trackstarhq.com/connections/on-demand-syncs/${SYNC_JOB_ID}`;
const headers = {
  'x-trackstar-api-key': TRACKSTAR_API_KEY,
  'x-trackstar-access-token': ACCESS_TOKEN
};

const response = await axios.get(url, { headers });

console.log(response.data);

curl --request GET \
  --url https://production.trackstarhq.com/connections/on-demand-syncs/your_sync_job_id \
  --header 'x-trackstar-api-key: your_api_key' \
  --header 'x-trackstar-access-token: your_access_token'

Cancelling a Sync Job

If a sync job is no longer needed, you can cancel it before it completes. Only jobs in the open state can be cancelled.

Cancel via API
Cancel via Dashboard

import requests

TRACKSTAR_API_KEY = "your_api_key"
ACCESS_TOKEN = "your_access_token"
SYNC_JOB_ID = "your_sync_job_id"

url = f"https://production.trackstarhq.com/connections/on-demand-syncs/{SYNC_JOB_ID}/cancel"
headers = {
    "x-trackstar-api-key": TRACKSTAR_API_KEY,
    "x-trackstar-access-token": ACCESS_TOKEN,
    "Content-Type": "application/json"
}

response = requests.post(url, headers=headers)
response.raise_for_status()

print(response.json())

const axios = require('axios');

const TRACKSTAR_API_KEY = 'your_api_key';
const ACCESS_TOKEN = 'your_access_token';
const SYNC_JOB_ID = 'your_sync_job_id';

const url = `https://production.trackstarhq.com/connections/on-demand-syncs/${SYNC_JOB_ID}/cancel`;
const headers = {
  'x-trackstar-api-key': TRACKSTAR_API_KEY,
  'x-trackstar-access-token': ACCESS_TOKEN,
  'Content-Type': 'application/json'
};

const response = await axios.post(url, null, { headers });

console.log(response.data);

curl --request POST \
  --url https://production.trackstarhq.com/connections/on-demand-syncs/your_sync_job_id/cancel \
  --header 'x-trackstar-api-key: your_api_key' \
  --header 'x-trackstar-access-token: your_access_token' \
  --header 'Content-Type: application/json'

In the On-Demand Syncs tab, click the cancel icon at the end of any row whose status is open. The icon only appears for cancellable rows.

Once cancelled, the job stays in the list with status cancelled and the icon disappears.

Interaction with Other Syncs

Asynchronous execution: On-demand sync jobs run in the background. Poll the status endpoint or rely on Trackstar’s existing webhooks (e.g. order.created, order.updated) to know when new data has landed.
Precedence over scheduled syncs: While a sync job is in the open state, the regularly scheduled syncs for that same data type will not run, which can cause its recent data to fall behind. Other data types on the connection keep syncing on their normal schedules. Once no sync jobs remain in the open state for a data type (they complete, are cancelled, or are marked stuck), its scheduled syncs automatically resume from where they left off — so no data is missed, only delayed.

Knowing When Your Data Is Ready

Each kind of sync has its own completion signal:

After you…	Listen for…
Connect a new integration	`connection.historical-sync-completed` per data type
Trigger a force sync	`connection.force-sync-completed` per data type
Create an on-demand sync job	`connection.sync-job-completed` (or `connection.sync-job-stuck`)
Anything — data changed at the source	Webhook events like `order.created` and `order.updated`

More information on our webhooks can be found in the webhooks documentation.

Stuck Syncs

Occasionally a sync stops making progress — for example when the underlying integration’s API is degraded. Trackstar detects this in two places:

Scheduled syncs: if a data type’s regular sync stops making progress, Trackstar sends a connection.schedule-stuck event. Its latest_data field tells you how fresh that data type’s data is, so you know how far behind it may be. Our team is alerted internally and investigates; scheduled syncs resume automatically once the underlying issue is resolved.
On-demand sync jobs: a job that stops making progress for an extended period moves to status stuck, and Trackstar sends a connection.sync-job-stuck event. Stuck jobs do not resume on their own — if a job becomes stuck, reach out to us and we’ll investigate.

Disabled Endpoints

If there are data types your business doesn’t use — say you never handle returns — you can disable those endpoints so they stay out of the way entirely. A disabled endpoint:

Doesn’t sync. Scheduled syncs stop, force syncs skip it, and creating an on-demand sync job for it returns a 400.
Isn’t validated at connect time. End users connecting through Trackstar Link won’t see an attempt to validate permissions for it.
Is omitted from available_actions. It no longer appears in the connection’s available actions.
Rejects writes. Write calls return a 403 (e.g. create_return is disabled for this connection) without reaching the integration. See Writing Data.

Disabled endpoints resolve in two layers:

Org policy: set per integration type (WMS, Cart, Carrier) in the dashboard. Applies to every connection of that type, existing and future.
Per-connection adjustments: on top of org policy, the Magic Link that installs a connection can disable extra endpoints for it, or re-enable org-disabled ones.

Org policy via Dashboard
At install via Magic Link

Go to Connection Settings and open the Disabled Endpoints tab. Toggles are grouped by integration type, and each type’s list is independent — turning off Products for Cart doesn’t affect Products for WMS.

Disabled Endpoints tab in Connection Settings, grouped by integration type

Some endpoints rely on data that another endpoint syncs. If a change would disable an endpoint that a still-enabled one depends on — for example disabling inventory while returns, which uses inventory data, stays on — the change is rejected with an error explaining the conflict.

Re-enabling an endpoint is just removing it from the disabled list: its syncs resume automatically and Trackstar backfills the data it missed.

What About Writes?

Writes don’t wait for a sync. When you create or update a resource via POST or PUT, Trackstar forwards the request to the integration in real time and returns its response immediately. See Writing Data for details.

Home

How-To Guides

Use Cases

Sync Types at a Glance

Scheduled Syncs

Default Sync Frequencies

Initial Sync Behavior

Force Syncs

On-Demand Syncs

Supported Functions

WMS

Carrier

Cart

Usage

Creating a Sync Job

Checking Sync Job Status

Cancelling a Sync Job

Interaction with Other Syncs

Knowing When Your Data Is Ready

Stuck Syncs

Disabled Endpoints

What About Writes?

​Sync Types at a Glance

​Scheduled Syncs

​Default Sync Frequencies

​Initial Sync Behavior

​Force Syncs

​On-Demand Syncs

​Supported Functions

​WMS

​Carrier

​Cart

​Usage

​Creating a Sync Job

​Checking Sync Job Status

​Cancelling a Sync Job

​Interaction with Other Syncs

​Knowing When Your Data Is Ready

​Stuck Syncs

​Disabled Endpoints

​What About Writes?

Sync Types at a Glance

Scheduled Syncs

Default Sync Frequencies

Initial Sync Behavior

Force Syncs

On-Demand Syncs

Supported Functions

WMS

Carrier

Cart

Usage

Creating a Sync Job

Checking Sync Job Status

Cancelling a Sync Job

Interaction with Other Syncs

Knowing When Your Data Is Ready

Stuck Syncs

Disabled Endpoints

What About Writes?