List products

Retrieves a paginated list of products with extensive filtering and sorting options. Supports filtering by categories, collections, tags, attributes, brands, markets, status, product numbers, dates, and more. Returns products with all related data including variants, prices, and market status.

GET/api/v1/{team_slug}/{app_slug}/products

API: Management
OpenAPI: management-api
Updated: Apr 26, 2026

management-api:GET:/api/v1/{team_slug}/{app_slug}/products

API ownership

API family: Management API
Best for: Trusted back-office workflows that create, update, organize, or delete merchant-owned data.
Do not use from: Browser-only storefront code or public clients.
Guide route: /apis/management/latest

The OpenAPI contract defines the method, path, parameters, request body, and responses for this operation.

Operation

Method: GET
Path: /api/v1/\{team_slug\}/\{app_slug\}/products
Summary: List products
Description: Retrieves a paginated list of products with extensive filtering and sorting options. Supports filtering by categories, collections, tags, attributes, brands, markets, status, product numbers, dates, and more. Returns products with all related data including variants, prices, and market status.
OpenAPI contract: management-api
Operation ID: Not documented in the OpenAPI contract.

Operation key uses API family, method, and path because this OpenAPI contract does not publish an operation ID.

Parameters35 parameters

Name	In	Required	Type	Description
page	query	No	integer	Page number (default is 1)
per-page	query	No	integer	Amount of products per page. Minimum 0 and max 100 (default is 20)
app_slug	path	Yes	string	App slug
team_slug	path	Yes	string	Team slug
categories	query	No	string[]	Filter by category URI
collections	query	No	string[]	Filter by collection URI
attributes	query	No	string[]	Filter by attributes. The format should be `template_key/attribute_key`. e.g `colors/black`
brands	query	No	string[]	Filter by brand name
markets	query	No	string[]	Filter by market slugs (commercial availability - products with variant prices in these markets)
search	query	No	string	Search on product name
product-number	query	No	string[]	Filter by exact product number/SKU (case-insensitive, supports multiple values)
status	query	No	string[]	Search by status, active \| inactive \| draft \| incomplete
sort-order	query	No	string	Sort order. Should be one of ASC or DESC. Default DESC
sort-key	query	No	string	The key to sort on. Can be one of `product-name`, `product-number`, `created-at`, `updated-at`, `status`, `category`, `tag`, `collection`. (Default is `created_at`). When sorting by `category`, `tag`, or `collection` order, you must also filter by a single corresponding item.
tags	query	No	string[]	Filter by tag keys
smart-listing	query	No	string[]	Filter by smart-listing slug(s). A product matches if any variant belongs to one of these smart-listings
static-listing	query	No	string[]	Filter by static-listing slug(s). A product matches if any variant belongs to one of these static-listings
dont-match-publishing-rules	query	No	boolean	Only show products which don't follow the publishing rules for the specific app
created-at-before	query	No	string	ISO 8601 date. Fetch products created before this date.
created-at-after	query	No	string	ISO 8601 date. Fetch products created after this date.
updated-at-before	query	No	string	ISO 8601 date. Fetch products updated before this date.
updated-at-after	query	No	string	ISO 8601 date. Fetch products updated after this date.
has-description	query	No	boolean	Filter by whether product description exists.
description-includes	query	No	string	Filter by substring in description.
has-translations	query	No	boolean	Filter by whether any product translations exist.
has-product-relation	query	No	boolean	Filter by whether any product relation exist.
product-relation-type	query	No	string	Filter on a specific product relation type
product-market-status	query	No	string[]	Filter by marketing status (active, inactive, draft, incomplete, archived). Can be combined with product-market-status-market and/or product-market-status-store-group
product-market-status-market	query	No	string[]	Filter products by marketing status in specific market(s). Requires product-market-status to be specified
product-market-status-store-group	query	No	string	Filter products by marketing status in specific store group/channel. Requires product-market-status to be specified
product-ids	query	No	string[]	Filter by product ids
no-categories	query	No	boolean	Filter products that have no categories
no-variants	query	No	boolean	Filter products that have no variants
channel-id	query	No	string	Filter products that are members of the given channel (UUID). Each product response includes its channel_statuses memberships when present.
channel-status	query	No	string	Filter products in the given channel by status (active or incomplete). Requires channel-id.

Request bodyNo documented body

Not documented in the OpenAPI contract.

Responses4 statuses

Status	Description	Content
200	Product list	application/json (object)
400	Invalid query parameter	application/json (object)
401	Unauthorized	application/json (object)
500	Internal Server Error	application/json (object)

200 - object

Product List

Property	Type	Required	Details
`data`	object[]	No	-
`success`	boolean	No	-
`total`	integer	No	-
`total_pages`	integer	No	-

Product

Property	Type	Required	Details
`attributes`	object[]	No	Product attributes
`brand`	object	No	Brand of the product
`categories`	object[]	No	Associated categories
`channel_statuses`	object[]	No	-
`collections`	object[]	No	Associated collections
`created_at`	string	No	Creation timestamp
`custom`	object	No	-
`description`	string	No	Description of the product
`exclude_from_feeds`	boolean	No	If the products should exist in feeds or not
`files`	object[]	No	Product files
`html_description`	string	No	Html description
`html_short_description`	string	No	Html short description
`id`	string	No	Product ID
`images`	object[]	No	Images of the product
`market_status`	object[]	No	-
`markets`	object[]	No	Associated markets
`meta_description`	string	No	Meta description for SEO
`meta_title`	string	No	Meta title for SEO
`package_dimensions`	object	No	The package dimensions
`product_dimensions`	object	No	The products dimensions
`product_name`	string	No	VariantName of the product
`product_number`	string	No	Product number
`product_type`	string	No	Product type
`redirects`	object[]	No	Product redirects
`relations`	object[]	No	Product relations
`schedules`	object[]	No	-
`short_description`	string	No	Short description of the product
`slug`	string	No	Slug for the product
`source_app_id`	string	No	-
`source_id`	string	No	-
`status`	string	No	Status of the product
`tags`	object[]	No	Product tags
`tax_group_id`	string	No	The id of the tax group
`third_part_links`	object[]	No	-
`translations`	object	No	Product translations
`updated_at`	string	No	Last updated timestamp
`variant_groups`	object[]	No	Variant groups with images, attributes, videos
`variants`	object[]	No	Product variants
`videos`	object[]	No	Videos of the product

Attribute

Property	Type	Required	Details
`created_at`	string	No	-
`description`	string	No	-
`filterable`	boolean	No	-
`id`	string	No	-
`key`	string	No	-
`name`	string	No	-
`template_key`	string	No	-
`template_name`	string	No	-
`translatable`	boolean	No	-
`translations`	object	No	-
`updated_at`	string	No	-
`values`	object	No	-

Product Brand

Property	Type	Required	Details
`address`	object	No	-
`email`	string	No	-
`id`	string	No	-
`name`	string	No	-
`series`	object	No	-
`slug`	string	No	-

Product Category

Property	Type	Required	Details
`attributes`	object[]	No	-
`children`	object[]	No	-
`cover_url`	string	No	-
`created_at`	string	No	-
`google_product_category_id`	string	No	-
`id`	string	No	-
`is_main_category`	boolean	No	-
`name`	string	No	-
`order`	integer	No	-
`parent_id`	string	No	-
`redirects`	object[]	No	-
`slug`	string	No	-
`sort_order`	integer	No	Used for ordering categories themselves
`status`	string	No	-
`translations`	object	No	-
`updated_at`	string	No	-
`uri`	string	No	-

Product Channel Status

Property	Type	Required	Details
`channel_id`	string	No	-
`channel_slug`	string	No	-
`status`	string	No	-

Product Collection

Property	Type	Required	Details
`children`	object[]	No	-
`created_at`	string	No	-
`id`	string	No	-
`order`	integer	No	-
`parent_id`	string	No	-
`redirects`	object[]	No	-
`slug`	string	Yes	-
`status`	enum("active", "inactive", "draft")	Yes	-
`title`	string	No	-
`translations`	object	No	-
`updated_at`	string	No	-
`uri`	string	No	-

File

Property	Type	Required	Details
`attributes`	object[]	No	-
`created_at`	string	No	-
`folder_id`	string	No	-
`id`	string	No	-
`public`	boolean	No	-
`title`	string	No	-
`translations`	object	No	-
`type`	string	No	-
`updated_at`	string	No	-
`url`	string	No	-

Image With Priority

Property	Type	Required	Details
`alt`	string	No	-
`app_id`	string	No	-
`attributes`	object[]	No	-
`blurhash`	string	No	-
`copyright`	string	No	-
`custom`	object	No	-
`folder_id`	string	No	-
`id`	string	No	-
`parent_id`	string	No	-
`priority`	integer	No	-
`public`	boolean	No	-
`source_app_id`	string	No	-
`source_id`	string	No	-
`status`	string	No	-
`title`	string	No	-
`translations`	object	No	-
`url`	string	No	-

Market Status

Property	Type	Required	Details
`created_at`	string	No	-
`market_id`	string	No	-
`market_slug`	string	No	-
`status`	string	No	-
`store_group_id`	string	No	-
`store_group_slug`	string	No	-
`updated_at`	string	No	-

Market

Property	Type	Required	Details
`active`	boolean	No	-
`country_codes`	string[]	No	-
`created_at`	string	No	-
`currency_code`	string	No	-
`id`	string	No	-
`locale`	string	No	-
`name`	string	No	-
`slug`	string	No	-
`updated_at`	string	No	-

Dimensions

Property	Type	Required	Details
`capacity_milliliter`	integer	No	min: 0 the capacity in milliliter
`depth`	integer	No	min: 0 The products depth in millimeter
`diameter`	integer	No	min: 0 the products diameter in millimeter
`height`	integer	No	min: 0 The products height in millimeter
`length`	integer	No	min: 0 The products length in millimeter
`weight`	integer	No	min: 0 The products weight in grams
`width`	integer	No	min: 0 The products width in millimeter

Redirects

Property	Type	Required	Details
`id`	string	No	-
`item_id`	string	No	-
`locale`	string	No	-
`new_slug`	string	No	-
`old_slug`	string	No	-
`type`	enum("product", "page", "collection", "category", "product_bundle")	No	-

Relation

Property	Type	Required	Details
`direction`	string	No	-
`id`	string	No	-
`primary_product_id`	string	No	-
`products`	object[]	No	-
`title`	string	No	-
`type`	string	No	-
`type_id`	string	No	-

Job

Property	Type	Required	Details
`add_category_names`	string[]	No	-
`add_collection_names`	string[]	No	-
`add_tag_names`	string[]	No	-
`execute_at`	string	No	Date when the job should run
`finished_at`	string	No	If a job is finished will this timestamp be filled
`id`	string	No	-
`item_id`	string	No	-
`item_name`	string	No	-
`item_type`	string	No	-
`remove_category_names`	string[]	No	-
`remove_collection_names`	string[]	No	-
`remove_tag_names`	string[]	No	-
`to_amount_cents_with_tax`	integer	No	-
`to_market_id`	string	No	-
`to_market_status`	string	No	-
`to_on_sale`	boolean	No	-
`to_sale_amount_cents_with_tax`	integer	No	-
`to_start_sale_timestamp`	string	No	-
`to_status`	string	No	-
`to_stop_sale_timestamp`	string	No	-
`to_store_group_id`	string	No	-

Product Tag

Property	Type	Required	Details
`attributes`	object[]	No	-
`created_at`	string	No	-
`filterable`	boolean	No	-
`id`	string	No	-
`key`	string	No	-
`markets`	object[]	No	-
`name`	string	No	-
`order`	integer	No	-
`schedules`	object[]	No	-
`source_app_id`	string	No	-
`source_id`	string	No	-
`status`	string	No	-
`translations`	object	No	-
`updated_at`	string	No	-

Third Party Link

Property	Type	Required	Details
`created_at`	string	No	-
`id`	string	No	-
`title`	string	No	-
`type`	string	No	-
`updated_at`	string	No	-
`url`	string	No	-

Product Translations

Property	Type	Required	Details
`description`	object[]	No	-
`html_description`	object[]	No	-
`html_short_description`	object[]	No	-
`meta_description`	object[]	No	-
`meta_title`	object[]	No	-
`name`	object[]	No	-
`short_description`	object[]	No	-
`slug`	object[]	No	-

Variant Group

Property	Type	Required	Details
`attributes`	object[]	No	-
`channel_statuses`	object[]	No	-
`created_at`	string	No	-
`id`	string	No	-
`images`	object[]	No	-
`name`	string	No	-
`priority`	integer	No	-
`product_id`	string	No	-
`slug`	string	No	-
`tags`	object[]	No	-
`translations`	object	No	-
`updated_at`	string	No	-
`variants`	object[]	No	-
`videos`	object[]	No	-

Variant

Property	Type	Required	Details
`attributes`	object[]	No	-
`created_at`	string	No	-
`custom_fields`	object	No	-
`id`	string	No	-
`images`	object[]	No	Images of the product
`listings`	object	No	-
`parent_product_id`	string	No	-
`purchase_price`	object	No	-
`shipping_attributes`	string[]	No	-
`source_app_id`	string	No	-
`source_id`	string	No	-
`status`	string	No	-
`store_group`	object[]	No	Product StoreGroup
`tags`	object[]	No	-
`translations`	object	No	-
`updated_at`	string	No	-
`validate_stock`	boolean	No	-
`variant_dimensions`	object	No	-
`variant_group_id`	string	No	-
`variant_name`	string	No	-
`variant_number`	string	No	-
`videos`	object[]	No	Videos of the product
`warehouse_variant_stock`	object[]	No	-

Video

Property	Type	Required	Details
`attributes`	object[]	No	-
`description`	string	No	-
`folder_id`	string	No	-
`id`	string	No	-
`path`	string	No	-
`public`	boolean	No	-
`status`	string	No	-
`title`	string	No	-
`translations`	object	No	-
`variants`	object[]	No	-

{
  "data": [
    {
      "attributes": [
        {
          "created_at": null,
          "description": null,
          "filterable": null,
          "id": null,
          "key": null,
          "name": null,
          "template_key": null,
          "template_name": null,
          "translatable": null,
          "translations": null,
          "updated_at": null,
          "values": null
        }
      ],
      "brand": {
        "address": {
          "city": null,
          "co_address": null,
          "country": null,
          "house_number": null,
          "postal_code": null,
          "state_province": null,
          "street_address": null
        },
        "email": "string",
        "id": "string",
        "name": "string",
        "series": {
          "id": null,
          "name": null,
          "slug": null
        },
        "slug": "string"
      },
      "categories": [
        {
          "attributes": null,
          "children": null,
          "cover_url": null,
          "created_at": null,
          "google_product_category_id": null,
          "id": null,
          "is_main_category": null,
          "name": null,
          "order": null,
          "parent_id": null,
          "redirects": null,
          "slug": null,
          "sort_order": null,
          "status": null,
          "translations": null,
          "updated_at": null,
          "uri": null
        }
      ],
      "channel_statuses": [
        {
          "channel_id": null,
          "channel_slug": null,
          "status": null
        }
      ],
      "collections": [
        {
          "children": null,
          "created_at": null,
          "id": null,
          "order": null,
          "parent_id": null,
          "redirects": null,
          "slug": null,
          "status": null,
          "title": null,
          "translations": null,
          "updated_at": null,
          "uri": null
        }
      ],
      "created_at": "string",
      "custom": {},
      "description": "string",
      "exclude_from_feeds": false,
      "files": [
        {
          "attributes": null,
          "created_at": null,
          "folder_id": null,
          "id": null,
          "public": null,
          "title": null,
          "translations": null,
          "type": null,
          "updated_at": null,
          "url": null
        }
      ],
      "html_description": "string",
      "html_short_description": "string",
      "id": "string",
      "images": [
        {
          "alt": null,
          "app_id": null,
          "attributes": null,
          "blurhash": null,
          "copyright": null,
          "custom": null,
          "folder_id": null,
          "id": null,
          "parent_id": null,
          "priority": null,
          "public": null,
          "source_app_id": null,
          "source_id": null,
          "status": null,
          "title": null,
          "translations": null,
          "url": null
        }
      ],
      "market_status": [
        {
          "created_at": null,
          "market_id": null,
          "market_slug": null,
          "status": null,
          "store_group_id": null,
          "store_group_slug": null,
          "updated_at": null
        }
      ],
      "markets": [
        {
          "active": null,
          "country_codes": null,
          "created_at": null,
          "currency_code": null,
          "id": null,
          "locale": null,
          "name": null,
          "slug": null,
          "updated_at": null
        }
      ],
      "meta_description": "string",
      "meta_title": "string",
      "package_dimensions": {
        "capacity_milliliter": 0,
        "depth": 0,
        "diameter": 0,
        "height": 0,
        "length": 0,
        "weight": 0,
        "width": 0
      },
      "product_dimensions": {
        "capacity_milliliter": 0,
        "depth": 0,
        "diameter": 0,
        "height": 0,
        "length": 0,
        "weight": 0,
        "width": 0
      },
      "product_name": "string",
      "product_number": "string",
      "product_type": "string",
      "redirects": [
        {
          "id": null,
          "item_id": null,
          "locale": null,
          "new_slug": null,
          "old_slug": null,
          "type": null
        }
      ],
      "relations": [
        {
          "direction": null,
          "id": null,
          "primary_product_id": null,
          "products": null,
          "title": null,
          "type": null,
          "type_id": null
        }
      ],
      "schedules": [
        {
          "add_category_names": null,
          "add_collection_names": null,
          "add_tag_names": null,
          "execute_at": null,
          "finished_at": null,
          "id": null,
          "item_id": null,
          "item_name": null,
          "item_type": null,
          "remove_category_names": null,
          "remove_collection_names": null,
          "remove_tag_names": null,
          "to_amount_cents_with_tax": null,
          "to_market_id": null,
          "to_market_status": null,
          "to_on_sale": null,
          "to_sale_amount_cents_with_tax": null,
          "to_start_sale_timestamp": null,
          "to_status": null,
          "to_stop_sale_timestamp": null,
          "to_store_group_id": null
        }
      ],
      "short_description": "string",
      "slug": "string",
      "source_app_id": "string",
      "source_id": "string",
      "status": "string",
      "tags": [
        {
          "attributes": null,
          "created_at": null,
          "filterable": null,
          "id": null,
          "key": null,
          "markets": null,
          "name": null,
          "order": null,
          "schedules": null,
          "source_app_id": null,
          "source_id": null,
          "status": null,
          "translations": null,
          "updated_at": null
        }
      ],
      "tax_group_id": "string",
      "third_part_links": [
        {
          "created_at": null,
          "id": null,
          "title": null,
          "type": null,
          "updated_at": null,
          "url": null
        }
      ],
      "translations": {
        "description": [],
        "html_description": [],
        "html_short_description": [],
        "meta_description": [],
        "meta_title": [],
        "name": [],
        "short_description": [],
        "slug": []
      },
      "updated_at": "string",
      "variant_groups": [
        {
          "attributes": null,
          "channel_statuses": null,
          "created_at": null,
          "id": null,
          "images": null,
          "name": null,
          "priority": null,
          "product_id": null,
          "slug": null,
          "tags": null,
          "translations": null,
          "updated_at": null,
          "variants": null,
          "videos": null
        }
      ],
      "variants": [
        {
          "attributes": null,
          "created_at": null,
          "custom_fields": null,
          "id": null,
          "images": null,
          "listings": null,
          "parent_product_id": null,
          "purchase_price": null,
          "shipping_attributes": null,
          "source_app_id": null,
          "source_id": null,
          "status": null,
          "store_group": null,
          "tags": null,
          "translations": null,
          "updated_at": null,
          "validate_stock": null,
          "variant_dimensions": null,
          "variant_group_id": null,
          "variant_name": null,
          "variant_number": null,
          "videos": null,
          "warehouse_variant_stock": null
        }
      ],
      "videos": [
        {
          "attributes": null,
          "description": null,
          "folder_id": null,
          "id": null,
          "path": null,
          "public": null,
          "status": null,
          "title": null,
          "translations": null,
          "variants": null
        }
      ]
    }
  ],
  "success": false,
  "total": 0,
  "total_pages": 0
}

400 - object

Error Message

Property	Type	Required	Details
`details`	string[]	No	-
`message`	string	No	-
`success`	boolean	No	-

Generated example (synthetic):

{
  "details": [
    "string"
  ],
  "message": "string",
  "success": false
}

401 - object

Error Message

Property	Type	Required	Details
`details`	string[]	No	-
`message`	string	No	-
`success`	boolean	No	-

Generated example (synthetic):

{
  "details": [
    "string"
  ],
  "message": "string",
  "success": false
}

500 - object

Error Message

Property	Type	Required	Details
`details`	string[]	No	-
`message`	string	No	-
`success`	boolean	No	-

Generated example (synthetic):

{
  "details": [
    "string"
  ],
  "message": "string",
  "success": false
}

Contract identity

Use these fields to confirm you are implementing the intended endpoint contract.

API family: Management API
Method: GET
Path: /api/v1/\{team_slug\}/\{app_slug\}/products
Operation ID: Not documented in the OpenAPI contract.
OpenAPI tag: Products
OpenAPI summary: List products