Fulfillment modes

Every listing has a fulfillment field: "managed" or "external". This is computed from whether a deliverable is attached — you don’t set it directly.

Managed fulfillment

ListBee delivers the product automatically. You attach a deliverable (file, URL, or text) to the listing. After payment, ListBee creates an access grant and delivers it to the buyer by email.

Best for: digital downloads, redirect links, license keys, text content.

$ curl -X POST https://api.listbee.so/v1/listings \
>   -H "Authorization: Bearer lb_..." \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "Python Async Patterns",
>     "price": 1900
>   }'
$ # Create draft, then attach deliverable:
$ curl -X PUT https://api.listbee.so/v1/listings/lst_.../deliverable \
>   -H "Authorization: Bearer lb_..." \
>   -H "Content-Type: application/json" \
>   -d '{"type": "url", "value": "https://your-bucket.s3.amazonaws.com/python-async.pdf"}'
$ # → fulfillment: "managed"

What ListBee handles in managed mode

Step	ListBee does it
Collect payment	Yes (Stripe Checkout)
Create access grant	Yes
Deliver to buyer	Yes (email with download link / redirect / inline text)
Fire `order.paid` webhook	Yes
Fire `order.fulfilled` webhook	Yes

External fulfillment

Your app handles delivery. ListBee collects payment, fires an order.paid webhook, and your code takes over. No deliverable needed on the listing.

Best for: physical goods, AI-generated content, custom services, anything that requires logic after payment.

$ curl -X POST https://api.listbee.so/v1/listings \
>   -H "Authorization: Bearer lb_..." \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "Custom Portrait Drawing",
>     "price": 4900
>   }'
$ # No deliverable = external fulfillment
$ # → fulfillment: "external"

What you handle in external mode

Step	Who
Collect payment	ListBee (Stripe Checkout)
Receive `order.paid` webhook	Your app
Deliver product to buyer	Your app
Call `POST /v1/orders/{id}/fulfill` (optional)	Your app
Fire `order.fulfilled` webhook	ListBee (after you call fulfill)

External fulfillment requires a registered webhook. If no webhook is configured, the readiness system shows a configure_webhook action — the listing cannot sell until a webhook endpoint is set up to receive order.paid events.

Decision tree

Do you have a file, URL, or text to deliver automatically?
  → Yes: use managed fulfillment (attach a deliverable)
  → No: use external fulfillment (leave no deliverable)
Is delivery handled by your own code or a third party?
  → Yes: use external fulfillment
  → No: use managed fulfillment
Does the product require information from the buyer (address, size, preferences)?
  → Yes: use external fulfillment + checkout_schema
  → No: managed or external — your choice

Responsibility matrix

Responsibility	Managed	External
Payment collection	ListBee	ListBee
Buyer email collection	ListBee	ListBee
Custom checkout fields	Optional (checkout_schema)	Optional (checkout_schema)
Digital content delivery	ListBee	Your app
Physical goods shipping	N/A	Your app
Order status transitions	Automatic (PENDING → PAID → FULFILLED)	PENDING → PAID automatic, PAID → FULFILLED via API
Webhook: `order.paid`	Fired	Fired
Webhook: `order.fulfilled`	Fired (immediately after paid)	Fired (after you call fulfill or ship)

Defaults

Fulfillment mode is computed from deliverable presence — you cannot set it directly.

Deliverable attached?	`fulfillment`
Yes (file/url/text)	`"managed"`
No	`"external"`

To switch modes: attach a deliverable (switches to managed) or remove it (switches to external).

Next steps

Deliverables — file, URL, and text content types for managed fulfillment.
Checkout schema — collect custom fields from buyers at checkout.
Dynamic fulfillment — generate content after payment with the fulfill callback.
Selling physical products — external fulfillment with address collection.

Copy for AI assistants

$ # ListBee — fulfillment modes
$ #
$ # Every listing has fulfillment: "managed" | "external"
$ # This is COMPUTED from deliverable presence — not set directly.
$ #
$ # MANAGED (deliverable attached):
$ #   ListBee delivers automatically — file download, URL redirect, or inline text.
$ #   Order flow: PENDING → PAID → FULFILLED (all automatic)
$ #   Events: order.paid + order.fulfilled both fire
$ #
$ # EXTERNAL (no deliverable):
$ #   ListBee collects payment, fires order.paid webhook, your app delivers.
$ #   Order flow: PENDING → PAID (automatic) → FULFILLED (via POST /v1/orders/{id}/fulfill)
$ #   Requires: registered webhook endpoint
$ #   Events: order.paid fires on payment, order.fulfilled fires after you call fulfill
$ #
$ # Create managed listing:
$ #   POST /v1/listings { name, price }
$ #   PUT /v1/listings/{id}/deliverable { type: "url", value: "https://..." }
$ #   → fulfillment: "managed"
$ #
$ # Create external listing:
$ #   POST /v1/listings { name, price }
$ #   (no deliverable attached)
$ #   → fulfillment: "external"
$ #
$ # Fulfill an external order:
$ #   POST /v1/orders/{id}/fulfill  { content?, content_type?, content_url? }
$ #
$ # Ship a physical order:
$ #   POST /v1/orders/{id}/ship  { carrier, tracking_code, seller_note? }
$ #
$ # Auth: Authorization: Bearer lb_...
$ # Docs: https://docs.listbee.so/fulfillment-modes