Search

Provides access to intelligent search and filtering across your catalog

Endpoint Details

POST /catalog/search

Headers

Header	Value
Content-Type	application/json
Authorization	Bearer <YOUR_ACCESS_TOKEN>

Body

Parameter	Type	Description	Required
search	string	Text to search for in the catalog. Can include product names, brands, or other attributes
pageToken	string	Token for pagination, used to retrieve the next or previous page of results
entity	string	Entity identifier for personalized results
page	integer	Page number for pagination (starts at 0)
perPage	integer	Number of results to return per page
visitorId	string	Unique identifier for the visitor/user to enable personalized results
retailers	array<string>	Array of retailer identifiers
orderBy	string	Field to sort results by. Possible values: "price", "name", "brand", "price")
orderDirection	string	Sort direction. Possible values: "asc", "desc"
filters	array<filterParameters>	Array of filter objects to refine search results
loc	locType	Location object for determining real-time availability
isLegacy	boolean	Whether to return legacy identifiers
isLean	boolean	Whether to return a minimal response format
refresh	boolean	When set to true, a new access token will be generated and returned

Response Details

Field	Type	Description
statusCode	number	HTTP status code of the response
message	string	A brief message describing the result of the API call
metadata	metaDataObject	Contains metadata about the API call
auth	authObject	Authentication object, only when refresh in true
navigation	navigationSchema	Navigation schema
products	array<productType>	Array of matched products
retailers	array<retailerType>	Array of available retailers

Metadata Object

Field	Type	Description
languages	Array<string>	List of supported languages for the response, e.g. ["en"]
timestamp	string	Unix timestamp (in milliseconds) when the response was generated
timezone	string	Timezone used for the response, always "UTC"
requestId	string	Unique identifier for the API request. Used for debugging and support
path	string	API path
version	string	API version used for the request

Sample Request and Response

curl --location 'https://staging.api.liquidcommerce.cloud/catalog/search' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
    "search": "",
    "pageToken": "",
    "entity": "",
    "page": 0,
    "perPage": 10,
    "orderBy": "price",
    "orderDirection": "desc",
    "filters": [
        {
            "key": "categories",
            "values": [
                "SPIRITS > TEQUILA"
            ]
        },
        {
            "key": "engraving",
            "values": "YES"
        },
         {
            "key": "fulfillment",
            "values": [
                "onDemand"
            ]
        },
         {
            "key": "tags",
            "values": [
                "WOMAN OWNED"
            ]
        }
    ],
    "loc": {
        "address": {
            "one": "100 madison ave",
            "two": "apt 1707",
            "city": "New york",
            "state": "NY",
            "zip": "10016"
        }
    },
    "isLegacy": true,
    "isLean": false,
    "refresh": false
}
'

200

{
  "statusCode": 200,
  "message": "Liquid Catalog, unique AI driven product discovery and recommendations.",
  "metadata": {
    "languages": ["en"],
    "timestamp": 1731603976867,
    "timezone": "UTC",
    "requestId": "requestid_123abc456def",
    "path": "/api/catalog/search",
    "version": "1.7.0"
  },
  "navigation": {
    "correctedQuery": "",
    "attributionToken": "attr123",
    "currentPage": 0,
    "totalPages": 1,
    "totalCount": 2,
    "availableOrderBy": ["price"],
    "availableOrderDirection": ["asc", "desc"],
    "cursor": {
      "nextPageToken": "next123",
      "previousPageToken": "prev123"
    },
    "filters": [
      {
        "bucket": "brands",
        "values": [
          {
            "value": "CASA DRAGONES",
            "count": 2
          }
        ]
      }
    ]
  },
  "products": [
     {
        "id": "30d851c7dab529f303f4931b",
        "salsifyGrouping": "GROUPING-1445173",
        "name": "TEQUILA CASA DRAGONES AÑEJO BARREL BLEND",
        "brand": "CASA DRAGONES",
        "catPath": "Spirits > Tequila > Añejo",
        "category": "",
        "classification": "",
        "type": "",
        "subType": "",
        "region": "Jalisco",
        "country": "Mexico",
        "material": "Agave",
        "color": "White",
        "flavor": "",
        "variety": "",
        "appellation": "",
        "abv": "40",
        "proof": "80",
        "age": "2 Year",
        "vintage": "",
        "description": "Casa Dragones Barrel Blend, 100% Blue Agave Añejo tequila, achieves its distinctive character from being matured in two different wood barrels, new French Oak and new American Oak, each selected for their individual flavor and characteristics. At the end of the aging process, both barrel styles are blended together to create a uniquely smooth, agave-forward taste profile.",
        "htmlDescription": "<p>Casa Dragones Barrel Blend, 100% Blue Agave Añejo tequila, achieves its distinctive character from being matured in two different wood barrels, new French Oak and new American Oak, each selected for their individual flavor and characteristics. At the end of the aging process, both barrel styles are blended together to create a uniquely smooth, agave-forward taste profile.</p>",
        "tastingNotes": ""A subtle melange of flavors." - Wine Spectator",
        "images": [
            "https://example.com/images/product1.jpg"
        ],
        "sizes": [
            {
                "id": "6554c9a46b741e7ad37c8ad2",
                "upc": "00850005002161",
                "size": "750 ML",
                "volume": "750",
                "uom": "MILLILITRE",
                "container": "Bottle",
                "containerType": "",
                "pack": false,
                "packDesc": "",
                "image": "https://example.com/images/bottle1.jpg",
                "attributes": {
                    "engraving": {
                        "status": true,
                        "maxLines": 3,
                        "maxCharsPerLine": 16,
                        "fee": 5000,
                        "location": "Between the Labels"
                    }
                },
                "variants": [
                    {
                        "partNumber": "00850005002161_6565f4e8700628ce19106bc7",
                        "retailerId": "6565f4e8700628ce19106bc7",
                        "modalities": [
                            "shipping"
                        ],
                        "price": 14999,
                        "salePrice": 0,
                        "stock": 100,
                        "isEngravable": false,
                        "fulfillmentTypes": {
                            "shipping": "65830af0be8824843febdb8c",
                            "onDemand": ""
                        },
                        "fulfillments": [
                            "65830af0be8824843febdb8c"
                        ]
                    }                 
                ],
                "salsifyPid": "2216260"
            }
        ],
        "attributes": {
            "brandOrigin": "",
            "originStatement": "The wood used for their new French Oak barrels is a proprietary blend of 100% Quercus Sessile Oak, sustainably sourced from five different forests in the centre of France, then custom toasted to impart roundness and light spicy notes, while respecting the minerality of the soil. The new American Oak barrels receive a custom medium toast, imparting the complexity of the agave and a beautiful aromatic intensity.",
            "ownershipType": [
                "Woman Owned"
            ],
            "tags": [
                "Woman Owned"
            ],
            "images": {
                "backOfBottle": "",
                "frontOfBottle": "",
                "lifestyle": []
            },
            "awards": [],
            "recipes": [
                {
                    "image": "",
                    "ingredients": [
                        {
                            "name": "Casa Dragones Añejo Barrel Blend",
                            "amount": "2 oz."
                        },
                        {
                            "name": "Vanilla Agave Syrup",
                            "amount": "1/4 oz."
                        },
                        {
                            "name": "Bittermens Mole Bitters",
                            "amount": "2 dashes"
                        }
                    ],
                    "steps": [
                        "Stir with ice and strain into a chilled rocks glass with one large ice cube.",
                        "Garnish with a long mandarin orange twist."
                    ],
                    "title": "El Grito"
                }
            ],
            "video": [],
            "tastingNotes": [
                {
                    "statement": "Light caramel, with bright hues and pronounced legs.",
                    "image": "https://example.com/images/tasting1.png",
                    "title": "Body & Color"
                },
                {
                    "statement": "Fresh floral, pear with notes of figs and almonds.",
                    "image": "https://example.com/images/tasting2.png",
                    "title": "Aroma"
                },
                {
                    "statement": "Notes of macadamia, nutmeg and blackberry.",
                    "image": "https://example.com/images/tasting3.png",
                    "title": "Taste"
                },
                {
                    "statement": "Long round finish, notes of cacao, spicy black pepper.",
                    "image": "https://example.com/images/tasting4.png",
                    "title": "Finish"
                }
            ]
        }
    },
    {
      "id": "66ae3111e2e91f45afac28f7",
      "salsifyGrouping": "GROUPING-330410",
      "name": "Tequila Casa Dragones Reposado Mizunara",
      "brand": "Casa Dragones",
      "catPath": "Spirits > Tequila > Reposado",
      "region": "Jalisco",
      "country": "Mexico",
      "material": "Agave",
      "color": "Tawny/brown",
      "variety": "100% Blue Agave",
      "appellation": "Jalisco",
      "abv": "40",
      "proof": "80",
      "age": "1 Year",
      "description": "Casa Dragones Reposado Mizunara, 100% Blue Agave Reposado tequila; is the first tequila rested exclusively in new Mizunara casks, a rare oak native to Japan, traditionally used for aging Japanese whiskies.",
      "images": [
        "https://example.com/images/product2.jpg"
      ],
      "sizes": [
        {
          "id": "4efe5a4554660ad190c99d1c",
          "upc": "00850005002215",
          "size": "750 ML",
          "volume": "750",
          "uom": "MILLILITRE",
          "container": "Bottle",
          "image": "https://example.com/images/size2.jpg",
          "attributes": {
            "engraving": {
              "status": true,
              "maxLines": 3,
              "maxCharsPerLine": 16,
              "fee": 5000,
              "location": "Between the Labels"
            }
          },
          "variants": [
            {
              "partNumber": "8222419_b8fd6f32e6a47930f717c111",
              "retailerId": "c2c8a24ee2b876280e5e0fa3",
              "modalities": ["onDemand"],
              "price": 15999,
              "salePrice": 0,
              "stock": 100,
              "isEngravable": false,
              "fulfillments": ["26978cee5037ead268f3c0cc"]
            }
          ]
        }
      ],
      "attributes": {
        "tastingNotes": [
          {
            "statement": "Light, bright golden with a silky texture, and long pronounced legs.",
            "image": "https://example.com/images/tasting3.png",
            "title": "Body & Color"
          },
          {
            "statement": "Orange blossom, magnolia with gentle notes of honey and sandalwood.",
            "image": "https://example.com/images/tasting4.png",
            "title": "Aroma"
          }
        ]
      }
    }
  ],
  "retailers": [
    {
      "id": "ret_abc123xyz789",
      "name": "LiquidCommerce Wine & Spirits",
      "platformFee": 499,
      "address": {
        "one": "240 Loisaida Avenue",
        "two": "",
        "city": "New York",
        "state": "NY",
        "zip": "10009",
        "country": "US"
      },
      "fulfillments": [
        {
          "id": "ful_ghi189rst123",
          "timezone": "America/New_York",
          "type": "onDemand",
          "canEngrave": false,
          "fees": {
            "min": 1999,
            "fee": 0,
            "free": {
              "active": false,
              "min": 0
            }
          },
          "expectation": {
            "detail": "Arrives in 60 mins",
            "short": "60 mins"
          },
          "hours": {
            "monday": {
              "active": true,
              "times": [
                {
                  "startsAt": "10:00",
                  "endsAt": "21:00"
                }
              ]
            },
            "tuesday": {
              "active": true,
              "times": [
                {
                  "startsAt": "10:00",
                  "endsAt": "21:00"
                }
              ]
            },
            "wednesday": {
              "active": true,
              "times": [
                {
                  "startsAt": "10:00",
                  "endsAt": "21:00"
                }
              ]
            },
            "thursday": {
              "active": true,
              "times": [
                {
                  "startsAt": "10:00",
                  "endsAt": "21:00"
                }
              ]
            },
            "friday": {
              "active": true,
              "times": [
                {
                  "startsAt": "10:00",
                  "endsAt": "21:00"
                }
              ]
            },
            "saturday": {
              "active": true,
              "times": [
                {
                  "startsAt": "10:00",
                  "endsAt": "21:00"
                }
              ]
            },
            "sunday": {
              "active": true,
              "times": [
                {
                  "startsAt": "10:00",
                  "endsAt": "21:00"
                }
              ]
            }
          },
          "breaks": [],
          "items": []
        }
      ]
    },
    {
      "id": "ret_abc123xyz189",
      "name": "LiquidCommerce Barn",
      "platformFee": 499,
      "address": {
        "one": "1000 N 5th Ave",
        "two": "134",
        "city": "Vernon Hills",
        "state": "NY",
        "zip": "10061",
        "country": "US"
      },
      "fulfillments": [
        {
          "id": "ful_abc123xyz189",
          "timezone": "America/Chicago",
          "type": "shipping",
          "canEngrave": true,
          "fees": {
            "pack": {
              "active": true,
              "maxQuantity": 25,
              "fee": 1599
            },
            "individual": {
              "active": true,
              "maxQuantity": 25,
              "fee": 1599
            },
            "free": {
              "active": false,
              "min": 0
            }
          },
          "expectation": {
            "detail": "Ships in 2-3 days",
            "short": "2-3 days"
          },
          "hours": {
            "monday": {
              "active": false,
              "times": []
            },
            "tuesday": {
              "active": false,
              "times": []
            },
            "wednesday": {
              "active": false,
              "times": []
            },
            "thursday": {
              "active": false,
              "times": []
            },
            "friday": {
              "active": false,
              "times": []
            },
            "saturday": {
              "active": false,
              "times": []
            },
            "sunday": {
              "active": false,
              "times": []
            }
          },
          "breaks": [],
          "items": []
        }
      ]
    }
  ]
}