Quickstart

Step 1: Create an account

No console signup needed. The agent bootstraps directly via the API. See Authentication for the full flow.

1
from listbee import ListBee
2
3
bootstrapping = ListBee()
4
api_key = bootstrapping.bootstrap.run(
5
    "seller@example.com",
6
    on_otp=lambda: input("Enter OTP from email: "),
7
    on_human_action=lambda url: print(f"Complete Stripe: {url}"),
8
)
9
10
client = ListBee(api_key=api_key)

Save the api_key — it’s shown once. Use it as Authorization: Bearer lb_... on every subsequent request.

Step 2: Create and publish a listing

A listing is a sellable item with a hosted product page. Required: name and price (in cents).

Pick a fulfillment mode:

• static — bake the deliverable into the listing. ListBee delivers it automatically at payment.
• async — leave the deliverable empty. Your agent generates and pushes it after each order via /fulfill.

1
from listbee import Deliverable
2
3
created = client.listings.create(
4
    name="SEO Playbook 2026",
5
    price=1900,                             # $19.00
6
    fulfillment_mode="static",
7
    deliverable=Deliverable.url("https://example.com/seo-playbook.pdf"),
8
)
9
10
listing = created.listing
11
signing_secret = created.signing_secret     # store this — webhook verification
12
13
client.listings.publish(listing_id=listing.id)
14
print(listing.url)                          # share with buyers

signing_secret is the HMAC key for webhook payloads on this listing. It’s returned once at creation — store it now. See Fulfillment for webhook signing.

Step 3: Handle orders

When a buyer pays, ListBee creates an order (status: paid) and fires order.paid. For static listings, ListBee also delivers the pre-baked deliverable, transitions the order to fulfilled, and fires order.fulfilled.

For async listings, your agent generates content after payment and pushes it back:

1
from listbee import Deliverable
2
3
# In your order.paid handler:
4
client.orders.fulfill(
5
    order_id="ord_9xM4kP7nR2qT5wY1",
6
    deliverable=Deliverable.text("Your personalized report: ..."),
7
)

ListBee emails the buyer a permanent unlock_url and transitions the order to fulfilled.

Step 4: Receive webhooks

Pass agent_callback_url on the listing to have ListBee POST events to your server. Events are signed with the listing’s signing_secret (HMAC-SHA256).

1
client.listings.update(
2
    listing_id=listing.id,
3
    agent_callback_url="https://your-agent.example.com/hooks/listbee",
4
)

No URL? You can still poll GET /v1/orders or GET /v1/events for a reconciliation pass. See Events and Fulfillment.

Next steps

• Listings — fulfillment modes, metadata, checkout schema
• Orders — lifecycle, unlock URLs, redelivery
• Fulfillment — webhook signing, retry schedule
• Readiness — what’s blocking an account or listing