> ## Documentation Index > Fetch the complete documentation index at: https://docs.salesive.com/llms.txt > Use this file to discover all available pages before exploring further. # List products > Retrieve a paginated set of catalog items with optional search and filter options. ## Request ```http theme={null} GET /products?page=1&limit=10 x-shop-id: {{shopId}} ``` ## Headers | Header | Type | Description | | ----------- | ------ | -------------------------- | | `x-shop-id` | string | Identify the shop context. | ## Query parameters | Parameter | Type | Description | | ---------- | ------- | ---------------------------------------------------------------------------------------------------------- | | `page` | integer | Page number to return (default: `1`). | | `limit` | integer | Maximum number of items per page (default: `10`). | | `q` | string | Search string applied to item name or description. `search` is accepted as an alias. | | `sort` | string | Sort order. One of `newest` (default), `oldest`, `price_asc`, `price_desc`, `name_asc`, `name_desc`. | | `category` | string | Filter by category. Accepts the category **id, slug, or name**. An unknown category returns an empty page. | | `stock` | string | Availability filter. `in` (in stock) or `out` (out of stock). | | `featured` | boolean | When `true`, returns only featured items; when `false`, returns only non-featured items. | **Filtering is allow-listed.** Only the parameters above affect the query. Any other query string (for example a cache-buster like `?_=1718…` or an unknown key) is ignored and never narrows the result set — so pagination totals stay stable regardless of extra params. Filtering by a category slug or name resolves to the matching category automatically. The catalog adapts to the shop type and is returned in a `catalogType` field: * **ecommerce** → `catalogType: "product"` * **restaurant** → `catalogType: "food"` (also includes a `foods` alias) * **business** → `catalogType: "service"` (also includes a `services` alias) The `products` key is always kept for compatibility and holds the same array, and every item carries an `itemType` of `product`, `food`, or `service`. Service items include their `addons` and `video`, and (like foods) have no variants or category. ## Successful response ```json theme={null} { "status": 200, "success": true, "message": "Foods found", "data": { "products": [ { "_id": "68e5bb463a1fc56a8ac150c0", "shop": { "_id": "68b8f52575da81b332af29f1", "name": "Sample Kitchen", "currency": { "_id": "68c54dd440e9beff3260c2b2", "name": "Nigerian Naira", "symbol": "₦", "code": "NGN", "id": "68c54dd440e9beff3260c2b2" }, "logo": "https://cdn.salesive.com/logos/shop.webp", "id": "68b8f52575da81b332af29f1" }, "category": { "_id": "69fb494ddf63302ed89ba11d", "name": "Pizza", "id": "69fb494ddf63302ed89ba11d" }, "createdAt": "2026-05-06T13:59:42.799Z", "description": "

Stone-baked pizza with basil and tomato sauce

", "featured": false, "images": [ "https://cdn.salesive.com/foods/margherita.webp" ], "name": "Margherita Pizza", "price": 8500, "promoPrice": 7500, "updatedAt": "2026-05-06T14:44:04.903Z", "video": null, "available": true, "addons": [ { "_id": "68e5bb463a1fc56a8ac150d1", "name": "Extra Cheese", "description": "A richer mozzarella finish baked on top.", "price": 1500, "maxQuantity": 3, "image": null, "available": true } ], "id": "68e5bb463a1fc56a8ac150c0", "inWishlist": false, "itemType": "food" } ], "foods": [ { "_id": "68e5bb463a1fc56a8ac150c0", "name": "Margherita Pizza", "itemType": "food" } ], "catalogType": "food", "pagination": { "total": 61, "page": 1, "limit": 10, "pages": 7, "hasNext": true, "hasPrev": false, "nextPage": 2, "prevPage": null } } } ``` ## Notes * For standard shops, the message remains `"Products found"` and `catalogType` is `"product"`. * For authenticated users, the API still includes `inWishlist` on each returned item. ## Error response ```json theme={null} { "status": 500, "success": false, "message": "Internal server error", "data": {} } ``` ## OpenAPI ````yaml GET /products openapi: 3.1.0 info: title: Salesive Store API description: >- REST interface for querying products, categories, and merchandising banners exposed by Salesive storefronts. version: 1.0.0 servers: - description: Production url: https://store.salesive.com/api/v1 security: - BearerAuth: [] ShopIdHeader: [] paths: /products: get: summary: List products description: Retrieve a paginated list of products with optional search filtering. parameters: - $ref: '#/components/parameters/XShopIdHeader' - name: page in: query description: Page number to return (defaults to 1). schema: type: integer minimum: 1 default: 1 - name: limit in: query description: Maximum number of products per page (defaults to 10). schema: type: integer minimum: 1 default: 10 - name: q in: query description: Optional search phrase applied to product names or descriptions. schema: type: string responses: '200': description: Paginated products response. content: application/json: schema: $ref: '#/components/schemas/ProductCollection' components: parameters: XShopIdHeader: name: x-shop-id in: header description: >- Optional identifier that scopes responses to a specific storefront when the referer cannot be inferred. required: false schema: type: string schemas: ProductCollection: type: object required: - products properties: products: type: array items: $ref: '#/components/schemas/Product' foods: type: array items: $ref: '#/components/schemas/Product' description: Compatibility alias returned for food storefronts. catalogType: type: string enum: - product - food - service pagination: type: object properties: total: type: integer minimum: 0 page: type: integer minimum: 1 limit: type: integer minimum: 1 pages: type: integer minimum: 1 hasNext: type: boolean hasPrev: type: boolean nextPage: type: - integer - 'null' prevPage: type: - integer - 'null' Product: type: object required: - id - name - price properties: id: type: string description: Unique product identifier. itemType: type: string enum: - product - food - service description: Catalog item type. catalogType: type: string enum: - product - food - service description: Catalog response type for the current storefront. name: type: string description: Display name of the product. description: type: string description: Rich description of the product. price: type: number format: float description: Unit price for the product. currency: type: string description: ISO currency code for the product price. category: type: string description: Identifier of the category the product belongs to. status: type: string description: Derived status such as active or archived. images: type: array items: type: string format: uri description: Optional list of image URLs for the product. addons: type: array items: $ref: '#/components/schemas/FoodAddon' description: Available add-ons for food catalog items. variants: type: array items: type: object properties: sku: type: string options: type: object additionalProperties: type: string stock: type: integer minimum: 0 description: Optional list of variant definitions for the product. FoodAddon: type: object required: - name - price - maxQuantity - available properties: _id: type: string name: type: string description: type: string description: >- Optional helper text shown in the UI and returned by add-on endpoints. price: type: number maxQuantity: type: integer minimum: 1 image: type: - string - 'null' format: uri available: type: boolean securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: JWT issued by the Salesive Store API for authenticated shoppers. ShopIdHeader: type: apiKey in: header name: x-shop-id description: >- Optional storefront identifier sent as a header to scope responses to a specific shop. Try It requests remember this value once provided. ````