Skip to main content

List Fulfillments

GET 
/api/storefront/instances/:id/fulfillments

The shipments SKU.io has pushed, or tried to push, to this store. One row per SKU.io sales order fulfillment that reached this connection, newest first.

Not yet available to API tokens

This endpoint currently requires session authentication; Personal Access Token scope support is in progress.

Row shape: status is pending, submitted or failed; external_id is the store's own shipment id (null until the store accepts it); error carries the store's refusal on a failed row; lines is the SKU/quantity array that was sent, with bundle components folded back into the bundle SKU the buyer ordered; submitted_at is set only once the store accepted it.

Row cross-links. storefront_order_route points at the mirrored store order this shipment belongs to and sales_order_route at the SKU.io sales order behind it (null when the shipment is not tied to one). Both are relative in-app link paths — append them to your SKU.io base URL to open the record; they are navigation hints, not API endpoints. storefront_order_id, sales_order_id and sales_order_fulfillment_id carry the same targets as raw ids. order_number, order_external_id and customer_name are denormalised from the store order for display.

Filters:

  • filter[search] — fuzzy match across the store shipment id, the tracking number, the carrier, and the order's number and store id, plus an exact match on the row id when the term is all digits (so a tracking number starting with a digit never drags in row 1). Narrow it with the top-level search_columns (comma list of id, external_id, tracking_number, carrier, order.order_number, order.external_id) and force = instead of LIKE for chosen columns with search_strict_columns.
  • filter[status] — pending, submitted or failed (text operators apply, so filter[status.is_one_of]=submitted,failed works).
  • filter[status_in] — a comma-separated status list, for a plain multi-select.
  • filter[external_id] (store shipment id), filter[carrier], filter[service], filter[tracking_number], filter[order_number] (matched on the related store order) — text.
  • filter[id], filter[storefront_order_id], filter[sales_order_id] — numeric. sales_order_id resolves through the SKU.io fulfillment, falling back to the store order's own sales order, so it matches whichever link exists.
  • filter[shipped_at], filter[submitted_at], filter[created_at], filter[updated_at] — date/time.

Operator syntax — every filter below also accepts filter[<field>.<operator>]=<value>; the bare filter[<field>]=<value> form is the implicit is.

  • Text operators: contains, does_not_contain, is, is_not, is_one_of, is_not_one_of, starts_with, does_not_start_with, ends_with, does_not_end_with, is_empty, is_not_empty.
  • Numeric operators: is, is_not, is_one_of, is_not_one_of, greater_than, less_than, greater_than_or_equal, less_than_or_equal, between (comma-separated pair), is_empty, is_not_empty.
  • Date/time operators: is, is_not, before, after, on_or_before, on_or_after, between, is_empty, is_not_empty, today, yesterday, tomorrow, past_week, past_month, past_year, next_week, next_month, next_year, days_ago, days_from_now, past_days, next_days (the last four take a number of days).
  • is_one_of / is_not_one_of take a comma-separated list.

filter_groups takes a base64-encoded JSON tree of the same filter keys, so conditions can be combined with AND/OR and nested groups: {"conjunction":"and","children":[{"type":"condition","condition":{"column":"status.is","operator":"is","value":"variance"}}]}. A tree that references a key not listed here is rejected rather than silently ignored.

Sorting: sort= id, external_id, status, carrier, service, tracking_number, shipped_at, submitted_at, created_at, updated_at. Prefix with - for descending. Default: -id (newest first).

Pagination: page (default 1) and per_page (default 10, clamped to 1-200). The response is a paginated envelope: data, current_page, last_page, per_page, total, from, to.

Authentication: Bearer token (session or PAT).

Request​

Responses​

OK

Response Headers
    Content-Type