Orders & Delivery

An order is created when a buyer visits a product page. It starts as pending (checkout opened), transitions to paid on payment, and reaches fulfilled when delivery is complete.

Order lifecycle

Orders move through five states:

PENDING → PAID → FULFILLED
              ↘ CANCELED
              ↘ FAILED

Managed fulfillment

PENDING → PAID → FULFILLED happens automatically. ListBee creates an access grant and delivers the content on payment confirmation. Both order.paid and order.fulfilled webhooks fire.

External fulfillment

PENDING → PAID happens automatically. Your app receives the order.paid webhook and handles delivery. Call POST /v1/orders/{id}/deliver when done — this transitions the order to FULFILLED and fires order.fulfilled.

For physical goods, call POST /v1/orders/{id}/ship first to record tracking info, then deliver when complete.

Fulfillment tracking

External orders have a fulfillment_status field that tracks delivery progress:

Managed orders skip straight to fulfilled — there’s no intermediate state.

Deliver an order

POST /v1/orders/{id}/deliver marks an external order as fulfilled. Optionally push generated content for ListBee to deliver to the buyer.

$
# Deliver without content (external fulfillment you handle yourself)
$
curl -X POST https://api.listbee.so/v1/orders/ord_.../deliver \
>
  -H "Authorization: Bearer lb_..." \
>
  -H "Content-Type: application/json" \
>
  -d '{}'
$
$
# Deliver text content inline
$
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 delivery content"}'
$
$
# Deliver a URL redirect
$
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://yourapp.com/delivery/abc123"}'
$
$
# Deliver a file (upload first, then deliver with token)
$
curl -X POST https://api.listbee.so/v1/files \
>
  -H "Authorization: Bearer lb_..." \
>
  -F "file=@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_..."}'

Ship an order

POST /v1/orders/{id}/ship records shipping information on a paid order. Use this for physical goods before marking the order as fulfilled.

$
curl -X POST https://api.listbee.so/v1/orders/ord_.../ship \
>
  -H "Authorization: Bearer lb_..." \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "carrier": "FedEx",
>
    "tracking_code": "794644790138",
>
    "seller_note": "Ships from Portland. Estimated 3-5 business days."
>
  }'

This fires an order.shipped webhook event.

List orders

GET /v1/orders returns orders in reverse chronological order with cursor-based pagination.

$
curl "https://api.listbee.so/v1/orders?limit=20" \
>
  -H "Authorization: Bearer lb_..."

Paginate with the cursor from the previous response:

$
curl "https://api.listbee.so/v1/orders?limit=20&cursor=ord_..." \
>
  -H "Authorization: Bearer lb_..."

Get an order

GET /v1/orders/{id} returns a single order.

$
curl https://api.listbee.so/v1/orders/ord_... \
>
  -H "Authorization: Bearer lb_..."

Filter orders

Key fields

Next steps

• Fulfillment modes — managed vs external, when to use each.
• Webhooks — get notified on order.paid, order.shipped, order.fulfilled.
• Checkout schema — collect custom data from buyers.

Copy for AI assistants

$
# ListBee — orders API
$
#
$
# Order lifecycle:
$
#   PENDING -> PAID -> FULFILLED (managed: automatic, external: via API)
$
#   PENDING -> CANCELED | FAILED (terminal)
$
#
$
# Managed fulfillment: PAID -> FULFILLED automatic (access grant + email)
$
# External fulfillment: PAID -> your app delivers -> call /deliver -> FULFILLED
$
#
$
# Deliver an order:
$
#   POST /v1/orders/{id}/deliver  {}
$
#     or with content: { "type": "text"|"url"|"file", "value": "..."|"token": "file_..." }
$
#   Response: order object with status: "fulfilled", fires order.fulfilled webhook
$
#
$
# Ship an order (physical goods):
$
#   POST /v1/orders/{id}/ship  { "carrier": "FedEx", "tracking_code": "...", "seller_note"? }
$
#   Response: order with fulfillment_status: "shipped", fires order.shipped webhook
$
#
$
# List orders (cursor pagination):
$
#   GET /v1/orders?limit=20&cursor=ord_...&status=paid&listing_slug=my-listing
$
#   Response: { "object": "list", "data": [...], "has_more": bool, "cursor": str | null }
$
#
$
# Get order:
$
#   GET /v1/orders/{id}
$
#   Response: { object, id, status, amount, currency, listing_id, listing_slug,
>
#     buyer_email, checkout_data, shipping_address, fulfillment_status,
>
#     carrier, tracking_code, seller_note, paid_at, fulfilled_at }
$
#
$
# Auth: Authorization: Bearer lb_...
$
# Errors: RFC 9457 { type, title, status, detail, code, param }