**Version: 202601**

# List products

**GET** `/openapi/2026-01/products`

Retrieve a list of products with pagination.

## Request

**Query Parameters**

- `ids` string[]

  Product's IDs. Example: ?ids=1001&ids=1002
- `title` string

  Product's title
- `collection_id` string

  Collection UUID, for example: `9e79ca1f-9ff2-409b-976f-98be343d38a3`
- `created_at_min` string

  Filter products created at or after date, for example: `2018-10-01T16:15:47-04:00`
- `created_at_max` string

  Filter products created at or before date, for example: `2018-10-01T16:15:47-04:00`
- `updated_at_min` string

  Filter products last updated at or after date, for example: `2018-10-01T16:15:47-04:00`
- `updated_at_max` string

  Filter products last updated at or before date, for example: `2018-10-01T16:15:47-04:00`
- `published_at_min` string

  Filter products published at or after date, for example: `2018-10-01T16:15:47-04:00`
- `published_at_max` string

  Filter products published at or before date, for example: `2018-10-01T16:15:47-04:00`
- `published_status` string

  Filter by published status: `published`, `unpublished`, `any`
- `spus` string[]

  Product's SPUs, separated by comma, for example: `spu1,spu2`
- `pre_cursor` string

  Previous page cursor for cursor-based pagination
- `cursor` string

  Page cursor for cursor-based pagination
- `per_page` int32

  Limit per page, maximum 250
- `fields` string[]

  Filter fields return in responses. Example: ?fields=id&fields=title
- `sort_direction` string

  Sort by direction, possible values are: `desc`, `asc`
- `exclude_ids` string[]

  Exclude\_ids is used to exclude products by their IDs, for example: `product_id1,product_id2`
- `product_type` string

  Filter by product type, available values are: `all`, `default`, `gift_card`, empty means all products
- `product_behaviour` string

  Product behaviour, available values are: `hidden`, empty means all products
- `location_id` uint64

  Filter by the location ID of the stock
- `vendors` string[]

  Filter by the vendor of the product. Example: ?vendors=Nike&vendors=Adidas
- `vendors_match` string[]

  Fuzzy matching filter by the vendor of the product. Example: ?vendors\_match=Nik&vendors\_match=Adid
- `handles` string[]

  Filter products by the handles. Example: ?handles=t-shirt&handles=hoodie

## Responses

**200**

OK

**application/json**

**Schema | Example**

**Schema**

- `code` string

  error code
- `message` string

  error message
- `data` object

  - `cursor` string

    [Cursor-based pagination](https://www.shoplazza.dev/reference/API-usage#cursor-pagination)
  - `pre_cursor` string

    [Cursor-based pagination](https://www.shoplazza.dev/reference/API-usage#cursor-pagination)
  - `has_more` boolean

    Whether more records follow this page (cursor pagination).
  - `products` object[]

    Product's list

    *   Array \[

    - `id` string

      Product's ID
    - `title` string

      Product's title
    - `description` string

      Product's description
    - `published` boolean

      Whether it is published or not
    - `requires_shipping` boolean

      Whether it is required to shipping
    - `taxable` boolean

      Whether it is taxable
    - `tags` string[]

      Tags, string list of tags
    - `vendor` string

      Vendor's name
    - `vendor_url` string

      Vendor's URL
    - `note` string

      Customizable note, for example: "This is a customizable product"
    - `seo_title` string

      SEO title
    - `seo_description` string

      SEO description
    - `seo_keywords` string[]

      SEO keywords
    - `handle` string

      Product's handle
    - `has_only_default_variant` boolean

      Whether it is a single variant
    - `inventory_tracking` boolean

      Whether to tracking inventory
    - `inventory_policy` string

      Inventory policy: `continue`, `deny`, `auto_unpublished`, required while `inventory_tracking` is true
    - `need_variant_image` boolean

      Whether variant image is needed. It's required if has\_only\_default\_variant is false
    - `spu` string

      Product's SPU
    - `fake_sales` int64

      Product's fake sales
    - `display_fake_sales` boolean

      Whether to display fake sales
    - `options` object[]

      List of options

      *   Array \[

      - `id` string

        Option's ID
      - `name` string

        Option's name, for example: "color","size"
      - `values` string[]

        Option's values, for example: \["red", "black"\],\["small", "large"\]
      - `position` int64

        Option's position
      *   \]
    - `images` object[]

      List of images

      *   Array \[

      - `id` string

        Image's ID
      - `src` string

        Image's URL
      - `width` int32

        Image's width in px
      - `height` int32

        Image's height in px
      - `alt` string

        Image's alt
      - `position` int64

        Image's position
      - `path` string

        Image's path
      *   \]
    - `variants` object[]

      List of product variants

      *   Array \[

      - `id` string

        The unique identifier of the variant
      - `product_id` string

        The product ID this variant belongs to
      - `image_id` string

        The image ID of the variant
      - `created_at` string

        The time of the variant was created
      - `updated_at` string

        The time of the variant was updated
      - `title` string

        Title of the variant
      - `option1` string

        The first option of the variant
      - `option2` string

        The second option of the variant
      - `option3` string

        The third option of the variant
      - `image` object

        The image of the variant

        - `src` string

          Image's URL
        - `width` int32

          Image's width in px
        - `height` int32

          Image's height in px
        - `alt` string

          Image's alt
        - `path` string

          Image's path
      - `position` int64

        The position of the variant in the product
      - `compare_at_price` double

        The compare at price of the variant
      - `price` double

        The price of the variant
      - `sku` string

        The SKU of the variant
      - `barcode` string

        The barcode of the variant
      - `note` string

        The note of the variant
      - `inventory_quantity` int64

        The inventory quantity of the variant
      - `weight` double

        The weight of the variant
      - `weight_unit` string

        The weight unit of the variant, possible value are: `kg`, `g`, `lb`, `oz`
      - `cost_price` double

        The cost price of the variant
      - `wholesale_price` object[]

        The wholesale prices of the variant

        *   Array \[

        - `price` double (required)

          Price
        - `min_quantity` int64 (required)

          Mini Order Quantity
        *   \]
      - `whole_prices` object[]

        The wholesale prices of the variant. Deprecated alias of `wholesale_price`; both carry the same value.

        *   Array \[

        - `price` double (required)

          Price
        - `min_quantity` int64 (required)

          Mini Order Quantity
        *   \]
      - `retail_price` double

        The retail price of the variant
      - `is_discount` boolean

        Whether the variant is discount
      - `origin_price` double

        The origin price of the variant
      - `extend` object

        Extend of the variant

        - `length` double

          The length of the variant
        - `width` double

          The width of the variant
        - `height` double

          The height of the variant
        - `dimension_unit` string

          The dimension unit
        - `origin_country_code` string

          Origin\_country\_code
        - `hs_code` string

          Hs\_code
      *   \]
    - `mixed_wholesale` boolean

      Whether mixed wholesale is supported
    - `product_type` string

      Product type
    - `brand` string

      Brand
    - `brief` string

      Brief of the product
    - `inventory_quantity` int64

      Inventory quantity
    - `price_min` double

      Min price
    - `price_max` double

      Max price
    - `compare_at_price_min` double

      Min compare at price
    - `compare_at_price_max` double

      Max compare at price
    - `published_at` string

      Published at
    - `created_at` string

      Created at
    - `updated_at` string

      Updated at
    - `sales` int64

      The real amount of sales
    - `independent_seo` boolean

      Independent seo
    - `url` string

      URL of the product
    - `available` boolean

      Whether the product available
    - `retail_price_min` double

      The minimum of the retail price
    - `retail_price_max` double

      The maximum of the retail price
    - `origin_price_min` double

      The minimum of the original price
    - `origin_price_max` double

      The maximum of the original price
    - `primary_image` object

      The primary image

      - `src` string

        Image's URL
      - `width` int32

        Image's width in px
      - `height` int32

        Image's height in px
      - `alt` string

        Image's alt
      - `path` string

        Image's path
    - `tax_code` string

      The tax code of the product
    - `category_id` string

      The category ID of the product
    - `category` object

      Categories in the products' list

      - `id` uint64

        Category ID
      - `name` string

        Name
      - `google_id` int64

        Google category ID
      - `level` int32

        Level
      - `path` string

        Path
    *   \]

```json
{
  "code": "string",
  "message": "string",
  "data": {
    "cursor": "string",
    "pre_cursor": "string",
    "has_more": true,
    "products": [
      {
        "id": "string",
        "title": "string",
        "description": "string",
        "published": true,
        "requires_shipping": true,
        "taxable": true,
        "tags": [
          "string"
        ],
        "vendor": "string",
        "vendor_url": "string",
        "note": "string",
        "seo_title": "string",
        "seo_description": "string",
        "seo_keywords": [
          "string"
        ],
        "handle": "string",
        "has_only_default_variant": true,
        "inventory_tracking": true,
        "inventory_policy": "string",
        "need_variant_image": true,
        "spu": "string",
        "fake_sales": 0,
        "display_fake_sales": true,
        "options": [
          {
            "id": "string",
            "name": "string",
            "values": [
              "string"
            ],
            "position": 0
          }
        ],
        "images": [
          {
            "id": "string",
            "src": "string",
            "width": 0,
            "height": 0,
            "alt": "string",
            "position": 0,
            "path": "string"
          }
        ],
        "variants": [
          {
            "id": "string",
            "product_id": "string",
            "image_id": "string",
            "created_at": "string",
            "updated_at": "string",
            "title": "string",
            "option1": "string",
            "option2": "string",
            "option3": "string",
            "image": {
              "src": "string",
              "width": 0,
              "height": 0,
              "alt": "string",
              "path": "string"
            },
            "position": 0,
            "compare_at_price": 0,
            "price": 0,
            "sku": "string",
            "barcode": "string",
            "note": "string",
            "inventory_quantity": 0,
            "weight": 0,
            "weight_unit": "string",
            "cost_price": 0,
            "wholesale_price": [
              {
                "price": 0,
                "min_quantity": 0
              }
            ],
            "whole_prices": [
              {
                "price": 0,
                "min_quantity": 0
              }
            ],
            "retail_price": 0,
            "is_discount": true,
            "origin_price": 0,
            "extend": {
              "length": 0,
              "width": 0,
              "height": 0,
              "dimension_unit": "string",
              "origin_country_code": "string",
              "hs_code": "string"
            }
          }
        ],
        "mixed_wholesale": true,
        "product_type": "string",
        "brand": "string",
        "brief": "string",
        "inventory_quantity": 0,
        "price_min": 0,
        "price_max": 0,
        "compare_at_price_min": 0,
        "compare_at_price_max": 0,
        "published_at": "string",
        "created_at": "string",
        "updated_at": "string",
        "sales": 0,
        "independent_seo": true,
        "url": "string",
        "available": true,
        "retail_price_min": 0,
        "retail_price_max": 0,
        "origin_price_min": 0,
        "origin_price_max": 0,
        "primary_image": {
          "src": "string",
          "width": 0,
          "height": 0,
          "alt": "string",
          "path": "string"
        },
        "tax_code": "string",
        "category_id": "string",
        "category": {
          "id": 0,
          "name": "string",
          "google_id": 0,
          "level": 0,
          "path": "string"
        }
      }
    ]
  }
}
```