Search catalog products
Searches products in the marketplace catalog.
Search the catalog
- MockDevelopment only
- Mercado LivreNot supported
- MagaluPlanned
- AmazonPlanned
- TikTok ShopPlanned
- ShopeePlanned
Search by text (query, the name) or by code (identifier, such as the GTIN). Send one of them; with neither, the answer is 400. categoryId filters. Each result has name, brand, category, identifiers and pictures.
To find a product by its GTIN:
curl "$BACKEND_URL/v1/connections/$CONNECTION_ID/catalog-products?identifier=7890000000017" \
-H "Authorization: Bearer mk_your_api_key"If the catalog does not have the code, the answer is 200 with empty data, not 404.
Use it when the marketplace asks the listing to point to a catalog product. One product in detail: Get catalog product. To link a catalog product to a MarketplaceProduct, see Catalog reference.
Part of Publish listings.
Synchronous read
Like the other discovery routes, the search answers right away, with no Job, within the adapter's time limit. If the marketplace does not answer, you get 503 MARKETPLACE_UNAVAILABLE and can try again. See List categories and Errors.
api_keyAuthorizationBearer <token>API key (mk_...)
id*stringIdentifier of the resource, as returned by the API.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidpage?integerPage number, starting at 1. Defaults to 1. A page beyond pagination.totalPages is not an error: it returns empty data.
1 <= value <= 90071992547409911pageSize?integerItems per page, from 1 to 100. Defaults to 20.
1 <= value <= 10020query?stringSearch by name.
1 <= length <= 200identifier?stringSearch by a code of the product, such as its GTIN.
1 <= length <= 200categoryId?stringOnly products of this category.
1 <= length <= 200One page of catalog products that match query (name) or identifier (a code such as the GTIN). pagination carries the totals.
application/json- response
One page of catalog products.
data*array<>The catalog products of this page, best match first.
pagination*Where this page sits in the whole listing: the totals and whether there are pages before and after it.
curl -X GET "https://example.com/v1/connections/3d1c8a52-7f0e-4b0a-8a65-9c1b2f6d7e01/catalog-products"{ "data": [ { "id": "mock-catalog-phone-1", "name": "Acme Phone One", "brand": "Acme", "categoryId": "mock-cellphones", "productType": "CELLULAR_PHONE", "identifiers": [ { "type": "GTIN", "value": "7890000000017" } ], "pictures": [ { "url": "https://example.com/pictures/acme-phone-one.jpg" } ], "marketplaceData": {} } ], "pagination": { "page": 1, "pageSize": 20, "totalItems": 57, "totalPages": 3, "hasNext": true, "hasPrev": false }}