Checkout schema

The checkout_schema field on a listing defines custom fields shown to the buyer on the product page before payment. Buyer responses are stored on the order as checkout_data.

Email is always collected — you don’t need to add it to the schema.

Adding fields

Pass checkout_schema when creating or updating a listing. Each field has a key, type, label, and required flag.

1 import httpx
2 
3 resp = httpx.post(
4     "https://api.listbee.so/v1/listings",
5     headers={"Authorization": "Bearer lb_..."},
6     json={
7         "name": "Custom Portrait Drawing",
8         "price": 4900,
9         "fulfillment": "external",
10         "checkout_schema": [
11             {
12                 "key": "style",
13                 "type": "select",
14                 "label": "Art style",
15                 "required": True,
16                 "options": ["Watercolor", "Pencil sketch", "Digital art"],
17             },
18             {
19                 "key": "description",
20                 "type": "text",
21                 "label": "Describe what you want drawn",
22                 "required": True,
23             },
24             {
25                 "key": "deadline",
26                 "type": "date",
27                 "label": "Need it by (optional)",
28                 "required": False,
29             },
30         ],
31     },
32 )
33 listing = resp.json()

Field types

Type	Rendered as	Value in `checkout_data`	Notes
`text`	Text input	`string`	General purpose. Free-form text.
`select`	Dropdown	`string`	Requires `options` array.
`date`	Date picker	`string` (ISO 8601 date)	`"2026-04-15"` format.
`address`	Address form (line1, line2, city, state, postal_code, country)	Stored in `order.shipping_address`	Parsed into a structured `ShippingAddress` object, not stored in `checkout_data`.

Address fields

The address type is special. It renders a full address form and stores the result as a structured ShippingAddress object on the order — not in checkout_data.

1 import httpx
2 
3 resp = httpx.post(
4     "https://api.listbee.so/v1/listings",
5     headers={"Authorization": "Bearer lb_..."},
6     json={
7         "name": "Handmade Leather Boots",
8         "price": 18900,
9         "fulfillment": "external",
10         "checkout_schema": [
11             {
12                 "key": "shipping_address",
13                 "type": "address",
14                 "label": "Shipping address",
15                 "required": True,
16             },
17         ],
18     },
19 )

The order response after payment:

1 {
2   "object": "order",
3   "id": "ord_abc123",
4   "checkout_data": {},
5   "shipping_address": {
6     "line1": "123 Main St",
7     "line2": "Apt 4B",
8     "city": "Portland",
9     "state": "OR",
10     "postal_code": "97201",
11     "country": "US"
12   }
13 }

Reading checkout data

After payment, checkout_data is a dictionary keyed by the field key values you defined. Address fields are in shipping_address instead.

1 import httpx
2 
3 resp = httpx.get(
4     "https://api.listbee.so/v1/orders/ord_abc123",
5     headers={"Authorization": "Bearer lb_..."},
6 )
7 order = resp.json()
8 
9 # Custom fields
10 print(order["checkout_data"]["style"])        # Watercolor
11 print(order["checkout_data"]["description"])  # A portrait of my cat
12 
13 # Address (separate field)
14 addr = order["shipping_address"]
15 if addr:
16     print(f"{addr['line1']}, {addr['city']}, {addr['state']} {addr['postal_code']}")

Limits

Maximum 10 fields per listing.
key must be unique within the schema.
options is required for select type, ignored for others.
address type: maximum 1 per schema.

Updating the schema

Update checkout_schema on an existing listing. The new schema replaces the old one entirely.

1 import httpx
2 
3 resp = httpx.put(
4     "https://api.listbee.so/v1/listings/r7kq2xy9",
5     headers={"Authorization": "Bearer lb_..."},
6     json={
7         "checkout_schema": [
8             {"key": "size", "type": "select", "label": "Size", "required": True, "options": ["S", "M", "L", "XL"]},
9         ],
10     },
11 )

To remove all custom fields, set checkout_schema to null.

Next steps

Selling physical products — address collection with external fulfillment.
Dynamic fulfillment — use checkout data to generate content.
Fulfillment modes — managed vs external.

Copy for AI assistants

Cursor / Claude Code

1 # ListBee — checkout schema
2 #
3 # Add custom fields to the checkout page via checkout_schema on a listing.
4 # Max 10 fields. Email is always collected (don't add it).
5 #
6 # Field types:
7 #   text    → free-form text input     → checkout_data[key]: string
8 #   select  → dropdown (requires options) → checkout_data[key]: string
9 #   date    → date picker              → checkout_data[key]: "YYYY-MM-DD"
10 #   address → full address form        → order.shipping_address: { line1, line2, city, state, postal_code, country }
11 #
12 # Create with schema:
13 #   POST /v1/listings {
14 #     name, price, fulfillment: "external",
15 #     checkout_schema: [
16 #       { key: "size", type: "select", label: "Size", required: true, options: ["S","M","L"] },
17 #       { key: "shipping_address", type: "address", label: "Address", required: true }
18 #     ]
19 #   }
20 #
21 # Read checkout data from order:
22 #   GET /v1/orders/{id}
23 #   → order.checkout_data = { size: "M" }
24 #   → order.shipping_address = { line1, line2, city, state, postal_code, country }
25 #
26 # Address fields go to shipping_address, not checkout_data.
27 # Max 1 address field per schema.
28 #
29 # Auth: Authorization: Bearer lb_...
30 # Docs: https://docs.listbee.so/checkout-schema