- 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 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: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 aconnection.historical-sync-completed event. This indicates data is now available for that data type from our API.
Example:
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.
- 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 that can be force synced right now (see the limits below); passfunctions_to_sync(e.g.["get_orders", "get_inventory"]) to sync specific ones.
cURL
- 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-completedevent for it.
Force Sync Limits
Some data types are synced by signing in to the provider’s website, which includes most carrierget_files syncs. Signing in too often can get the account blocked by the provider, so these limits apply:
- Once every 6 hours. A data type synced through the provider’s website can be force synced at most once every 6 hours, and scheduled syncs count toward that window. Requesting it sooner in
functions_to_syncreturns a429whose error message says when it can be force synced again. - Not supported for some data types. A few data types can’t be force synced at all, such as Royal Mail
get_files. Requesting one infunctions_to_syncreturns a400. - Skipped when you don’t name them. Without
functions_to_sync, data types under either limit are skipped and the rest of the connection syncs as usual. A skipped data type sends noconnection.force-sync-completedevent, and picks up new data on its next scheduled sync.
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_ordersget_inbound_shipmentsget_returnsget_billsget_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_filesget_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.ERP
Available function names (currently NetSuite only):get_sales_ordersget_sales_order_shipmentsget_purchase_ordersget_purchase_order_receipts
Master data (inventory, items, locations, customers, vendors, employees) is not supported for on-demand syncs. Items and inventory are retrieved in full on a connection’s first sync, and all master data stays current through the regular sync schedule. To refresh it sooner, use a force sync.
Usage
There are four endpoints for managing on-demand syncs:
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:ISO 8601 timestamp marking the start of the time window to sync (e.g.,
2025-12-01T00:00:00Z).ISO 8601 timestamp marking the end of the time window to sync (e.g.,
2026-01-01T00:00:00Z).The data-fetching function to run. Must be one of the values listed in Supported Functions.
400 response with a message saying why, for example:
- Create via API
- Create via Dashboard
Checking Sync Job Status
Use the sync jobid returned from the create call (data.id in the response) to check progress. The response includes a status field with one of the following values:
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 (data.id in the response):Cancelling a Sync Job
If a sync job is no longer needed, you can cancel it before it completes. Only jobs in theopen state can be cancelled.
- Cancel via API
- Cancel via Dashboard
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
openstate, 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 theopenstate 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:
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-stuckevent. Itslatest_datafield 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 aconnection.sync-job-stuckevent. Stuck jobs do not resume on their own — if a job becomes stuck, reach out to us and we’ll investigate.
What About Writes?
Writes don’t wait for a sync. When you create or update a resource viaPOST or PUT, Trackstar forwards the request to the integration in real time and returns its response immediately. See Writing Data for details.


