Product lists (product_list)

Show 2-24 products as a grid or list; the person picks one or several; the page records the picks and buys nothing. The result is { items: [{ productId, quantity }] }.

When to use it: The person picks one product, or several with quantities, from 2-24 search results or recommendations shown as a grid or list. The page only records the picks: add them to a cart or order them yourself afterwards, and do not tell the person it is done until you have.

When not to use it: Do not use it for one product (use product) or for more than 24 products: narrow the list first.

Gather first:

• Products that match what the person asked for, with real prices and photos.
• Whether they pick one (mode: "single") or several to fill a cart ("multiple").

Writing good content:

• Include a photo for every product: a grid without photos is hard to scan.
• Use categories and each product's categoryId when the list mixes kinds, so the person can filter.
• Use compareAtPrice only for a real original price, higher than price.
• The answer is the picked products and quantities. Act on them yourself afterwards.

Fields

Every page also has version (always 1), title, and optionally description, branding, cover (a header photo) and expiresAt; see Page fields. These are the fields of page (the page type and its data):

Why these are required: Each card needs an id, a name and a price; 2-24 products.

When optional fields are left out: Single choice in a 2-column grid; no filter chips; every product can be picked once; a grey box instead of a photo. maxSelections and maxQuantity need mode multiple. Tapping a card selects it; there is no detail sheet and no per-product options (send a product page for that, or list each size or color as its own card).

Minimal example

Only the required fields:

{
  "version": 1,
  "title": "Which one do you want?",
  "page": {
    "type": "product_list",
    "products": [
      {
        "id": "mug",
        "name": "Enamel camp mug",
        "price": {
          "amount": 18,
          "currency": "USD"
        }
      },
      {
        "id": "bottle",
        "name": "Steel water bottle",
        "price": {
          "amount": 29,
          "currency": "USD"
        }
      },
      {
        "id": "flask",
        "name": "Insulated coffee flask",
        "price": {
          "amount": 36,
          "currency": "USD"
        }
      }
    ]
  }
}

Full example

{
  "version": 1,
  "title": "Gift ideas under $100",
  "description": "Six picks for your sister. Tap the one you like.",
  "branding": {
    "name": "Juniper Market",
    "accentColor": "#2f5d50"
  },
  "page": {
    "type": "product_list",
    "products": [
      {
        "id": "linen-shirt-sage-m",
        "name": "Linen camp shirt",
        "description": "Sage · M",
        "price": {
          "amount": 68,
          "currency": "USD"
        },
        "photo": {
          "url": "https://images.example.test/shop/linen-shirt-sage-1.jpg",
          "alt": "Sage linen camp shirt"
        },
        "rating": 4.7,
        "reviewCount": 212,
        "badge": "New",
        "categoryId": "tops"
      },
      {
        "id": "canvas-tote",
        "name": "Canvas market tote",
        "price": {
          "amount": 32,
          "currency": "USD"
        },
        "photo": {
          "url": "https://images.example.test/shop/canvas-tote-1.jpg",
          "alt": "Natural canvas tote bag with leather handles"
        },
        "rating": 4.9,
        "reviewCount": 540,
        "badge": "Bestseller",
        "categoryId": "bags"
      },
      {
        "id": "wool-throw",
        "name": "Waffle wool throw",
        "price": {
          "amount": 96,
          "currency": "USD"
        },
        "compareAtPrice": {
          "amount": 128,
          "currency": "USD"
        },
        "photo": {
          "url": "https://images.example.test/shop/wool-throw-1.jpg",
          "alt": "Oatmeal waffle-knit wool throw"
        },
        "categoryId": "home"
      },
      {
        "id": "stoneware-mug",
        "name": "Speckled stoneware mug",
        "price": {
          "amount": 24,
          "currency": "USD"
        },
        "photo": {
          "url": "https://images.example.test/shop/stoneware-mug-1.jpg",
          "alt": "Speckled cream stoneware mug"
        },
        "rating": 4.6,
        "reviewCount": 88,
        "categoryId": "home"
      },
      {
        "id": "cord-cap",
        "name": "Corduroy cap",
        "price": {
          "amount": 38,
          "currency": "USD"
        },
        "photo": {
          "url": "https://images.example.test/shop/cord-cap-1.jpg",
          "alt": "Rust corduroy six-panel cap"
        },
        "available": false,
        "categoryId": "bags"
      },
      {
        "id": "merino-tee",
        "name": "Merino crew tee",
        "description": "Charcoal · L",
        "price": {
          "amount": 54,
          "currency": "USD"
        },
        "photo": {
          "url": "https://images.example.test/shop/merino-tee-1.jpg",
          "alt": "Charcoal merino crew-neck tee, folded"
        },
        "categoryId": "tops"
      }
    ],
    "categories": [
      {
        "id": "tops",
        "label": "Tops"
      },
      {
        "id": "bags",
        "label": "Bags & hats"
      },
      {
        "id": "home",
        "label": "Home"
      }
    ]
  }
}

Result

When the person submits, the result has these fields:

For the full example above, a result could be:

{
  "items": [
    {
      "productId": "canvas-tote",
      "quantity": 1
    }
  ]
}

Send it

eve, AI SDK and MCP

With @pagesystems/eve, @pagesystems/ai-sdk or the MCP server, the model calls get_page_type_schema with "product_list" (the same JSON as GET /v1/page-types/product_list), then create_page with this input (no version or branding; branding comes from your dashboard):

{
  "title": "Gift ideas under $100",
  "description": "Six picks for your sister. Tap the one you like.",
  "page": {
    "type": "product_list",
    "products": [
      {
        "id": "linen-shirt-sage-m",
        "name": "Linen camp shirt",
        "description": "Sage · M",
        "price": {
          "amount": 68,
          "currency": "USD"
        },
        "photo": {
          "url": "https://images.example.test/shop/linen-shirt-sage-1.jpg",
          "alt": "Sage linen camp shirt"
        },
        "rating": 4.7,
        "reviewCount": 212,
        "badge": "New",
        "categoryId": "tops"
      },
      {
        "id": "canvas-tote",
        "name": "Canvas market tote",
        "price": {
          "amount": 32,
          "currency": "USD"
        },
        "photo": {
          "url": "https://images.example.test/shop/canvas-tote-1.jpg",
          "alt": "Natural canvas tote bag with leather handles"
        },
        "rating": 4.9,
        "reviewCount": 540,
        "badge": "Bestseller",
        "categoryId": "bags"
      },
      {
        "id": "wool-throw",
        "name": "Waffle wool throw",
        "price": {
          "amount": 96,
          "currency": "USD"
        },
        "compareAtPrice": {
          "amount": 128,
          "currency": "USD"
        },
        "photo": {
          "url": "https://images.example.test/shop/wool-throw-1.jpg",
          "alt": "Oatmeal waffle-knit wool throw"
        },
        "categoryId": "home"
      },
      {
        "id": "stoneware-mug",
        "name": "Speckled stoneware mug",
        "price": {
          "amount": 24,
          "currency": "USD"
        },
        "photo": {
          "url": "https://images.example.test/shop/stoneware-mug-1.jpg",
          "alt": "Speckled cream stoneware mug"
        },
        "rating": 4.6,
        "reviewCount": 88,
        "categoryId": "home"
      },
      {
        "id": "cord-cap",
        "name": "Corduroy cap",
        "price": {
          "amount": 38,
          "currency": "USD"
        },
        "photo": {
          "url": "https://images.example.test/shop/cord-cap-1.jpg",
          "alt": "Rust corduroy six-panel cap"
        },
        "available": false,
        "categoryId": "bags"
      },
      {
        "id": "merino-tee",
        "name": "Merino crew tee",
        "description": "Charcoal · L",
        "price": {
          "amount": 54,
          "currency": "USD"
        },
        "photo": {
          "url": "https://images.example.test/shop/merino-tee-1.jpg",
          "alt": "Charcoal merino crew-neck tee, folded"
        },
        "categoryId": "tops"
      }
    ],
    "categories": [
      {
        "id": "tops",
        "label": "Tops"
      },
      {
        "id": "bags",
        "label": "Bags & hats"
      },
      {
        "id": "home",
        "label": "Home"
      }
    ]
  }
}

REST

curl https://pagesystems.ai/v1/pages \
  -H "Authorization: Bearer $PAGE_SYSTEMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"spec":{"version":1,"title":"Gift ideas under $100","description":"Six picks for your sister. Tap the one you like.","branding":{"name":"Juniper Market","accentColor":"#2f5d50"},"page":{"type":"product_list","products":[{"id":"linen-shirt-sage-m","name":"Linen camp shirt","description":"Sage · M","price":{"amount":68,"currency":"USD"},"photo":{"url":"https://images.example.test/shop/linen-shirt-sage-1.jpg","alt":"Sage linen camp shirt"},"rating":4.7,"reviewCount":212,"badge":"New","categoryId":"tops"},{"id":"canvas-tote","name":"Canvas market tote","price":{"amount":32,"currency":"USD"},"photo":{"url":"https://images.example.test/shop/canvas-tote-1.jpg","alt":"Natural canvas tote bag with leather handles"},"rating":4.9,"reviewCount":540,"badge":"Bestseller","categoryId":"bags"},{"id":"wool-throw","name":"Waffle wool throw","price":{"amount":96,"currency":"USD"},"compareAtPrice":{"amount":128,"currency":"USD"},"photo":{"url":"https://images.example.test/shop/wool-throw-1.jpg","alt":"Oatmeal waffle-knit wool throw"},"categoryId":"home"},{"id":"stoneware-mug","name":"Speckled stoneware mug","price":{"amount":24,"currency":"USD"},"photo":{"url":"https://images.example.test/shop/stoneware-mug-1.jpg","alt":"Speckled cream stoneware mug"},"rating":4.6,"reviewCount":88,"categoryId":"home"},{"id":"cord-cap","name":"Corduroy cap","price":{"amount":38,"currency":"USD"},"photo":{"url":"https://images.example.test/shop/cord-cap-1.jpg","alt":"Rust corduroy six-panel cap"},"available":false,"categoryId":"bags"},{"id":"merino-tee","name":"Merino crew tee","description":"Charcoal · L","price":{"amount":54,"currency":"USD"},"photo":{"url":"https://images.example.test/shop/merino-tee-1.jpg","alt":"Charcoal merino crew-neck tee, folded"},"categoryId":"tops"}],"categories":[{"id":"tops","label":"Tops"},{"id":"bags","label":"Bags & hats"},{"id":"home","label":"Home"}]}}}'

Validation errors

A spec that does not validate is refused with 400 invalid_spec. The message names each problem and its path, so a model can fix the spec and try again. For example:

Leaving out the required field products:

✖ Invalid input: expected array, received undefined
  → at page.products

Misspelling a field name (unknown keys are rejected):

✖ Unrecognized key: "colour"
  → at page

View this page as markdown