> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://api-docs.papertracc.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://api-docs.papertracc.com/_mcp/server.

# Overview

The catalogue is the set of products and collections available on the channel. A product appears when it is active and listed on the channel.

## Handles

Products and collections are addressed by `handle`, a URL-safe name such as `silk-scarf`. Use it in your own URLs. The collection handle `all` always exists and returns every listed product.

## Prices

Prices are decimal strings with a `currency` beside them. A product list shows a range across the product's variants; the product itself shows each variant's price. Pass `country` to price for a market other than the channel's default.

## What can be bought

| Field                | Meaning                                                                                                                          |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `available`          | The variant, or at least one variant of the product, can be bought now.                                                          |
| `price_on_request`   | The price is agreed at the point of sale. The product can be shown but not added to a cart.                                      |
| `default_variant_id` | The first variant that can be bought, for a one-click add to cart from a list.                                                   |
| `requestable`        | On Get Product: the product is sold through order requests. Show a request button and send it with Create Request. See Requests. |
| `request_form`       | On Get Product: questions to ask about the product, or `null`. In `BUY_NOW` mode the answers go on the cart item.                |

To add a product to a cart, send the `id` of one of its variants.

## Items not in stock yet

A variant can be sold before its stock arrives. Its `sell_mode` says how:

| `sell_mode`     | Meaning                                                                                                                    | What to show the shopper                                     |
| --------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `STOCK`         | Sells from stock. When `available` is `false`, it is sold out.                                                             | **Add to cart**                                              |
| `BACKORDER`     | Out of stock, but can still be bought. It ships when stock arrives, within `lead_time_days` of the order when that is set. | **Add to cart**, with "Out of stock, ships in about 14 days" |
| `PREORDER`      | Not released yet. It ships from `release_date`.                                                                            | **Pre-order**, with "Ships from 12 Dec"                      |
| `MADE_TO_ORDER` | Made or sourced after the order. It is ready `lead_time_days` after the order.                                             | **Add to cart**, with "Made for you, ready in 7 days"        |

Shoppers pay at checkout, so show the wait before they do. A variant only shows as `BACKORDER` while it is out of stock, and a pre-order becomes `STOCK` on its release date.

On a product list, the card's `sell_mode` is set only when every variant of the product sells the same way and that way is not `STOCK`, so you can badge the card. Otherwise it is `null`, and each variant on Get Product carries its own.