Search listings by criteria

GET

/listings/search

curl --request GET \
  --url 'https://acme.mykreezalid.com/api/v1/listings/search?limit=25&user_id=4242&status=published' \
  --header 'Authorization: Basic <credentials>'

• Your marketplace's address. A marketplace with a custom domain must be called on that domain instead (https://developers.kreezalid.com/getting-started/base-urls/).

Returns a paginated list of your listings, newest first, filtered by the query parameters you send. Every query parameter other than limit is an exact-match filter on the listing field of the same name, for example ?user_id=4242&status=published. A name that is not a listing field makes the request fail, and this includes page, sort and fields: to go through pages or select fields, use Get listings instead.

Authorizations

• basic

Parameters

Query Parameters

limit

integer

default: 25 >= 1 <= 100

Number of results (at most 100).

user_id

integer

Example

4242

Example of a field filter: listings of this vendor.

status

string

Example

published

Example of a field filter: listings with this status.

Responses

200

The matching listings

Media typeapplication/json

object

listings

Array<object>

A listing (product or service) of your marketplace. Read-only fields are returned in responses; write-only fields are only accepted when you create or update a listing.

object

id

Listing’s unique identifier

integer

object

string

default: Listing

admin_status

Admin validation status of the listing: waiting (awaiting approval), approved (visible if the status is also published), rejected or blocked (hidden from the marketplace). On creation it defaults to approved, or to blocked when is_online is 0.

string

Allowed values: waiting approved rejected blocked

attributes

Values of the listing attributes, keyed by attribute alias (see List listing attributes). When writing, a select or checkbox attribute accepts option identifiers or option titles (several values as an array or separated by ##); a title that matches no existing option creates that option. Unknown aliases are ignored.

object

key

additional properties

any

add_ons

Add-ons of the listing, null when there are none

Array<object>

nullable

An extra product or service a buyer can add to a listing, such as gift wrapping or an extended warranty.

object

id

Add-on’s unique identifier

integer

object

string

default: Addon

listing_id

Unique identifier of the listing the add-on belongs to

integer

title

string

description

string

price

Price of the add-on, with up to two decimal places

number format: double

nullable

address

Address of the listing, grouped

object

location

string

nullable

city

string

nullable

state

string

nullable

country

string

nullable

category

Category of the listing. On write you can also send category with an id, or with a title matching an existing category, instead of category_id.

object

object

string

id

integer

parent_id

integer

nullable

title

string

slug

string

url

string

category_id

Unique identifier of the listing’s category. Required on creation.

integer

city

string

nullable

country

string

nullable

cover

URL of the cover image

string

nullable

currency

string

date_online

Date the listing went online

string

nullable

description

Description of the listing. Required on creation. HTML you send is converted to plain text.

string

nullable

external_id

Your own reference for the listing

string

nullable

formatted_price

Price formatted for display, with its currency and price unit; may contain HTML

string

nullable

is_online

Set to 0 on creation to create the listing as a draft, blocked by an admin, unless you send status or admin_status yourself.

boolean

lat

number

nullable

lng

number

nullable

location

string

nullable

min_qty

Minimum quantity a buyer must order

number

nullable

logistic_category

Logistic category of the listing

object

object

string

id

integer

title

string

medias

Images attached to the listing, as returned in responses, null when there are none. On create and update this name is also accepted as an alias of images and takes the same value, a list of image URLs; if both are sent, images wins. Prefer images when writing — the alias exists so that posting back the field name you read does not fail silently.

Array<object>

nullable

object

object

string

id

integer

alt

string

nullable

position

integer

media_type

string

src

string format: uri

images

Images to attach to the listing, as a JSON array of publicly reachable image URLs; a single URL on its own is accepted too. Each URL is downloaded server-side and re-uploaded to our own storage, so the source only needs to stay reachable for the duration of the request; the stored copy is returned in medias. The order of the array is the display order. On update, sending images replaces the whole set, so any existing image you want to keep must be sent again. Omit the field to leave the current images untouched. medias is accepted as an alias of this field.

Array<string>

order_type_id

Unique identifier of the listing’s order type (see List order types). On creation, when it is missing or unknown, the first available order type is used.

integer

order_type_url_token

URL token of an order type (see List order types), as an alternative to order_type_id

string

order_type

Order type of the listing

object

object

string

id

integer

title

string

transaction_type

string

enable_cart

boolean

original_price

Price before discount

number

nullable

on_homepage

Whether the listing is shown on the homepage

boolean

price

Price of the listing. Required (and not zero) on creation.

number

nullable

price_unit

Title of the price unit, for example per night

string

nullable

price_with_currency

string

quantity

Quantity available for sale

number

nullable

quantity_selector

string

nullable

requires_shipping

boolean

sku

string

nullable

shipping_methods

Shipping methods selected for the listing

Array<object>

nullable

object

id

integer

carrier_alias

string

price

number

sort_priority

number

step_price

number

title

string

slug

string

nullable

state

string

nullable

status

Public status of the listing: draft, published (visible) or archived (hidden). On creation, a listing is created as published, or as a draft when is_online is 0 and no status is sent.

string

Allowed values: draft published archived

supplier

One of:

User resource

User resource

A member of your marketplace, customer or vendor, as the Admin API returns it.

object

id

User’s unique identifier

integer

object

string

external_id

Your own identifier for this user

string

nullable

account_type

string

nullable

Allowed values: individual company non_profit soletrader

address_city

string

nullable

address_country

Two-letter country code

string

nullable

address_line1

string

nullable

address_line2

string

nullable

address_state

string

nullable

address_zipcode

string

nullable

attributes

Values of the user’s custom profile fields

object

avatar

Absolute URL of the profile image

string

nullable

birthday

string format: date

nullable

business_name

Company or organization name

string

nullable

can_post_listing

Whether the user’s group may publish listings

boolean

is_onboarding

Whether the user’s group goes through onboarding

boolean

company

Company details. Absent when account_type is individual.

object

object

string

address_line1

string

nullable

address_line2

string

nullable

address_city

string

nullable

address_country

string

nullable

address_state

string

nullable

address_zipcode

string

nullable

name

string

nullable

number

Company registration number

string

nullable

website_url

string

nullable

created_at

Sign-up date, YYYY-MM-DD HH:MM:SS

string

email

string

first_name

string

nullable

group

object

object

string

default: Group

id

Group’s unique identifier

integer

name

string

alias

string

group_id

Identifier of the user’s group. Deprecated in responses: read group.id.

integer

group_name

Read group.name.

string

group_alias

Read group.alias.

string

lang

Language code

string

nullable

last_name

string

nullable

listing_count

Number of the user’s listings

integer

nullable

listing_count_any_status

Number of the user’s listings, whatever their status

integer

locale

Same value as lang

string

nullable

metafields

The user’s metafields, when they are loaded; null otherwise

Array<object>

nullable

A custom value you attach to a resource, identified by its namespace and title.

object

namespace

required

Group the metafield belongs to

string

title

required

Name of the metafield, unique within its namespace

string

value

required

Value of the metafield. Usually a string; it can be returned as a number or a JSON value depending on how the metafield was defined.

string

nationality

Two-letter country code

string

nullable

average_rating

Average rating from the reviews the user received

number

nullable

phone_country_code

string

nullable

phone_number

string

nullable

profile_url

Absolute URL of the user’s public profile

string

nullable

public_name

Name shown publicly, following your display settings

string

status

Account status

string

Allowed values: enabled disabled unknown

identity_status

Whether the user completed their identity details

string

nullable

Allowed values: not_completed completed

review_count

Number of reviews the user received

integer

nullable

timezone

string

nullable

username

string

nullable

owner

User resource

A member of your marketplace, customer or vendor, as the Admin API returns it.

object

id

User’s unique identifier

integer

object

string

external_id

Your own identifier for this user

string

nullable

account_type

string

nullable

Allowed values: individual company non_profit soletrader

address_city

string

nullable

address_country

Two-letter country code

string

nullable

address_line1

string

nullable

address_line2

string

nullable

address_state

string

nullable

address_zipcode

string

nullable

attributes

Values of the user’s custom profile fields

object

avatar

Absolute URL of the profile image

string

nullable

birthday

string format: date

nullable

business_name

Company or organization name

string

nullable

can_post_listing

Whether the user’s group may publish listings

boolean

is_onboarding

Whether the user’s group goes through onboarding

boolean

company

Company details. Absent when account_type is individual.

object

object

string

address_line1

string

nullable

address_line2

string

nullable

address_city

string

nullable

address_country

string

nullable

address_state

string

nullable

address_zipcode

string

nullable

name

string

nullable

number

Company registration number

string

nullable

website_url

string

nullable

created_at

Sign-up date, YYYY-MM-DD HH:MM:SS

string

email

string

first_name

string

nullable

group

object

object

string

default: Group

id

Group’s unique identifier

integer

name

string

alias

string

group_id

Identifier of the user’s group. Deprecated in responses: read group.id.

integer

group_name

Read group.name.

string

group_alias

Read group.alias.

string

lang

Language code

string

nullable

last_name

string

nullable

listing_count

Number of the user’s listings

integer

nullable

listing_count_any_status

Number of the user’s listings, whatever their status

integer

locale

Same value as lang

string

nullable

metafields

The user’s metafields, when they are loaded; null otherwise

Array<object>

nullable

A custom value you attach to a resource, identified by its namespace and title.

object

namespace

required

Group the metafield belongs to

string

title

required

Name of the metafield, unique within its namespace

string

value

required

Value of the metafield. Usually a string; it can be returned as a number or a JSON value depending on how the metafield was defined.

string

nationality

Two-letter country code

string

nullable

average_rating

Average rating from the reviews the user received

number

nullable

phone_country_code

string

nullable

phone_number

string

nullable

profile_url

Absolute URL of the user’s public profile

string

nullable

public_name

Name shown publicly, following your display settings

string

status

Account status

string

Allowed values: enabled disabled unknown

identity_status

Whether the user completed their identity details

string

nullable

Allowed values: not_completed completed

review_count

Number of reviews the user received

integer

nullable

timezone

string

nullable

username

string

nullable

user

One of:

User resource

User resource

A member of your marketplace, customer or vendor, as the Admin API returns it.

object

id

User’s unique identifier

integer

object

string

external_id

Your own identifier for this user

string

nullable

account_type

string

nullable

Allowed values: individual company non_profit soletrader

address_city

string

nullable

address_country

Two-letter country code

string

nullable

address_line1

string

nullable

address_line2

string

nullable

address_state

string

nullable

address_zipcode

string

nullable

attributes

Values of the user’s custom profile fields

object

avatar

Absolute URL of the profile image

string

nullable

birthday

string format: date

nullable

business_name

Company or organization name

string

nullable

can_post_listing

Whether the user’s group may publish listings

boolean

is_onboarding

Whether the user’s group goes through onboarding

boolean

company

Company details. Absent when account_type is individual.

object

object

string

address_line1

string

nullable

address_line2

string

nullable

address_city

string

nullable

address_country

string

nullable

address_state

string

nullable

address_zipcode

string

nullable

name

string

nullable

number

Company registration number

string

nullable

website_url

string

nullable

created_at

Sign-up date, YYYY-MM-DD HH:MM:SS

string

email

string

first_name

string

nullable

group

object

object

string

default: Group

id

Group’s unique identifier

integer

name

string

alias

string

group_id

Identifier of the user’s group. Deprecated in responses: read group.id.

integer

group_name

Read group.name.

string

group_alias

Read group.alias.

string

lang

Language code

string

nullable

last_name

string

nullable

listing_count

Number of the user’s listings

integer

nullable

listing_count_any_status

Number of the user’s listings, whatever their status

integer

locale

Same value as lang

string

nullable

metafields

The user’s metafields, when they are loaded; null otherwise

Array<object>

nullable

A custom value you attach to a resource, identified by its namespace and title.

object

namespace

required

Group the metafield belongs to

string

title

required

Name of the metafield, unique within its namespace

string

value

required

Value of the metafield. Usually a string; it can be returned as a number or a JSON value depending on how the metafield was defined.

string

nationality

Two-letter country code

string

nullable

average_rating

Average rating from the reviews the user received

number

nullable

phone_country_code

string

nullable

phone_number

string

nullable

profile_url

Absolute URL of the user’s public profile

string

nullable

public_name

Name shown publicly, following your display settings

string

status

Account status

string

Allowed values: enabled disabled unknown

identity_status

Whether the user completed their identity details

string

nullable

Allowed values: not_completed completed

review_count

Number of reviews the user received

integer

nullable

timezone

string

nullable

username

string

nullable

user_id

Unique identifier of the vendor (user) who owns the listing. Required on creation.

integer

title

Title of the listing. Required on creation.

string

url

Full URL of the listing page on your marketplace

string

variants

Variants of the listing, null when there are none. On update, send the full list: each variant is matched to an existing one by external_id, then by sku; a variant with no match is created, and every existing variant missing from the list is deleted.

Array<object>

nullable

A version of a listing that differs by size, color or any other characteristic, with its own price, SKU and stock.

object

id

Variant’s unique identifier

integer

object

string

default: Variant

external_id

Your own reference for the variant

string

nullable

listing_id

Unique identifier of the listing the variant belongs to

integer

price

number

nullable

price_unit

integer

nullable

quantity

The quantity of the variant that is available for sale

number

nullable

sort_priority

Sorts the variants with the lowest number first. Negative numbers are allowed.

number

nullable

sku

string

nullable

title

required

string

weight

number

cover_id

Unique identifier of the listing image used for this variant

integer

nullable

visibility

Where the listing is displayed: both (catalog and search), catalog (only the catalog), search (only search results) or none (not visible). Defaults to both on creation.

string

Allowed values: both catalog search none

weight

number

nullable

weight_unit

string

nullable

metafields

Metafields of the listing, grouped by namespace then by title

object

key

additional properties

any

next_date

Date of the next availability, for listings that have one

string

nullable

settings

Settings the listing inherits from its order type, such as whether payment, shipping or stock are enabled

object

key

additional properties

any

pagination

Paging information, added next to the results of a paginated list. Request another page with the page query parameter and change the page size with limit (at most 100).

object

totalResultsCount

Number of results across all pages.

integer

currentPage

Number of the page returned, starting at 1.

integer

nextPage

Whether a next page exists.

boolean

prevPage

Whether a previous page exists.

boolean

resultOnPageCount

Number of results on this page.

integer

pageCount

Number of pages.

integer

Example

{
  "listings": [
    {
      "id": 645646,
      "object": "Listing",
      "admin_status": "waiting",
      "attributes": {
        "color": "Blue",
        "material": "Leather"
      },
      "add_ons": [
        {
          "id": 4242,
          "object": "Addon",
          "listing_id": 324353,
          "title": "Extended Warranty",
          "description": "Protect your purchases beyond the standard warranty period",
          "price": 12.5
        }
      ],
      "category": {
        "object": "Category",
        "id": 4242,
        "title": "Shoes",
        "slug": "shoes",
        "url": "/c/shoes"
      },
      "category_id": 432432,
      "city": "New York City",
      "country": "US",
      "currency": "USD",
      "date_online": "2026-10-01 09:30:00",
      "description": "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla dignissim laoreet sem, quis mollis elit rutrum a. Donec nunc urna, rhoncus in sagittis ut, elementum scelerisque libero. Quisque interdum nibh nisl, non gravida nibh molestie quis. Phasellus nunc nunc, luctus a luctus ac, iaculis sit amet turpis.</p><p>Phasellus tortor orci, posuere in mi at, blandit ullamcorper tellus. Proin vel sem aliquam, faucibus dolor quis, dictum leo. Aliquam consectetur massa at ipsum auctor, at mattis nunc porttitor. Suspendisse potenti. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus.</p>",
      "external_id": "INTERNAL_REF_234324",
      "formatted_price": "$123.50",
      "is_online": true,
      "lat": 40.7572114,
      "lng": -73.9913385,
      "location": "253 W 42nd St, New York, NY 10036, United States",
      "min_qty": 1,
      "logistic_category": {
        "object": "LogisticCategory",
        "id": 4242
      },
      "medias": [
        {
          "object": "Media",
          "id": 4242,
          "position": 0,
          "media_type": "image"
        }
      ],
      "images": [
        "https://example.com/photo-front.jpg",
        "https://example.com/photo-back.jpg"
      ],
      "order_type_id": 986545,
      "order_type": {
        "object": "OrderType",
        "id": 4242,
        "title": "Sale",
        "transaction_type": "selling"
      },
      "original_price": 150,
      "on_homepage": false,
      "price": 123.5,
      "price_unit": null,
      "price_with_currency": "$123.50",
      "quantity": 43,
      "quantity_selector": null,
      "requires_shipping": true,
      "sku": "SKU_123",
      "shipping_methods": [
        {
          "id": 1,
          "carrier_alias": "fed_ex",
          "price": 4.95,
          "sort_priority": 4,
          "step_price": 0.95,
          "title": "FedEx"
        }
      ],
      "slug": "listing-s-slug",
      "state": "NY",
      "status": "draft",
      "supplier": {
        "id": 545353,
        "object": "User",
        "external_id": "ABCdef123456",
        "account_type": "individual",
        "address_city": "New-York City",
        "address_country": "US",
        "address_line1": "253 W 42nd St",
        "address_line2": null,
        "address_state": "NY",
        "address_zipcode": "10036",
        "attributes": {
          "profession": "Web developer"
        },
        "birthday": "1990-05-17",
        "business_name": "ACME",
        "company": {
          "object": "Company",
          "name": "ACME"
        },
        "created_at": "2024-03-18 09:41:05",
        "email": "jane@example.com",
        "first_name": "Jane",
        "group": {
          "object": "Group",
          "id": 784568,
          "name": "VIP Customers",
          "alias": "vip-customers"
        },
        "group_id": 784568,
        "lang": "en",
        "last_name": "Doe",
        "listing_count": 12,
        "listing_count_any_status": 14,
        "locale": "en",
        "metafields": [
          {
            "namespace": "erp",
            "title": "warehouse_code",
            "value": "WH-42"
          }
        ],
        "nationality": "US",
        "average_rating": 4.5,
        "phone_country_code": "+1",
        "phone_number": "212-398-2600",
        "profile_url": "https://acme.mykreezalid.com/shop/a1b2c3d/jane-doe",
        "public_name": "Jane Doe",
        "status": "enabled",
        "identity_status": "not_completed",
        "review_count": 3,
        "timezone": "America/New_York",
        "username": "janedoe"
      },
      "owner": {
        "id": 545353,
        "object": "User",
        "external_id": "ABCdef123456",
        "account_type": "individual",
        "address_city": "New-York City",
        "address_country": "US",
        "address_line1": "253 W 42nd St",
        "address_line2": null,
        "address_state": "NY",
        "address_zipcode": "10036",
        "attributes": {
          "profession": "Web developer"
        },
        "birthday": "1990-05-17",
        "business_name": "ACME",
        "company": {
          "object": "Company",
          "name": "ACME"
        },
        "created_at": "2024-03-18 09:41:05",
        "email": "jane@example.com",
        "first_name": "Jane",
        "group": {
          "object": "Group",
          "id": 784568,
          "name": "VIP Customers",
          "alias": "vip-customers"
        },
        "group_id": 784568,
        "lang": "en",
        "last_name": "Doe",
        "listing_count": 12,
        "listing_count_any_status": 14,
        "locale": "en",
        "metafields": [
          {
            "namespace": "erp",
            "title": "warehouse_code",
            "value": "WH-42"
          }
        ],
        "nationality": "US",
        "average_rating": 4.5,
        "phone_country_code": "+1",
        "phone_number": "212-398-2600",
        "profile_url": "https://acme.mykreezalid.com/shop/a1b2c3d/jane-doe",
        "public_name": "Jane Doe",
        "status": "enabled",
        "identity_status": "not_completed",
        "review_count": 3,
        "timezone": "America/New_York",
        "username": "janedoe"
      },
      "user": {
        "id": 545353,
        "object": "User",
        "external_id": "ABCdef123456",
        "account_type": "individual",
        "address_city": "New-York City",
        "address_country": "US",
        "address_line1": "253 W 42nd St",
        "address_line2": null,
        "address_state": "NY",
        "address_zipcode": "10036",
        "attributes": {
          "profession": "Web developer"
        },
        "birthday": "1990-05-17",
        "business_name": "ACME",
        "company": {
          "object": "Company",
          "name": "ACME"
        },
        "created_at": "2024-03-18 09:41:05",
        "email": "jane@example.com",
        "first_name": "Jane",
        "group": {
          "object": "Group",
          "id": 784568,
          "name": "VIP Customers",
          "alias": "vip-customers"
        },
        "group_id": 784568,
        "lang": "en",
        "last_name": "Doe",
        "listing_count": 12,
        "listing_count_any_status": 14,
        "locale": "en",
        "metafields": [
          {
            "namespace": "erp",
            "title": "warehouse_code",
            "value": "WH-42"
          }
        ],
        "nationality": "US",
        "average_rating": 4.5,
        "phone_country_code": "+1",
        "phone_number": "212-398-2600",
        "profile_url": "https://acme.mykreezalid.com/shop/a1b2c3d/jane-doe",
        "public_name": "Jane Doe",
        "status": "enabled",
        "identity_status": "not_completed",
        "review_count": 3,
        "timezone": "America/New_York",
        "username": "janedoe"
      },
      "user_id": 655785,
      "title": "Blue leather shoes",
      "variants": [
        {
          "id": 432432,
          "object": "Variant",
          "external_id": "INTERNAL_REF_234324",
          "listing_id": 324353,
          "price": 123.5,
          "price_unit": null,
          "quantity": 10,
          "sort_priority": 10,
          "sku": "BASKT-XYZ-BLN-41",
          "title": "Blue Shoes Size 41",
          "weight": 0.8,
          "cover_id": 4242
        }
      ],
      "visibility": "both",
      "weight": 0.8,
      "weight_unit": "kg",
      "metafields": {
        "erp": {
          "warehouse_code": "WH-42"
        }
      }
    }
  ],
  "pagination": {
    "totalResultsCount": 137,
    "currentPage": 1,
    "resultOnPageCount": 25,
    "pageCount": 6
  }
}

403

Missing or wrong API credentials