> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vortexiq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Catalogue API (preview)

> Planned read-only API for searching products from BigCommerce and Adobe Commerce stores whose merchants opted in to sharing their catalogue with Meta AI.

<Warning>
  **Preview: in development, not yet live.** This page describes the planned API so partners can review it. Endpoints, fields and limits may change before launch.
</Warning>

The Catalogue API lets an approved partner, starting with Meta AI, search products from stores whose merchants have chosen to share their catalogue. It is read-only. Shoppers buy on the merchant's own store.

```
https://app.vortexiq.ai/api/v1/catalog
```

## Endpoints

| Endpoint | Purpose |
| - | - |
| [`GET /products/search`](/integrations/meta-ai/catalogue-api/search-products) | Free-text search across opted-in stores |
| [`GET /products/{product_id}`](/integrations/meta-ai/catalogue-api/get-product) | One product by id |
| [`GET /merchants`](/integrations/meta-ai/catalogue-api/list-merchants) | Stores that are sharing |

The same three operations will also be available as MCP tools on `https://app.vortexiq.ai/mcp`.

## Which stores are included

* **Only opted-in stores.** A merchant turns sharing on per store in Vortex IQ Settings. Until they do, nothing from that store is returned. See [Show your products in Meta AI](/integrations/meta-ai/catalogue-sharing).
* **BigCommerce first,** then Adobe Commerce (including Magento Open Source) once those stores' catalogues are syncing to Vortex IQ.
* **Visible products only.** Products the merchant has hidden or disabled are never returned.

## One product format

BigCommerce and Adobe Commerce name their product fields differently. The API maps both to one shape, so a partner handles every store the same way.

```json theme={null}
{
  "id": "bc_3kgh3kz_1234",
  "merchant": {
    "id": "m_7f3c2a",
    "name": "Example Outdoor Co",
    "domain": "www.example-outdoor.com",
    "platform": "bigcommerce",
    "currency": "GBP"
  },
  "title": "Trail Runner 2 Waterproof Boot",
  "description": "Lightweight waterproof walking boot with a grippy sole.",
  "brand": "Example Outdoor",
  "categories": ["Footwear", "Walking Boots"],
  "price": { "amount": "119.00", "currency": "GBP" },
  "sale_price": { "amount": "99.00", "currency": "GBP" },
  "availability": "in_stock",
  "url": "https://www.example-outdoor.com/trail-runner-2/",
  "image_url": "https://cdn.example-outdoor.com/trail-runner-2.jpg",
  "sku": "TR2-WP-42",
  "updated_at": "2026-10-02T09:00:00Z"
}
```

* **Prices** are the price the store shows on the product page, in the store's own currency, as decimal strings.
* **Availability** is `in_stock`, `out_of_stock` or `preorder`. Exact stock counts are never exposed.
* **`url`** is the product page on the merchant's store. There is no basket or checkout in the API.

## What is never returned

Cost price, margins, stock counts, sales figures, customer data, order data, and anything from a store that has not opted in.

## Authentication

Approved partners receive credentials during onboarding and send `Authorization: Bearer <token>` on every request. Shoppers never sign in. This is separate from the merchant account linking used by the [MCP server](/integrations/meta-ai/overview#merchant-workspace-mcp-server).

## Errors and limits

Errors use the same shape as the OAuth endpoints: `{"error": "...", "error_description": "..."}`. Expect `400` for invalid parameters, `401` for a missing or invalid token, `404` for a product that is not shareable, and `429` with `Retry-After` when a rate limit is reached. Limits will be agreed with each partner.

## Specification

The OpenAPI 3.1 file for this preview is at [`/integrations/meta-ai/catalogue-api/openapi.json`](/integrations/meta-ai/catalogue-api/openapi.json).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.