Search Products

Searching products

Contents

• Overview
• Permissions and Authentication
• Headers
• Query parameters
• Sample request
• Sample response

Overview

• Call name: search-products
• Endpoint URL: https://{Services API hostname}/search/products
• Request methods: HTTP POST
• Request Content-Type: application/x-www-form-urlencoded
• Response Content-Type: application/json
• Auth required: yes

This endpoint searches for both products and product variants in a single request. The search matches against product name, description, owner code, brand, and category fields for products, and against product variant name and barcodes for product variants. Results are ranked by relevance, with stronger matches on the product name weighted highest.

The response returns a JSON object containing two arrays: products and product_variants. If you only need product variants, consider using the dedicated Search Product Variants endpoint instead.

Permissions and Authentication

This API call requires admin authentication:

• The performing user must be logged in and have access to the chain specified in the request
• A valid admin session is required (see Authentication)

Headers

The following headers are required:

Header	Description
X-Spaaza-Session-User-Id	Spaaza ID of the user obtained from the login endpoint
X-Spaaza-Session-Key	Session key obtained from the login endpoint
X-Spaaza-Session-Chain-Id	The ID of the Spaaza chain or retailer

Query parameters

This API accepts the following parameters, sent as application/x-www-form-urlencoded form data:

Parameter	Description
chain_id	(integer, required) The ID of the Spaaza chain or retailer
query	(string, required) The search term(s). Matches against product name, description, owner code, brand, category, and product variant name and barcodes
page	(integer, required) The page number of results (starting from 1)
count	(integer, optional) Number of results to return per page. Defaults to 10 if not specified

Sample request

curl -X POST \
  -H 'X-Spaaza-Session-User-Id: <your user ID>' \
  -H 'X-Spaaza-Session-Key: <your session key>' \
  -H 'X-Spaaza-Session-Chain-Id: <your chain ID>' \
  -d 'chain_id=<your chain ID>' \
  -d 'query=Merino Jumper' \
  -d 'page=1' \
  -d 'count=25' \
  'https://{Services API hostname}/search/products'

Sample response

The response is a JSON object with two arrays: products containing matching products, and product_variants containing matching product variants.

{
    "products": [
        {
            "brand": "Aran Brands Inc.",
            "category": "knitwear",
            "chain_id": 1743,
            "cost_price": 79.95,
            "created_date": "2026-03-15T10:30:00Z",
            "currency": {
                "id": 1,
                "code": "EUR",
                "name_en": "Euro",
                "symbol": "\u20ac"
            },
            "deleted": false,
            "description": "The Aran Jumper is a style of jumper that takes its name from the Aran Islands.",
            "id": 5,
            "image_url": "https://www.example.com/images/arran.jpg",
            "last_modified_date": "2026-06-01T14:22:00Z",
            "name": "Men's Merino Aran Jumper",
            "owner_code": "00024003",
            "price": 99.95,
            "price_is_promotional": false,
            "season": "",
            "web_url": "https://www.example.com/products/arran-jumper"
        }
    ],
    "product_variants": [
        {
            "barcodes": [
                {
                    "barcode": "2000042436020",
                    "created_date": "2026-03-15T10:30:00Z",
                    "deleted": false,
                    "id": 3,
                    "last_modified_date": "2026-06-01T14:22:00Z",
                    "product_variant_id": 12
                }
            ],
            "chain_id": 1743,
            "colour": "blue",
            "cost_price": 79.95,
            "created_date": "2026-03-15T10:30:00Z",
            "currency": {
                "id": 1,
                "code": "EUR",
                "name_en": "Euro",
                "symbol": "\u20ac"
            },
            "deleted": false,
            "id": 12,
            "image_url": "https://www.example.com/images/blue_arran.jpg",
            "last_modified_date": "2026-06-01T14:22:00Z",
            "name": "Men's Merino Aran Jumper - Blue M",
            "price": 99.95,
            "price_is_promotional": false,
            "product": {
                "brand": "Aran Brands Inc.",
                "category": "knitwear",
                "chain_id": 1743,
                "cost_price": 79.95,
                "created_date": "2026-03-15T10:30:00Z",
                "currency": {
                    "id": 1,
                    "code": "EUR",
                    "name_en": "Euro",
                    "symbol": "\u20ac"
                },
                "deleted": false,
                "description": "The Aran Jumper is a style of jumper that takes its name from the Aran Islands.",
                "id": 5,
                "image_url": "https://www.example.com/images/arran.jpg",
                "last_modified_date": "2026-06-01T14:22:00Z",
                "name": "Men's Merino Aran Jumper",
                "owner_code": "00024003",
                "price": 99.95,
                "price_is_promotional": false,
                "season": "",
                "web_url": "https://www.example.com/products/arran-jumper"
            },
            "size": "M",
            "web_url": "https://www.example.com/products/arran-jumper-blue-m"
        }
    ]
}

Product fields

Field	Type	Description
brand	string	The brand name of the product
category	string	The product category
chain_id	integer	The chain ID the product belongs to
cost_price	float	The cost price of the product
created_date	string	ISO 8601 datetime when the product was created
currency	object	Currency information including id, code, name_en, symbol
deleted	boolean	Whether the product has been deleted
description	string	The product description
id	integer	Unique product identifier
image_url	string	URL to the product image
last_modified_date	string	ISO 8601 datetime when the product was last modified
name	string	The product name
owner_code	string	The retailer's own code for the product
price	float	The retail price of the product
price_is_promotional	boolean	Whether the current price is a promotional price
season	string	The product season
web_url	string	URL to the product on the retailer's website

Product variant fields

Field	Type	Description
barcodes	array	Array of barcode objects (see below)
chain_id	integer	The chain ID the variant belongs to
colour	string	The colour of the variant
cost_price	float	The cost price of the variant
created_date	string	ISO 8601 datetime when the variant was created
currency	object	Currency information including id, code, name_en, symbol
deleted	boolean	Whether the variant has been deleted
id	integer	Unique product variant identifier
image_url	string	URL to the variant image
last_modified_date	string	ISO 8601 datetime when the variant was last modified
name	string	The variant name
price	float	The retail price of the variant
price_is_promotional	boolean	Whether the current price is a promotional price
product	object	The parent product object (same structure as product fields above)
size	string	The size of the variant
web_url	string	URL to the variant on the retailer's website

Barcode fields

Field	Type	Description
barcode	string	The barcode value
created_date	string	ISO 8601 datetime when the barcode was created
deleted	boolean	Whether the barcode has been deleted
id	integer	Unique barcode identifier
last_modified_date	string	ISO 8601 datetime when the barcode was last modified
product_variant_id	integer	The ID of the product variant the barcode belongs to