orders

list sales orders

Every order Tightly holds, whatever it came in by: a connected channel, a person, a file, this API, an EDI 850 or the buyer portal. status_numbers counts the whole filtered book per lifecycle, not the page, so a total shown above the rows can be relied on. Do not call this to find one order you already have the id for: GET /sales/orders/{order_id} serves that one whole, and this list deliberately carries no address.

Scope: orders:read.

get/api/v1/sales/orders

Request

  • Base URL: https://api.app.tightly.io
  • URL: https://api.app.tightly.io/api/v1/sales/orders
  • Auth: HTTP bearer

Query parameters

product_querystring

Case-insensitive literal match on product name, variant name or SKU. Returns whole orders containing a matching line; units and values remain whole-order totals.

lifecycle'draft' | 'open' | 'allocated' | 'fulfilment_requested' | 'fulfilled' | 'cancelled'

Only orders in this state.

needs_youboolean

Only orders somebody has to answer for: a wholesale draft nobody has confirmed, or an order carrying an open queue row. Not expressible as a lifecycle, which is why it is a filter of its own.

origin'channel' | 'manual' | 'csv' | 'api' | 'edi' | 'portal'

Only orders that came in by this door.

is_wholesaleboolean

True for orders an account placed, false for orders a shopper placed.

trading_partner_idstring

Only orders for this account.

sales_channel_idstring

Only orders on this channel.

location_idsstring

Comma-separated serving warehouse IDs; order header location, not retailer destination door.

commitment_idsstring

Comma-separated current recorded booking commitment IDs; whole orders, once each.

searchstring

Matches an order's name, its reference, or the account it is for.

sincestring date

Only orders placed on or after this day.

offsetinteger

How many orders to skip, for paging.

limitinteger

How many orders to return. Above the maximum the read is REFUSED rather than trimmed: a caller handed 500 of 4,000 rows with no warning has wrong data. filtered_max_size states the book's true size, so a caller can always tell a page from the whole of it.

sort_key'name' | 'customer' | 'origin' | 'state' | 'placed' | 'value' | 'units' | 'channel' | 'location' | 'needs'

Sort the whole filtered book by this column before paging, never only the drawn page. Omitted, wholesale drafts sort first, then orders by when they were placed, newest first.

sort_dir'asc' | 'desc'

Direction for sort_key. Ignored without it.

Headers

Tightly-Versionstring
Example:2026-11

The date train to answer on. One train exists today, 2026-11, the one this reference describes and the one every key is minted on, so the call answers on it with or without this header. Send it anyway, so a client built now names its train from the start.

Response

The page of orders, and the counts the head ties to.

dataobject

The house paging shape (offset, size, max_size, filtered_max_size, rows), status_numbers and as_of.

messageobject

severity, service and desc.

Changes

No recorded changes to this operation across all 1 revision of this API.