Extended Catalog¶

Capability: dev.asp.services.catalog Version: 2026-02-19 Schema: catalog.json

Purpose¶

Retrieves a provider's complete catalog with hierarchical sections, items with pricing, and modifier groups for customization.

Endpoint¶

GET /catalog/{provider_id}/catalog

Response Structure¶

A catalog is organized as:

Service Catalog
├── provider_id, provider_name
└── sections[]
    ├── id, title
    └── items[]
        ├── id, title, description, price_cents, images[]
        └── modifier_groups[]
            ├── id, title, required, min/max_selections
            └── options[]
                ├── id, label, price_delta_cents

Schema: Catalog Item¶

Field	Type	Required	Description
`id`	string	Yes	Unique item identifier.
`title`	string	Yes	Display name of the item.
`description`	string	Yes	Item description.
`price_cents`	integer	Yes	Base price in cents.
`image`	[image]	Yes	Item image.
`modifier_groups`	array\<modifier_group>	No	Available customization groups for this item.
`is_available`	boolean	Yes	Whether this item is currently available for ordering. Default: `True`
`is_featured`	boolean	Yes	Whether this item is currently featured.
`tags`	array\<string>	No	Free-form tags relevant to this item, e.g. 'fast food', 'gourmet', 'date night', 'romantic'.
`images`	array\<image>	No	Multiple images for different contexts (thumbnail for list view, hero for detail page, etc.).

Schema: Modifier Group¶

Field	Type	Required	Description
`id`	string	Yes	Unique group identifier.
`title`	string	Yes	Display title for this modifier group.
`required`	boolean	No	Whether the user must select an option from this group. Default: `False`
`min_selections`	integer	No	Minimum number of options the user must select. Default: `0`
`max_selections`	integer	No	Maximum number of options the user may select. Default: `1`
`options`	array\<modifier_option>	Yes	Available options in this group.

Schema: Modifier Option¶

Field	Type	Required	Description
`id`	string	Yes	Unique option identifier.
`label`	string	Yes	Display label for this option.
`price_delta_cents`	integer	No	Price adjustment in cents when this option is selected. Default: `0`

Example¶

{
  "provider_id": "pizza-palace",
  "provider_name": "Pizza Palace",
  "sections": [
    {
      "id": "pizzas",
      "title": "Pizzas",
      "items": [
        {
          "id": "margherita",
          "title": "Margherita Pizza",
          "description": "Classic tomato, mozzarella, and basil",
          "price_cents": 1299,
          "images": [
            { "url": "https://img.example.com/margherita.jpg", "type": "thumbnail", "alt_text": "Margherita Pizza" }
          ],
          "modifier_groups": [
            {
              "id": "size",
              "title": "Size",
              "required": true,
              "min_selections": 1,
              "max_selections": 1,
              "options": [
                { "id": "small", "label": "Small", "price_delta_cents": 0 },
                { "id": "medium", "label": "Medium", "price_delta_cents": 300 },
                { "id": "large", "label": "Large", "price_delta_cents": 500 }
              ]
            },
            {
              "id": "extras",
              "title": "Extras",
              "required": false,
              "max_selections": 3,
              "options": [
                { "id": "extra-cheese", "label": "Extra Cheese", "price_delta_cents": 150 },
                { "id": "mushrooms", "label": "Mushrooms", "price_delta_cents": 100 }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Availability¶

Items include an is_available flag (default true). Unavailable items should be displayed as greyed-out or hidden, depending on the agent's UX.

Reorder¶

Agents can reorder from a previous order, receiving current availability and pricing for the original items.

Endpoint¶

POST /catalog/reorder

Request¶

Field	Type	Required	Description
`order_id`	string	Yes	The previous order to reorder from
`provider_id`	string	Yes	The provider of the original order
`scheduled_for`	datetime	No	Optional scheduled time (integrates with `available_for_scheduling`)

Response¶

Field	Type	Description
`items`	array of CatalogItem	Items from the original order with current availability and pricing
`unavailable_items`	array	Items no longer available, each with `item_id`, `title`, and `reason`

Example¶

{
  "order_id": "order-98765",
  "provider_id": "pizza-palace"
}

Response:

{
  "items": [
    {
      "id": "margherita",
      "title": "Margherita Pizza",
      "price_cents": 1299,
      "is_available": true
    }
  ],
  "unavailable_items": [
    {
      "item_id": "tiramisu",
      "title": "Tiramisu",
      "reason": "Out of stock"
    }
  ]
}