# Catalog

Use the catalog to turn a user's selection into the codes, answer time, and
initial photo requirements accepted by `POST /orders`. Resolve it at runtime
because availability, prices, labels, and photo requirements can change.

## Recommended lookup order

For a category-first picker:

1. Get a `category_code` from `GET /catalog/categories`.
2. Get a compatible `brand_code` from
   `GET /catalog/brands?category_code={category_code}`.
3. Optionally get a `model_code` from `GET /catalog/models` using the selected
   brand and category.
4. Get an available `answer_time` for the brand and category, then load the
   photo requirements for the selected category, brand, and optional model.
5. Send the returned codes unchanged in `POST /orders`.

Once brand and category are known, answer times and photo indexes can be loaded
in parallel. When a model is selected, pass its code to the photo-index request
as well. Providing category, brand, and model context produces the most precise
photo indexes and example photos for the item.

For a brand-first picker, start with unfiltered `GET /catalog/brands`, use its
nested `categories`, then make the same context-specific calls.

## Endpoint summary

Every endpoint accepts optional `locale`; supported values are `en` and `ja`.

| Endpoint | Required inputs | Other inputs | Returns |
| --- | --- | --- | --- |
| `GET /catalog/categories` | None | `brand_code`, `locale` | Category codes, labels, and optional icons. |
| `GET /catalog/brands` | None | `category_code`, `locale`, `page`, `limit` | Brand codes, labels, and nested categories. |
| `GET /catalog/models` | `brand_code`, `category_code` | `locale`, `page`, `limit` | Model codes, labels, and optional images. |
| `GET /catalog/answer_times` | `brand_code`, `category_code` | `locale` | Service-time codes, prices, suggested selections, and availability. |
| `GET /catalog/photo_indexes` | `category_code` | `brand_code`, `model_code`, `locale` | Photo index codes, requirements, limits, and example images. |

The [API Reference](/api) contains the complete schemas and error responses.

## Shared response rules

- Treat every returned `code` as an opaque request value. Send it exactly as
  returned; do not derive it from `name` or `name_locale`.
- Use `name` for English display and `name_locale` for localized display.
- Collections are returned in `data`. Brand and model responses also include
  pagination fields.

## Categories and brands

Use `brand_code` to load categories for a selected brand, or use
`category_code` to limit the brands offered for a selected category.

## Models

Models are always optional for order creation. Selecting one can make the photo
indexes and example images more precise for the item, helping users supply the
most relevant photos. Pass the selected `model_code` to both
`GET /catalog/photo_indexes` and `POST /orders`. If no model is selected, omit
it from both requests.

## Answer times

Load answer times after selecting a valid brand/category pair.

| Field | Use |
| --- | --- |
| `code` | Service time in minutes. Send this integer as `answer_time` in `POST /orders`. |
| `price` | Price in credits. |
| `default` | Suggested catalog selection. |
| `available` | Submit options whose current value is `true`. |
| `next_available_at` | Earliest known availability as an ISO 8601 timestamp, or `null`. |

Send a currently available `code`. An unavailable selection returns
`answer-time-unavailable`; see [Errors](/errors) for its details.

## Photo indexes

`GET /catalog/photo_indexes` requires `category_code` and accepts optional
`brand_code` and `model_code`. Supplying `model_code` also requires
`brand_code`, and the model must belong to that brand/category. Providing more
supported classification context makes the returned indexes and example images
more precise for the item.

| Field | Use for initial order creation |
| --- | --- |
| `code` | Send as `photos[].index_code`. |
| `required` | Include at least one photo for this code when `true`. |
| `photo_limit` | Maximum number of initial photos for this code. |
| `icon_url` | Optional display asset; can be `null`. |
| `example_urls` | Examples that can help a user capture the requested view. |

Build `photos` from the current catalog response and follow its `required` and
`photo_limit` values.

## Freshness

Cache display-oriented catalog data only for a bounded period. Refresh answer
times close to order submission, and reload photo indexes when the selected
brand, category, or model changes. See the [Quickstart](/quickstart) for a
complete order flow.