Skip to main content

List Suppliers

GET 
/api/v2/suppliers

List suppliers with pagination, search, sorting, sparse fieldsets and the full advanced-filter grammar. Every supplier field that can be exported or imported is also readable and filterable here.

Required scope: suppliers:read

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Authentication: requires a Bearer token with the suppliers:read scope.

Pagination

  • page — 1-based page number (default 1).
  • per_page — rows per page (default 10). Pass per_page=-1 to return every matching supplier on a single page, which is how pickers and lookups load the full list.

Sparse fieldsets

  • included[] — return ONLY these fields. Repeat the parameter once per field: included[]=name&included[]=city&included[]=default_payment_term.
  • excluded[] — return everything except these fields.

Relation values are exposed twice: nested (address, default_store, default_incoterm, default_pricing_tier, default_tax_rate, default_payment_term, default_shipping_method) and flat (city, province_code, country_code, zip, label, fax, address1–address3, address_name, address_company, address_phone, default_warehouse_name, default_store_name, default_incoterm_code, contractor_default_warehouse_name, wire_instructions_verified_by_name). Use the flat keys with included[] — a dotted key such as address.city is not a valid included[] entry.

Sorting — sort=<field>, prefix with - for descending. Default -created_at. Allowed fields: id, name, type, company_name, email, primary_contact_name, leadtime, minimum_order_quantity, contacts_count, products_count, created_at, updated_at, purchase_order_email, messaging_phone, website, timezone, archived_at, target_stock_days, minimum_purchase_order, minimum_purchase_order_quantity, default_incoterm_place, purchase_order_format, po_processing_method, auto_submit_dropship_po, auto_fulfill_dropship, auto_generate_backorder_po, auto_submit_backorder_po, auto_split_backorder_po_by_brand, auto_receive_backorder_po, default_stock_level, stock_mode, in_stock_quantity, stock_buffer_percentage, default_deposit_percentage, auto_apply_deposits, wire_instructions_verified_at, invoice_reminders_mode, invoice_reminder_interval_days, invoice_reminder_max_count, invoice_reminder_start_after_days, is_manufacturing_contractor, default_outsourced_cost_basis, default_pricing_tier_id, default_warehouse_id, default_store_id, default_payment_term_id, default_tax_rate_id, default_incoterm_id, default_shipping_method_id, contractor_default_warehouse_id.

Fields backed by a related record (address parts, default_payment_term, default_shipping_method, default_warehouse_name, …) are filterable but not sortable.

Simple filters

  • filter[search] — matches name, company_name, email, primary_contact_name.
  • filter[archived] — only, archived or true returns archived suppliers only; all returns both; any other value, or omitting the parameter, returns active suppliers only.
  • filter[type] — goods or service.

Advanced filters — filter[<field>.<operator>]=<value>. The bare form filter[<field>]=<value> behaves as an implicit is. List operators (is_one_of, is_not_one_of) and between take comma-separated values.

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. Text fields: name, company_name, email, primary_contact_name, type, purchase_order_email, messaging_phone, website, timezone, address_name, address_company, address_phone, fax, address1, address2, address3, city, province, province_code, zip, country, country_code, label, default_warehouse_name, default_store_name, default_payment_term, default_tax_rate, default_pricing_tier, default_incoterm_code, default_shipping_method, contractor_default_warehouse_name, default_incoterm_place, purchase_order_format, po_processing_method, default_stock_level, stock_mode, wire_instructions, wire_instructions_verified_by_name, invoice_reminders_mode, default_outsourced_cost_basis.

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, is_empty, is_not_empty. Numeric fields: id, leadtime, minimum_order_quantity, target_stock_days, minimum_purchase_order, minimum_purchase_order_quantity, in_stock_quantity, stock_buffer_percentage, default_deposit_percentage, invoice_reminder_interval_days, invoice_reminder_max_count, invoice_reminder_start_after_days, contacts_count, products_count, default_warehouse_id, default_store_id, default_payment_term_id, default_tax_rate_id, default_pricing_tier_id, default_incoterm_id, default_shipping_method_id, contractor_default_warehouse_id.

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. Relative operators (today, past_week, …) ignore the value; days_ago, days_from_now, past_days and next_days take an integer number of days. Date/time fields: created_at, updated_at, archived_at, wire_instructions_verified_at.

Boolean flags — use filter[<field>.is]=true|false: auto_submit_dropship_po, auto_fulfill_dropship, auto_generate_backorder_po, auto_submit_backorder_po, auto_split_backorder_po_by_brand, auto_receive_backorder_po, auto_apply_deposits, is_manufacturing_contractor.

Custom fields — each active supplier custom field adds filter[cf_<slug>.<operator>], using the operator family that matches the field's type (text/long text/dropdown → text, number/decimal → numeric, date → date, datetime → date/time, checkbox → cf_<slug>.is). The stored values are returned in custom_field_values[].

Grouped filters — for AND/OR trees, send filter_groups as base64-encoded JSON. Decoded shape:

{"conjunction":"and","children":[{"type":"condition","condition":{"column":"leadtime","operator":"greater_than","value":14}},{"type":"group","group":{"conjunction":"or","children":[{"type":"condition","condition":{"column":"country_code","operator":"is","value":"US"}},{"type":"condition","condition":{"column":"country_code","operator":"is","value":"CA"}}]}}]}

Columns and operators are the same set listed above. Groups may nest, and each level carries its own conjunction (and / or).

Include compliance_status in a with parameter to add each supplier's compliance posture to the response: required, missing and expired (arrays of document type values) plus is_complete. Resolved in a single batched pass for the whole page, so it does not cost a query per row. The key is omitted when the include is not requested — absent means "not evaluated", which is not the same as compliant. A supplier that requires no certificates reports is_complete: true with an empty required array. Compliance is advisory throughout and never blocks a purchase order.

Request​

Responses​

OK

Response Headers
    Content-Type