--- title: "List all products" method: GET path: "/companies/{company}/products" tags: ["Products"] --- # List all products `GET /companies/{company}/products` ## Request - Base URL: `https://api.factuarea.com/v1` - URL: `https://api.factuarea.com/v1/companies/{company}/products` - Auth: one of: - HTTP bearer - API key in header `X-API-Key` List products in your catalog with cursor-based pagination. ## Path parameters - `company` string, uuid, required ## Query parameters - `limit` integer - `starting_after` string, uuid - `ending_before` string, uuid - `sku` string - `sku[in]` string: Comma-separated list of values (CSV). - `sku[contains]` string - `name` string - `name[contains]` string - `is_active` boolean - `created[gte]` string, date-time - `created[lte]` string, date-time - `created[gt]` string, date-time - `created[lt]` string, date-time - `price[gte]` number - `price[lte]` number - `price[gt]` number - `price[lt]` number - `in_stock` boolean - `low_stock` boolean - `tag` string - `tag[in]` string: Comma-separated list of values (CSV). - `search` string - `metadata` object ## Headers - `Factuarea-Version` string, date ## Response `200` - object: Cursor-paginated list envelope shared by every v1 listing endpoint. `data` holds the page items; `has_more` signals whether another page exists; `next_cursor` is the cursor to pass back for the following page. Treat it as strictly opaque: send it through verbatim, never parse it and never assume a format — it is not the same across listings, and each listing documents its own cursor parameter. Concrete listings narrow `data` to their resource type via `allOf`. - `data` object[], required: Items on the current page. - `id` string, required - `object` 'product', required - `name` string, required - `sku` string, nullable, required - `price` string, required: Monetary amount as a string with two decimal places (Stripe-style), e.g. "1234.56". - `currency` string, required - `tax_rate` TaxRateRef, required - `id` string, nullable, required - `rate` number, nullable, required - `stock` string, required: Available stock quantity with four-decimal scale. - `item_kind` 'product' | 'service', required: Catalog item kind. - `base_unit` 'C62' | 'KGM' | 'GRM' | 'LTR' | 'MLT' | 'MTR' | 'MTK' | 'HUR' | 'DAY', required: UNECE base unit code. Only the nine measure units can be a base unit (`C62`, `KGM`, `GRM`, `LTR`, `MLT`, `MTR`, `MTK`, `HUR`, `DAY`); a packaging or count unit (`H87`, `XPK`, `XBX`…) can only be the unit of a presentation or a supplier offer. It cannot be edited once the product has history: see `base_unit_change` and `POST /v1/companies/{company}/products/{product}/base-unit-replacement`. - `gross_weight_kg` string, nullable: Gross transport weight in kg per BASE unit (decimal string, up to 4 decimals, greater than 0), packaging included; `null` when unknown. Rejected with 422 `gross_weight_not_allowed` for services and for products whose base unit is a mass unit (`KGM`, `GRM`), where the weight is the quantity itself. A variant weight replaces it for that variant; a fixed presentation may declare its own weight per commercial unit. - `manage_stock` boolean, required: Whether the product participates in document-driven stock movements (invoices, delivery notes). Requires the company `stock_management` module to be enabled. Defaults to `false`. - `gallery` object[], required: Product gallery images. - `index` integer, required: Position of the image in the gallery (0-based). - `url` string, uri, required: Public URL of the image. - `content_type` string, required: MIME type of the image (e.g. `image/jpeg`). - `video` object, nullable, required: Product attached video, or `null` if there is none. - `url` string, uri, required: Public URL of the video. - `content_type` string, required: MIME type of the video (e.g. `video/mp4`). - `is_active` boolean, required - `description` string, nullable, required: Free-text description of the product. - `tags` string[], required: Product classification tags. - `low_stock_threshold` string, nullable, required: Threshold below which stock is considered low, or `null` if not configured. - `presentation_count` integer, required - `variant_count` integer, required - `supplier_offer_count` integer, required - `option_group_count` integer, required: Number of option groups the product declares (active and inactive). Always reported, so a listing that omits `option_groups` for brevity never reads as a plain product. - `configuration_count` integer, required: Number of commercial combinations the product declares (active and inactive). Matches the size of `configurations` returned by the product detail. - `catalog_availability_mode` 'open' | 'closed', required: `open` keeps the Cartesian product of active axes sellable; only configurations with `restricts_availability=true` constrain their own variant. `closed` treats all active configurations as the exact allow-list. - `preferred_supplier_offer_id` string, uuid, nullable, required - `presentations` ProductPresentation[], required - `id` string, uuid, required - `object` 'product_presentation', required - `product_id` string, uuid, required - `name` string, required - `mode` 'fixed' | 'variable_measure', required - `unit` 'C62' | 'KGM' | 'GRM' | 'LTR' | 'MLT' | 'MTR' | 'MTK' | 'HUR' | 'DAY' | 'H87' | 'XPK' | 'XBX' | 'XDS' | 'XBG' | 'XBO' | 'XDJ' | 'XCA' | 'XTB' | 'XCI' | 'XJY' | 'XEN' | 'XCS', required: UN/ECE code of the commercial unit of the presentation. The nine measure units can also be a base unit; the thirteen count and packaging units (`H87` piece, `XPK` pack, `XBX` box, …) are valid only here and in supplier offers. It must be expressible over the base unit of the product: a packaging unit needs a declared equivalence (`conversion_factor` or `nominal_base_quantity`), a measure unit must belong to the same family as the base; otherwise 422 `unit_not_expressible`. - `conversion_factor` string, nullable, required - `nominal_base_quantity` string, nullable, required - `barcode` string, nullable, required - `gross_weight_kg` string, nullable: Own gross transport weight in kg per COMMERCIAL unit (decimal string, up to 4 decimals, greater than 0), packaging included; it overrides any derivation from the product or variant weight. `null` when the presentation declares none. Rejected with 422 `gross_weight_not_allowed` on `variable_measure` presentations. - `commercial_price_override` string, nullable, required: Own price PER COMMERCIAL UNIT, or `null` when the presentation declares none. Orthogonal to `conversion_factor`, which converts QUANTITY and is never reused as a price multiplier: a 3.5 kg tub priced at 50.00 is worth 50.00 per tub. - `specifications` object, required: Technical specifications OWN to this presentation (informational, not selectable). Empty object `{}` when there are none. The effective sheet combines product < variant < presentation and is composed by the aggregate. - `active` boolean, required - `variants` ProductVariant[], required - `id` string, uuid, required - `object` 'product_variant', required - `product_id` string, uuid, required - `name` string, required - `sku` string, nullable, required - `barcode` string, nullable, required - `base_price_override` string, nullable, required - `unit_cost_override` string, nullable, required - `gross_weight_kg` string, nullable: Own gross transport weight in kg per BASE unit (decimal string, up to 4 decimals, greater than 0) that replaces the product weight for this variant; `null` inherits the product weight. Rejected with 422 `gross_weight_not_allowed` when the product base unit is a mass unit. - `manage_stock` boolean, required - `stock` string, required - `low_stock_threshold` string, nullable, required - `specifications` object, required: Technical specifications OWN to this variant (informational, not selectable). Empty object `{}` when there are none. `base_price_override` stays PER BASE UNIT, unlike a presentation price, which is per commercial unit. - `active` boolean, required - `supplier_offers` SupplierProductOffer[], required - `id` string, uuid, required - `object` 'supplier_product_offer', required - `product_id` string, uuid, required - `supplier_id` string, uuid, required - `variant_id` string, uuid, nullable, required - `supplier_sku` string, nullable, required - `purchase_unit` 'C62' | 'KGM' | 'GRM' | 'LTR' | 'MLT' | 'MTR' | 'MTK' | 'HUR' | 'DAY' | 'H87' | 'XPK' | 'XBX' | 'XDS' | 'XBG' | 'XBO' | 'XDJ' | 'XCA' | 'XTB' | 'XCI' | 'XJY' | 'XEN' | 'XCS', required: UN/ECE code of the unit the supplier sells in. Any of the 22 units; it must be expressible over the base unit of the product (422 `unit_not_expressible` otherwise). - `conversion_factor` string, required - `unit_cost` string, nullable, required - `currency` string, required - `availability` string, required - `minimum_quantity` string, nullable, required - `lead_time_days` integer, nullable, required - `preferred` boolean, required - `active` boolean, required - `option_groups` ProductOptionGroup[], required: Sellable option groups (finish, flavour, quality) with their values. Always an array; `[]` when the product declares none. Populated only when the caller asks for the configurable catalog. - `id` string, uuid, required - `object` 'product_option_group', required - `product_id` string, uuid, required - `name` string, required - `required` boolean, required: Whether a value of this group must be chosen to confirm a line. - `position` integer, required - `scope_id` string, uuid, nullable, required: Scope of the group: `null` means it applies to the whole product; when set, it is the id of a variant or a presentation of the same product and the group only takes part in selections including it. - `active` boolean, required - `values` ProductOptionValue[], required - `id` string, uuid, required - `object` 'product_option_value', required - `name` string, required - `position` integer, required: Display order inside its group. - `price_adjustment` string, nullable, required: Additive adjustment PER COMMERCIAL UNIT. `null` means "this value does not change the price", which is NOT the same as `"0.0000"`. - `active` boolean, required: Whether the value is still selectable. An inactive value keeps naming historical document lines. - `configurations` ProductConfiguration[], required: Commercial configurations used for exact pricing and, depending on `catalog_availability_mode`, availability. In `open`, they do not restrict unless a row explicitly opts in. In `closed`, active rows form the exact allow-list; an empty active list means nothing is sellable. - `id` string, uuid, required - `object` 'product_configuration', required - `product_id` string, uuid, required - `name` string, required: Visible label composed from variant + presentation + values. It is not a stored column: the historical name is frozen by the document line, not by the catalog. It is also the text the price-list `search` filter matches. - `variant_id` string, uuid, nullable, required - `variant_name` string, nullable, required - `presentation_id` string, uuid, nullable, required - `presentation_name` string, nullable, required - `signature` string, required: Canonical, order-independent signature of variant + presentation + option values. Unique per product. - `commercial_price` string, nullable, required: FINAL price per commercial unit. When set it ALREADY absorbs the adjustments of its option values: they are not added again. - `active` boolean, required - `restricts_availability` boolean, required: Only used in `open` mode. When true, this row constrains the named variant; omitted presentation/options are wildcards. False means the row is pricing/identity only. - `options` ProductConfigurationOption[], required - `object` 'product_configuration_option', required - `group_id` string, uuid, required - `group_name` string, required - `value_id` string, uuid, required - `value_name` string, required - `price_adjustment` string, nullable, required - `is_low_stock` boolean, required: Indicates whether the current stock is below the configured threshold. - `is_in_stock` boolean, required: Whether there is stock available (> 0). - `specifications` object, required: Structured technical specifications of the product (free key-value pairs). Empty object `{}` when there are no specifications. - `metadata` Metadata, nullable, required: A free map of up to 50 key→value pairs for storing arbitrary structured data (values are strings up to 500 characters). Unlike `custom_fields` — an ordered list of typed `{field, value}` pairs with display semantics, present on the six document resources — `metadata` is an unordered map for opaque integration data; a document may carry both. The master resources (Client, Supplier) have no `custom_fields`, so their `metadata` doubles as the custom-fields store. **Reserved keys (read-only).** When the system auto-issues an invoice from a payment correlation (Stripe/GoCardless/MONEI), it writes `stripe_subscription_id`, `stripe_invoice_id`, `billing_reason`, `period_start` and `period_end` into that invoice metadata automatically. Do not set or overwrite them by hand — the platform owns them and a manual value may be replaced when the correlation runs. - `external_id` string, nullable: External integration key (ERP/CRM/e-commerce) mapping this product to a record in a third-party system. Free-format, unique per company, orthogonal to the catalog `sku` (a product may have both, neither, or either). - `created_at` string, date-time, nullable, required - `updated_at` string, date-time, nullable, required - `base_unit_change` BaseUnitChange: Whether the base unit of the product can be edited in place. `mode` is `direct` exactly when there are no blockers; with blockers it is `replacement` and the base unit is changed by replacing the product (`POST /v1/companies/{company}/products/{product}/base-unit-replacement`); an already replaced product is `unavailable` with no blockers. Attempting to edit `base_unit` with blockers is rejected with 422 `business_rule_violation`, subcode `product_base_unit_locked`, and the same `blockers` in `details`. Only calculated on single-product reads (show, create, update, replacement): list responses omit the key. - `mode` 'direct' | 'replacement' | 'unavailable', required - `blockers` object[], required: What fixes the base unit, in a stable order. - `code` 'stock' | 'movements' | 'presentations' | 'supplier_offers' | 'variant_stock', required: Closed catalog of blockers. - `quantity` string, required: Decimal string without trailing zeros: the stock in `unit` for `stock`, a count of elements for the rest. - `unit` string, nullable, required: UN/ECE code of the unit of `quantity`. Only informed for `stock`; `null` for the rest. - `replaces` ProductReplacementLink: The OTHER end of a base unit replacement: on `replaces`, the old product the current one replaced; on `replaced_by`, the new product that replaced the current one. - `id` string, uuid, required: Id of the other product. - `name` string, required - `base_unit` 'C62' | 'KGM' | 'GRM' | 'LTR' | 'MLT' | 'MTR' | 'MTK' | 'HUR' | 'DAY', required: Base unit of the other product. - `replaced_at` string, date-time, required - `equivalence` string, nullable, required: Old base units per ONE new base unit, decimal string with scale 6. `null` between measure families with no declared equivalence. - `stock_transferred` string, required: Stock moved to the new product, decimal string with scale 4, ALWAYS in the unit of the NEW product. - `replaced_by` ProductReplacementLink: The OTHER end of a base unit replacement: on `replaces`, the old product the current one replaced; on `replaced_by`, the new product that replaced the current one. - `id` string, uuid, required: Id of the other product. - `name` string, required - `base_unit` 'C62' | 'KGM' | 'GRM' | 'LTR' | 'MLT' | 'MTR' | 'MTK' | 'HUR' | 'DAY', required: Base unit of the other product. - `replaced_at` string, date-time, required - `equivalence` string, nullable, required: Old base units per ONE new base unit, decimal string with scale 6. `null` between measure families with no declared equivalence. - `stock_transferred` string, required: Stock moved to the new product, decimal string with scale 4, ALWAYS in the unit of the NEW product. - `has_more` boolean, required: Whether more pages are available after this one. - `next_cursor` string, nullable, required: Opaque cursor for the next page, or `null` when `has_more` is `false`. The example below shows the shape used by most listings; others return a different one, so pass the value back verbatim instead of validating it. ## Other responses - `400`: `parameter_unknown` with `subcode` `retired_active_profile_header`: the retired `X-Active-Profile` header was sent; the company goes in the path. `parameter_invalid_format` on `Factuarea-Version`: the header is not a `YYYY-MM-DD` date. `unsupported_api_version`: the `Factuarea-Version` date is not a supported version. - `401`: Missing or invalid API key. - `403`: The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`). - `404`: The requested resource does not exist or belongs to another company. `profile_not_found`: the company in the path does not exist, is not in the API key scope or belongs to the other environment (live or test). - `422`: Validation failed. The `error.param` field identifies which input is invalid. - `429`: Rate limit exceeded. Retry after the duration in `Retry-After`. - `500`: Unexpected server error. --- [API](https://skmtc.dev/factuarea/apis/factuarea-public-api.md) · [All operations](https://skmtc.dev/factuarea/apis/factuarea-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/factuarea/apis/factuarea-public-api/revisions/718e77934422?raw)