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

# Catalogs overview

> Choose between complete snapshots and fast granular catalog updates.

The Catalogs API lets a POS, middleware platform, or restaurant system publish and maintain the menu used by Chataigne.

Catalog identity is scoped by location. Your identifiers are stored as the public `id` and remain stable across updates. The same catalog and product IDs can be reused in another location; a catalog may also be attached to several locations without making its public ID global.

V1 lists and manages every catalog attached to the authorized location, including catalogs synchronized by a POS or created in the dashboard. Provider ownership remains private and does not make a catalog read-only. POS and API complete imports are serialized; if both systems write the same catalog, the last committed write wins. Deleting a catalog attached to several locations is rejected so a location-scoped request cannot remove another location's menu.

## Choose a write mode

| Need                                                     | Operation                                               | Behavior                                   |
| -------------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------ |
| Publish or reconcile the complete menu                   | `PUT /v1/locations/{location_id}/catalogs/{catalog_id}` | Asynchronous authoritative replacement     |
| Choose the menu used by the AI                           | `PUT /v1/locations/{location_id}/active_catalog`        | Immediate location-wide selection          |
| Change one category, product, modifier, group, or bundle | Resource `POST`, `PATCH`, or `DELETE`                   | Immediate targeted database write          |
| Read current menu data                                   | Catalog or resource `GET`                               | Returns public IDs and never internal SKUs |

Use a [complete snapshot](/catalogs/full-snapshot-sync) for initial imports and periodic POS synchronization. Use [granular updates](/catalogs/granular-updates) for low-latency price, name, relationship, or item changes between complete imports.

A location can contain several catalogs, but the AI orders from one active catalog. Follow [Select the active catalog](/catalogs/active-catalog) to replace the `active_catalog` singleton with a location-scoped public `catalog_id` after the catalog exists. The response echoes the selected public ID; Chataigne keeps its private catalog ID internal.

<Info>
  Complete snapshots and POS imports use Chataigne's shared catalog comparison and persistence
  engine. Granular updates do not compare the complete catalog; they resolve the requested `id`
  inside its parent and update only that resource.
</Info>

## Permissions

Reading requires `catalog.read`. Creating, synchronizing, and updating require `catalog.write`. Deleting requires `catalog.delete`.

## V1 scope

V1 manages categories, products, modifier groups, modifiers, and bundles. Products contain their base price, modifier-group IDs, operational state, conditional prices, and availability rules directly. Chataigne's internal SKU is never present in requests or responses.

Products, modifiers, and bundles use the same operational fields. `disabled: true` hides the resource and prevents ordering. `out_of_stock: true` keeps it visible but temporarily unavailable. `restrictions` define sale windows and service types; `price_overrides` define conditional prices. Products additionally expose `bundle_only` and an optional input `order`.

Promotions, catalog settings other than active-catalog selection, primary or hidden categories, best-seller flags, taxes, delivery-package metadata, provider metadata, and multi-SKU products are not managed by this API version.