--- title: "A page of the product catalogue, one row per product" method: GET path: "/api/v1/products/table" tags: ["products"] --- # A page of the product catalogue, one row per product `GET /api/v1/products/table` ## Request - Base URL: `https://api.app.tightly.io` - URL: `https://api.app.tightly.io/api/v1/products/table` - Auth: HTTP bearer A page of products with the catalogue fields an integrator syncs on: title, vendor, category, department, `num_variants`, status, GTIN, description, currency, HS code, country of origin, unit of measure, `sales_channels`, and `last_updated_at` and `last_updated_by`. Figures that differ variant by variant are `{min, max}` pairs, not single numbers: `unit_cost`, `sell_price`, `weight`, `length`, `width` and `height`. `variant_options` is the option map `{name: [values]}` and `gallery_images` the image list. Paging is `offset` and `limit`, limit at most 10,000 and 8 by default. Four counts come back with the rows: `products_count` and `size` for this page, `filtered_max_size` for the filtered set and `max_size` for the catalogue. Page on `filtered_max_size`, never on `max_size`, or a filtered walk never ends. Narrow with `filter_args`: product_id, vendor, category, department, product_status, sales_channel_id, country_of_origin and collection_id take `eq` and `in`; unit_cost and sell_price take `gte` and `lte`. `search` matches title, SKU and vendor. Sort with `sort_args`: comma-separated columns, `-` for descending, bare or `+` for ascending. `export=true` answers a download URL in `data.url` instead of rows. Planning attributes ride along where the PIM holds them: `replenishment_mode` is the declared lifecycle and `is_seasonal` the detected one, `size_curve` is the effective curve, and `planning_gaps` is what planning is missing, each `{field, label, reason, severity}`. Scope: `products:read`. ## Query parameters - `offset` integer - `limit` integer - `search` string - `filter_args` string - `sort_args` string - `export` boolean ## Headers - `Tightly-Version` string ## Response `200` A page of products, with the page's counts and the filtered set's size. `department` is the source NetSuite item Department label, independent of Brand/Category mapping and distinct from native purchasing subsidiary and the merchandise hierarchy Department. It is read-only; null means no source label. Filter with `eq` or `in` using exact labels. A product matches any SKU Department while retaining all its SKU aggregates. - object - `data` GetPimTablePayload - `filtered_max_size` integer, required - `max_size` integer, required - `offset` integer, required - `products_count` integer, required - `rows` PimTableRow[], required - `brand_id` string, nullable - `brand_name` string, nullable - `category` string, nullable - `category_id` string, nullable - `country_of_origin` string, nullable - `currency` string, nullable - `custom_fields` object, nullable - `demand_group_id` string, nullable - `demand_group_lead` string, nullable - `department` string, nullable - `description` string, nullable - `ean` string, nullable - `gallery_images` string[], required - `gtin` string, nullable - `height` object, nullable - `hs_code` string, nullable - `is_seasonal` boolean, nullable - `last_updated_at` string, nullable - `last_updated_by` string, nullable - `length` object, nullable - `missing_required_count` integer, nullable - `num_variants` integer, required - `planning_gaps` object[] - `price_band` string, nullable - `price_band_reason` object, nullable - `price_band_source` string, nullable - `product_id` string, required - `product_status` string, nullable - `product_title` string, nullable - `replenishment_mode` string, nullable - `sales_channels` PimSalesChannel[], required - `id` string, required - `name` string, required - `sell_price` object, nullable - `selling_window_end` string, nullable - `selling_window_start` string, nullable - `size_curve` object, nullable - `unit_cost` object, nullable - `uom` string, nullable - `upc` string, nullable - `variant_options` object, required - `vendor` string, nullable - `weight` object, nullable - `weight_unit` string, nullable - `width` object, nullable - `size` integer, required - `message` object: severity, service and desc. ## Other responses - `400`: offset or limit is outside its range, or filter_args is not valid JSON. - `401`: No usable key: malformed, unknown, revoked, expired or stopped. One refusal covers all five, because telling a caller which is which maps the surface for them. - `403`: The key may not reach this operation. `scope_missing` when the key does not hold Products; `ip_not_allowed` when the caller's address is outside the key's allowlist. `plan_excludes` when the organisation's plan does not include the public API itself, which is sold with Essentials and is asked of every key minted under that gate. A key minted before the gate existed is never refused by it, whatever the plan holds. Products is ungated, so that is the only plan reason served here. - `429`: The key has spent its allowance for this minute. 600 reads and 120 writes a minute, counted per key, refused calls included. `Retry-After` says how long to wait. - `503`: The database is briefly out of reach, which is what a failover or a full connection pool looks like from outside. Wait the seconds `Retry-After` names and send the request again. A read is safe to repeat. A write is not, because the connection was lost in the middle of it, so read the object back before sending it a second time. Branch on the status rather than on `code`, which is `POSTGRES_UNAVAILABLE` from one of the two seams that raise this and `SERVICE_UNAVAILABLE` from the other. --- [API](https://skmtc.dev/tightly/apis/tightly-api.md) · [All operations](https://skmtc.dev/tightly/apis/tightly-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tightly/apis/tightly-api/revisions/199f7eb35afb?raw)