Dynamic fulfillment

Dynamic fulfillment bridges external and managed delivery. Your app receives the order.paid webhook, generates content (AI output, custom report, personalized file), then calls POST /v1/orders/{id}/deliver to push it back to ListBee. ListBee delivers the generated content to the buyer — same secure access page, same delivery email — as if you had attached the content to the listing from the start.

How it works

Buyer pays on product page
        ↓
ListBee fires order.paid webhook (includes checkout_data)
        ↓
Your agent generates content using checkout_data as input
        ↓
Agent calls POST /v1/orders/{id}/deliver with type + content
        ↓
ListBee stores content + creates access grant
        ↓
Buyer receives delivery email with secure access link
        ↓
ListBee fires order.fulfilled webhook

The buyer gets the same delivery experience as managed fulfillment — email with download link, redirect, or inline text — but the content was generated on-demand by your code.

Setup

Create a listing with fulfillment: "external" and a checkout_schema to collect buyer inputs. These inputs arrive in checkout_data on the order.paid webhook, ready for your generation logic.

$
curl -X POST https://api.listbee.so/v1/listings \
>
  -H "Authorization: Bearer lb_..." \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "name": "Personal Horoscope Reading",
>
    "price": 500,
>
    "fulfillment": "external",
>
    "checkout_schema": [
>
      {
>
        "key": "birth_date",
>
        "type": "date",
>
        "label": "Your birth date",
>
        "required": true
>
      },
>
      {
>
        "key": "zodiac_focus",
>
        "type": "select",
>
        "label": "Reading focus",
>
        "required": false,
>
        "options": ["Career", "Love", "Health", "General"]
>
      }
>
    ]
>
  }'

Walkthrough: AI horoscope agent

An AI agent sells personalized horoscopes. The buyer provides their birth date at checkout. After payment, the agent generates a horoscope and pushes it to ListBee for delivery.

Step 1: Handle the webhook and generate content

Your server receives the order.paid webhook. Verify the signature, extract checkout_data, run your generation logic, then call the deliver endpoint. The full order snapshot is in the webhook payload — no follow-up API call required.

1
import hashlib
2
import hmac
3
from fastapi import Request, HTTPException
4
import httpx
5
6
WEBHOOK_SECRET = "whsec_..."
7
API_KEY = "lb_prod_..."
8
9
async def handle_webhook(request: Request):
10
    payload = await request.body()
11
    signature = request.headers.get("X-ListBee-Signature", "")
12
13
    expected = hmac.new(WEBHOOK_SECRET.encode(), payload, hashlib.sha256).hexdigest()
14
    if not hmac.compare_digest(expected, signature):
15
        raise HTTPException(status_code=400, detail="Invalid signature")
16
17
    event = await request.json()
18
19
    if event["type"] == "order.paid":
20
        data = event["data"]
21
22
        # Everything needed is in the webhook — no API call required
23
        horoscope = generate_horoscope(
24
            birth_date=data["checkout_data"]["birth_date"],
25
            focus=data["checkout_data"].get("zodiac_focus", "General"),
26
        )
27
28
        # Push generated content to ListBee for delivery
29
        httpx.post(
30
            f"https://api.listbee.so/v1/orders/{data['order_id']}/deliver",
31
            headers={"Authorization": f"Bearer {API_KEY}"},
32
            json={"type": "text", "value": horoscope},
33
        )
34
35
    return {"ok": True}
36
37
def generate_horoscope(birth_date: str, focus: str = "General") -> str:
38
    # Your AI generation logic
39
    return f"Your personalized {focus.lower()} horoscope for {birth_date}..."

Step 2: Buyer receives the content

After your deliver call, ListBee creates an access grant and delivers the generated content to the buyer by email. The buyer clicks the link and sees the content on a secure access page — the same experience as a static digital product.

The deliver endpoint

POST /v1/orders/{id}/deliver accepts a type field and either a token (for uploaded files) or value (for URLs and text). You explicitly specify the content type — there is no auto-detection.

$
# Deliver a file (upload first, then deliver with token)
$
curl -X POST https://api.listbee.so/v1/files \
>
  -H "Authorization: Bearer lb_..." \
>
  -F "file=@generated-report.pdf"
$
# Response: { "id": "file_..." }
$
$
curl -X POST https://api.listbee.so/v1/orders/ord_.../deliver \
>
  -H "Authorization: Bearer lb_..." \
>
  -H "Content-Type: application/json" \
>
  -d '{"type": "file", "token": "file_..."}'
$
$
# Deliver a URL
$
curl -X POST https://api.listbee.so/v1/orders/ord_.../deliver \
>
  -H "Authorization: Bearer lb_..." \
>
  -H "Content-Type: application/json" \
>
  -d '{"type": "url", "value": "https://generated-content.example.com/report"}'
$
$
# Deliver text
$
curl -X POST https://api.listbee.so/v1/orders/ord_.../deliver \
>
  -H "Authorization: Bearer lb_..." \
>
  -H "Content-Type: application/json" \
>
  -d '{"type": "text", "value": "Your generated content here..."}'

Use cases

Next steps

• Fulfillment modes — understand managed vs external.
• Checkout schema — all field types you can collect at checkout.
• Webhooks — handle order.paid and order.fulfilled events.

Copy for AI assistants

$
# ListBee — dynamic fulfillment (AI-generated content)
$
#
$
# Pattern: external fulfillment + deliver callback
$
#
$
# 1. Create listing:
$
#    POST /v1/listings {
>
#      name, price, fulfillment: "external",
>
#      checkout_schema: [{ key, type, label, required, options? }]
>
#    }
$
#
$
# 2. Receive order.paid webhook — checkout_data contains buyer inputs:
$
#    event.data.checkout_data = { birth_date: "1990-05-15", ... }
$
#    event.data.buyer_email = "buyer@example.com"
$
#    (full snapshot in webhook — no follow-up API call needed)
$
#
$
# 3. Generate content (your AI / generation logic)
$
#
$
# 4. Push to ListBee — explicitly specify type:
$
#    POST /v1/orders/{id}/deliver { "type": "text", "value": "..." }
$
#    POST /v1/orders/{id}/deliver { "type": "url", "value": "https://..." }
$
#    POST /v1/orders/{id}/deliver { "type": "file", "token": "file_..." }
$
#      (upload file first: POST /v1/files with multipart form)
$
#    Response: order object with status: "fulfilled"
$
#    ListBee creates access grant, delivers to buyer by email
$
#    Fires order.fulfilled webhook
$
#
$
# Auth: Authorization: Bearer lb_...
$
# Docs: https://docs.listbee.so/dynamic-fulfillment