​
Overview

This API allows you to search and filter products across multiple stores using store-specific parameters. You can control which stores to include, specify which store-level fields to retrieve, and apply filters at the store level.

​
HTTP Method

This API uses the GET method at the endpoint search to search and filter products.

​
API Endpoint

The base URL for Multi-Store-API is https://api.example.com/search

​
Parameters

​
Header Parameters

Below parameters should pass in the HTTP headers of an API request.

Header NameTypeDescriptionExample ValueRequired
AuthorizationStringBearer token used for authenticating the userBearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...Yes
Content-TypeStringSpecifies the format of the request dataapplication/jsonYes

​
Query Parameters

ParameterTypeDescriptionExampleRequired
store.idStringSpecify a single store. Can be used multiple times to specify multiple storesstore.id=store1&store.id=store2Yes
store.idsStringComma_separated list of store IDs (alternative to using multiple store.id parameters)store.ids=store1,store2,store3Yes
store.fieldsStringComma_separated list of store level fields to include in the responsestore.fields=store_price,store_availabilityYes
store.filterStringStore level filters, supports multiple values combined via AND logicstore.filter=store_price:[100 TO *]&store.filter=store_availability:trueYes

​
Example Request Body

The below example retrieves products from store1 and store2 and returns only the store-level fields store_price and store_availability, and filters for products:

  • where store_price > 100, and
  • products that are currently available.
GET /search?store.ids=store1,store2&store.fields=store_price,store_availability&store.filter=store_price:[100 TO *]&store.filter=store_availability:true HTTP/1.1

Host: api.example.com

Authorization: Bearer eyJhbGciOi...

Content-Type: application/json

​
Sample Successful Response

{
  "products": [
    {
      "product_id": "prod_12345",
      "name": "Running Shoes",
      "stores": [
        {
          "store_id": "store1",
          "store_price": 120,
          "store_availability": true
        },
        {
          "store_id": "store2",
          "store_price": 130,
          "store_availability": true
        }
      ]
    }
  ]
}

​
Error Codes

Status CodeError CodeMessageDescription
400invalid_paramsOne or more query parameters are malformedProvided filter format is incorrect or an unsupported field is used
401unauthorizedMissing or invalid authentication tokenBearer token not provided or expired
403forbiddenAccess to the requested stores or data is deniedToken lacks permission for the requested stores
500server_errorAn unexpected error occurredContact support if the issue persists

​
Best Practices

  • Usestore.ids over multiple store.id parameters for readability.
  • Use store.fields to avoid bloated responses.
  • Avoid over-filtering in a single request, as it may impact performance.
  • You can combine filters carefully to fine-tune your results.