Skip to main content

List Supplier Price List

GET 
/api/suppliers/:supplier/price-list

Paginated price list for one supplier: every product this supplier can supply, joined against the chosen retail pricing tier and the chosen supplier cost tier, with the margin between them pre-computed in five conventions.

Authentication: Requires Bearer token (scope: suppliers)

Each row's margin object restates the same gap five ways so the caller does not have to:

  • margin_pct — (retail - cost) / retail
  • off_retail_pct — the same number read as a discount off the retail list price
  • cost_ratio_pct — cost / retail
  • markup_pct — (retail - cost) / cost
  • multiplier — retail / cost
  • amount — retail - cost, in the retail tier's currency

Every margin field is null when either side is missing or the retail price is zero, so unpriced products never produce a misleading 100%.

Tiers: when sell_tier_id / cost_tier_id are omitted the account's default retail and default supplier tiers are used. Call the metadata endpoint for the selectable tiers, the supplier's brands, and the column catalogue.

Filtering​

Filters are sent as filter[<name>] query parameters.

Quick filters:

  • filter[search] — partial match across SKU, product name, barcode, MPN and supplier SKU
  • filter[brand_id] — one or more brand ids, comma separated. Valid ids come from the metadata endpoint
  • filter[only_priced] — 1 keeps only products carrying both a retail price and a supplier cost on the selected tiers
  • filter[archived] — active (default), only for archived products only, all for both

Column filters take the form filter[<column>.<operator>], for example filter[sku.starts_with]=CB-, filter[margin_pct.greater_than]=50, filter[cost_price.between]=10,50.

  • Text columns — sku, name, barcode, mpn, hts_code, brand_name, supplier_sku. 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 columns — sell_price, cost_price, margin_amount, margin_pct, off_retail_pct, markup_pct, multiplier, minimum_order_quantity, leadtime, case_quantity, on_hand_quantity, weight. Operators: is, is_not, is_one_of, is_not_one_of, greater_than, greater_than_or_equal, less_than, less_than_or_equal, between, is_empty, is_not_empty
  • Boolean columns — is_default_supplier, archived. Operator: is (and is_not for archived)

For AND/OR logic and nested groups, send filter_groups instead: a base64-encoded JSON tree of the shape {"conjunction":"and","children":[{"type":"condition","condition":{"column":"margin_pct","operator":"greater_than","value":50}}]}. A children entry may also be {"type":"group","group":{...}} to nest a sub-group with its own conjunction. Conditions naming a column or operator that is not listed above are ignored.

Archived products are excluded unless the archived scope says otherwise.

Request​

Responses​

OK

Response Headers
    Content-Type