Skip to main content

List Faire Orders

GET 
/api/faire/orders

List Faire orders for a specific integration instance.

Tenant resolution (multi-instance safety): Both shapes are accepted, in priority order:

  • filter[integration_instance_ids] (preferred, Amazon-unified plural form; comma-separated CSV — first ID wins)
  • filter[instance_id] (legacy singular)
  • ?instance_id= query string fallback
  • body instance_id (POST/PUT only)

If none resolve to an existing FaireIntegrationInstance the endpoint returns an empty/zeroed payload — it does NOT silently fall back to the first tenant's data.

Empty-paginator response shape (when no instance can be resolved):

{
  "current_page": 1,
  "data": [],
  "total": 0,
  "per_page": 15
}

List Faire orders with rich Spatie QueryBuilder filtering, sorting and pagination. Defaults to Active orders (excludes archived) — mirrors the Purchase Orders bottom-bar pattern. Use filter[archived]=only for archived rows, filter[archived]=all for both.

Query Parameters — Pagination & Sort:

  • instance_id (optional) — Filter to a specific integration instance. Defaults to the first instance.
  • page (default 1), per_page (default 10)
  • sort — Prefix with - for DESC. Default -ordered_at. Allowed: id, ordered_at, shipped_at, delivered_at, created_at, updated_at, total, subtotal, discount_amount, status, retailer_name, retailer_country_code.

Search:

  • filter[search] — AdvancedSearchFilter across display_id, faire_order_id, retailer_name.

Archived Toggle (default-active):

  • filter[archived]= (or omitted) — Active only
  • filter[archived]=only — Archived only
  • filter[archived]=all — Both

Identity / Display:

  • filter[status], filter[display_id], filter[faire_order_id]

Retailer:

  • filter[retailer_name], filter[retailer_country_code], filter[retailer_state]

Money (numeric operators):

  • filter[total], filter[subtotal], filter[discount_amount], filter[currency_code]

Dates (datetime operators — [between], [gte], [lte], [eq]):

  • filter[ordered_at], filter[shipped_at], filter[delivered_at], filter[updated_at], filter[created_at]

Tracking:

  • filter[tracking_number], filter[tracking_carrier], filter[tracking_submission_status] (pending, submitted, failed)

Boolean callbacks:

  • filter[has_sku_order]=true|false — Has a linked SKU.io sales order.
  • filter[has_unmapped_items]=true|false — Has at least one line item without a SKU mapping.
  • filter[pre_start_date_import]=true|false — Order was imported via the pre-start-date flow.

Operator suffixes: combine any text/numeric/datetime filter with operator suffixes via filter[column][operator]=value (e.g. filter[status][is_one_of]=NEW,PROCESSING, filter[total][gte]=100, filter[ordered_at][between]=2026-04-01,2026-05-01).

Response Fields per Order:

  • id, integration_instance_id, faire_order_id, display_id, status
  • retailer_id, retailer_name, retailer_state, retailer_country_code
  • subtotal, discount_amount, total, currency_code (monetary fields are stored as integers in cents)
  • ordered_at, shipped_at, delivered_at, archived_at, created_at
  • tracking_number, tracking_carrier, tracking_submission_status
  • line_items — Loaded via eager-load (see Show Order for the full shape)

Linked SKU.io product on each line item: The per-line sku_product_id, sku_product_route, and sku_product fields resolve through the FaireProductOption → ProductListing → Product chain (matched on faire_variant_id). They are populated only when the variant has been explicitly mapped — either via the Variants Listing page "Map" button, Smart Match, or Bulk Map. String-based SKU matching is intentionally NOT used. A line whose sku happens to match a Product's sku but whose variant has never been mapped will return sku_product_id: null ("Unlinked" in the UI) — the same behaviour as the Shopify line item resource and the Variants Listing page itself.

Request​

Responses​

Successful response