Entity model

ListBee has five core entities. This page shows how they relate and where to find detailed documentation for each one.

Hierarchy

Account
├── Listing
│   ├── Order
│   │   └── Access Grant
│   ├── Deliverable (file / url / text / none)
│   └── Checkout Schema (text / select fields)
├── Webhook
└── API Key

An account owns everything and carries your seller profile — display name, bio, avatar, and social links. Listings are the products you sell — each has a fulfillment mode (managed or external) and an optional deliverable (the digital content ListBee can deliver). When a buyer pays, an order is created. For managed fulfillment, an access grant delivers the content. Webhooks notify you of events. API keys authenticate your requests.

Entities

Listing fields

Order fields

Relationships

• An account has many listings, webhooks, and API keys.
• A listing belongs to one account.
• A listing has many orders. Each order belongs to exactly one listing.
• An order has one access grant (created automatically on payment for managed fulfillment).
• A listing has one optional deliverable (file, URL, or text). Deliverables are mutable while the listing is in draft.
• A listing has an optional checkout schema (custom fields collected at checkout).
• Webhooks receive events for all resources under the account — there is no per-listing webhook scoping.

ID format

All IDs follow the pattern {prefix}_{random}. The prefix tells you the entity type at a glance:

acc_r7kq2xy9m3pR5tW1   → Account
lst_r7kq2xy9m3pR5tW1   → Listing
ord_r7kq2xy9m3pR5tW1   → Order
ag_r7kq2xy9m3pR5tW1    → Access Grant
wh_r7kq2xy9m3pR5tW1    → Webhook
lbk_r7kq2xy9m3pR5tW1   → API Key (entity)
lb_r7kq2xy9m3pR5tW1    → API Key (value — used in Authorization header)
evt_r7kq2xy9m3pR5tW1   → Event

Next steps

• Account — manage your seller profile and Stripe connection.
• Listings — create and manage your first product.
• Listing lifecycle — draft, published, and paused states.
• Fulfillment modes — managed vs external delivery.
• Readiness system — understand when a listing is ready to sell.

Copy for AI assistants

$
# ListBee — entity model
$
#
$
# Hierarchy: Account → Listing → Order → Access Grant
$
#                        ├→ Deliverable (file/url/text/null)
$
#                        └→ Checkout Schema (text/select)
$
#            Account → Webhook, API Key
$
#
$
# Account carries profile: display_name, bio, avatar_key, social_links
$
#
$
# ID prefixes:
$
#   acc_  account
$
#   lst_  listing (looked up by slug, not ID)
$
#   ord_  order
$
#   ag_   access grant (internal, not in API responses)
$
#   wh_   webhook
$
#   lbk_  API key entity
$
#   lb_   API key value (used in Authorization: Bearer lb_...)
$
#   evt_  event (webhook payload)
$
#
$
# Listing key fields:
$
#   status: "draft" | "published" | "paused"
$
#   fulfillment: "managed" | "external"  (computed from deliverable presence)
$
#   deliverable_type: "file" | "url" | "text" | null
$
#   checkout_schema: [{ key, type, label, required, options? }] | null
$
#
$
# Order key fields:
$
#   status: pending | paid | fulfilled | canceled | failed
$
#   checkout_data: { key: value } | null
$
#   fulfillment_status: pending | shipped | fulfilled | null
$
#   carrier, tracking_code, seller_note: string | null
$
#   paid_at, fulfilled_at: datetime | null
$
#
$
# Docs: https://docs.listbee.so/entity-model