> ## Documentation Index > Fetch the complete documentation index at: https://docs.mentionlab.io/llms.txt > Use this file to discover all available pages before exploring further. # List shopping products with merchant URLs > Returns a paginated list of the project's shopping products with their brand details and merchant URLs, filterable by brand, product, name search and external id. ## OpenAPI ````yaml https://api.mentionlab.io/api/docs-json post /api/shopping-products/items openapi: 3.0.0 info: title: MentionLab Public API v0.3.4-rc description: '' version: 0.3.4-rc contact: {} servers: - url: https://api.mentionlab.io security: [] tags: [] paths: /api/shopping-products/items: post: tags: - Shopping Products summary: List shopping products with merchant URLs description: >- Returns a paginated list of the project's shopping products with their brand details and merchant URLs, filterable by brand, product, name search and external id. operationId: ShoppingProductsController_getItems parameters: - name: limit required: false in: query schema: type: integer minimum: 1 maximum: 200 default: 50 - name: page required: false in: query schema: type: integer minimum: 1 default: 1 - name: x-project-id in: header description: Project ID to specify the project context required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/GetItemsDto' responses: '200': description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/PagingResponse' properties: results: type: array items: $ref: '#/components/schemas/ShoppingItemResponse' page: $ref: '#/components/schemas/Paging' '400': description: >- The request failed validation — the body, query or path parameters are malformed or out of range. content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '401': description: The request is missing valid authentication credentials. content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' '403': description: >- The authenticated principal lacks the required permission, or access to the requested organisation/project. content: application/json: schema: $ref: '#/components/schemas/ApiErrorResponse' components: schemas: GetItemsDto: type: object properties: entityIds: description: Filter by brand entity IDs. example: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 type: array items: type: string productIds: description: Filter by product IDs. example: - 7c9e6679-7425-40de-944b-e07fc1f90ae7 type: array items: type: string search: type: string description: Search by raw product name (partial match, case-insensitive). example: iPhone externalId: type: string description: Filter by exact external ID. example: product-123-abc mappingStatus: type: array description: >- Filter by product-mapping status. "unknown" = a brand is assigned but no specific product; "not_matched" = neither a brand nor a product. Omit to return all items. example: - unknown items: type: string enum: - unknown - not_matched PagingResponse: type: object properties: page: $ref: '#/components/schemas/Paging' required: - page ShoppingItemResponse: type: object properties: id: type: string description: Shopping product row ID. format: uuid example: d290f1ee-6c54-4b01-90e6-d701748f0851 initiatedAt: format: date-time type: string description: Timestamp when the product was captured. example: '2026-06-08T14:30:00.000Z' jobExecutionId: type: string description: ID of the job execution (run) that produced this product. format: uuid example: b4f0c2a1-9d3e-4f5a-8c7b-1e2d3f4a5b6c externalId: type: string description: External ID from the source. example: B0CQXYZABC rawName: type: string description: Raw product name as extracted. example: Apple iPhone 15 Pro 256GB Natural Titanium positionRank: type: number description: Position rank in the shopping results. example: 1 imageUrl: type: string description: Product image URL. example: https://m.media-amazon.com/images/I/81dT7CUY6GL._AC_SL1500_.jpg price: type: number description: Product price. example: '999.99' nullable: true priceCurrency: type: string description: Product price currency. example: USD starRating: type: number description: Product star rating. example: 4.5 nullable: true reviewCount: type: number description: Number of product reviews. example: 1234 nullable: true entityId: type: string description: Resolved brand entity ID. format: uuid example: f1c2d3e4-5a6b-7c8d-9e0f-1a2b3c4d5e6f entityName: type: string description: Resolved brand entity name. example: Apple productId: type: string description: Resolved product ID. format: uuid example: a7b8c9d0-1e2f-3a4b-5c6d-7e8f9a0b1c2d productName: type: string description: Resolved product name. example: iPhone 16 Pro merchantUrls: description: Merchant URLs where this product is available. example: - url: https://www.amazon.com/dp/B0CQXYZABC merchantName: Amazon merchantDomain: amazon.com price: 999.99 priceCurrency: USD merchantPosition: 1 aboveFold: true shippingPrice: 7.9 availability: true details: In stock online, Delivery $7.90 type: array items: $ref: '#/components/schemas/ShoppingItemMerchantUrl' required: - id - initiatedAt - jobExecutionId - rawName - positionRank - price - reviewCount - merchantUrls Paging: type: object properties: totalRecords: type: number limit: type: number currentPage: type: number totalPages: type: number nextPage: type: number prevPage: type: number required: - totalRecords - limit - currentPage - totalPages - nextPage - prevPage ApiErrorResponse: type: object properties: statusCode: type: number description: HTTP status code of the error. example: 400 message: type: string description: >- Human-readable description of the error. Validation failures return an array of per-field validation errors instead of a single string. example: Validation failed error: type: string description: Short name of the HTTP error. example: Bad Request required: - statusCode ShoppingItemMerchantUrl: type: object properties: url: type: string description: Merchant product page URL. example: https://www.amazon.com/dp/B0CQXYZABC merchantName: type: string description: Merchant display name. example: Amazon merchantDomain: type: string description: Merchant domain (e.g. amazon.com). Null if not set. example: amazon.com price: type: number description: Merchant-specific price. example: '999.99' nullable: true priceCurrency: type: string description: Merchant-specific price currency. example: USD merchantPosition: type: number description: >- 1-based rank of this merchant in ChatGPT's offer list for the product. Null if unknown. example: 1 nullable: true aboveFold: type: boolean description: >- Whether the merchant was shown by default (true) or hidden behind "Show more offers" (false). Null if unknown. example: true nullable: true shippingPrice: type: number description: >- Shipping cost in the offer's currency: 0 = free, > 0 = the cost, null = unknown. example: 7.9 nullable: true availability: type: boolean description: Whether the offer is in stock / available. Null if unknown. example: true nullable: true details: type: string description: >- Verbatim stock + delivery string shown for this offer (localized, unstructured), e.g. "In stock online, Delivery €7.90". Null if unknown. example: In stock online, Delivery €7.90 nullable: true required: - url - merchantName - price - merchantPosition - aboveFold - shippingPrice - availability - details ````