Skip to main content

Refresh Orders from Faire (Tracked)

POST 
/api/faire/instances/:integrationInstance/orders/refresh-tracked

Dispatches a background job that walks Faire's /api/v2/orders endpoint and upserts faire_orders + faire_order_line_items. Returns immediately with a tracked job log ID — progress is visible via the tracked job log endpoints.

Authorization

Any valid API token can call this endpoint — no specific scope required. Manage tokens.

Mirrors the products tracked refresh (/refresh-tracked on the products endpoint) so the same UX and progress reporting (synced_orders list, orders_fetched/saved counters) drives the orders refresh modal.

Path Parameters:

  • integrationInstance — The ID of the integration instance

Body:

  • mode (required) — One of:
    • incremental — Resume from the persisted sync_cursors.orders.cursor_at. Recommended for routine refreshes; cursor is persisted across runs.
    • full — Reset the cursor and walk Faire's full updated_at-min window (slow). Cursor is NOT persisted (so the next incremental run still resumes from where things left off).
    • date_range — Fetch only orders whose updated_at falls between date_from and date_to (inclusive). Cursor is NOT persisted.
  • date_from (required when mode=date_range) — ISO date string (YYYY-MM-DD). Sent to Faire as updated_at_min (start-of-day UTC).
  • date_to (required when mode=date_range) — ISO date string (YYYY-MM-DD). Sent to Faire as updated_at_max (end-of-day UTC). Must be >= date_from.

Response:

  • data.tracked_job_log_id — ID of the dispatched tracked job. Poll /api/tracked-job-logs/:id for progress.
  • message — Human-readable status string.

Validation Errors (422):

  • mode must be one of incremental, full, date_range
  • date_from and date_to are required when mode=date_range
  • date_to must be on or after date_from

Request​

Responses​

OK

Response Headers
    Content-Type