Stores

A store is the brand layer in ListBee. It holds the display name, bio, and avatar that appear on product pages. Each store has exactly one API key — when an agent authenticates, it operates within that store’s scope.

Stores sit between accounts and listings:

Account (human identity + Stripe)
└── Store (brand + API key)
    ├── Listings
    ├── Orders (via listings)
    └── Webhooks

One account can have multiple stores. All stores on an account share the same Stripe connection — the human does KYC once, every store can sell.

How it works

Stores are created through the bootstrap flow. When an agent bootstraps, it provides a store name. The API creates the store, generates an API key, and returns both. The agent uses that key for all subsequent requests.

Everything the agent does is scoped to its store. GET /v1/listings returns only that store’s listings. GET /v1/orders returns only orders from that store’s listings. Agents never see resources from other stores on the same account.

Key fields

Store readiness

Store readiness tells the agent whether listings in this store can accept payment.

1
{
2
  "readiness": {
3
    "sellable": false,
4
    "actions": [
5
      {
6
        "code": "connect_stripe",
7
        "kind": "human",
8
        "priority": "required",
9
        "message": "Connect Stripe to accept payments",
10
        "resolve": { "method": "redirect", "url": "https://console.listbee.so/stripe/connect" }
11
      }
12
    ],
13
    "next": "connect_stripe"
14
  }
15
}

The only store-level gate is Stripe. Once connected, sellable becomes true and listings can take payment immediately after publish.

Store landing page

Every store has a public landing page at buy.listbee.so/{slug}. It shows all published listings with the store’s branding. Useful for sharing a single link or providing a URL during Stripe Connect verification.

Example

1
from listbee import ListBee
2
3
client = ListBee(api_key="lb_...")
4
5
# Get current store
6
store = client.store.get()
7
print(store.display_name)  # "Acme Agency"
8
print(store.url)           # "https://buy.listbee.so/acme-agency"
9
print(store.readiness.sellable)  # True if Stripe connected
10
11
# Update branding
12
client.store.update(
13
    display_name="Acme Digital",
14
    bio="Premium digital products for modern teams",
15
)

Multiple stores

A second agent bootstrapping with the same email creates a new store on the existing account. The second store inherits the Stripe connection — it’s immediately sellable if Stripe was already connected.

Each store has its own API key, listings, webhooks, and slug. Stores are independent brands under one billing account.

Related

• Authentication — how to create a store via bootstrap
• Readiness — how readiness works at store and listing levels
• Listings — creating and managing listings within a store