Payments

ListBee uses Stripe to process payments. You connect your Stripe account once — all buyer payments flow to it. ListBee deducts its fee per order.

Connecting Stripe

There are two paths depending on whether you already have a Stripe account.

Path 1: Submit a Stripe key (API-driven)

If you already have a Stripe account with a secret key, submit it directly via the API. This is the agent-friendly path — no browser required.

$
curl -X POST https://api.listbee.so/v1/account/stripe-key \
>
  -H "Authorization: Bearer lb_..." \
>
  -H "Content-Type: application/json" \
>
  -d '{"secret_key": "sk_live_..."}'
$
# → account with readiness.operational: true

ListBee stores the key encrypted and validates it against Stripe before saving. The response is the updated account object with readiness.operational: true.

Path 2: Stripe Connect onboarding (browser-required)

If the user doesn’t have a Stripe account yet, call POST /v1/account/stripe/connect to start a guided onboarding flow. The response contains a URL for the user to open in their browser.

$
curl -X POST https://api.listbee.so/v1/account/stripe/connect \
>
  -H "Authorization: Bearer lb_..."
$
# → { "object": "stripe_connect_session", "url": "https://connect.stripe.com/..." }

After the user completes onboarding, the account’s readiness.operational will be true when you re-fetch it.

Disconnecting Stripe

DELETE /v1/account/stripe removes the Stripe connection from your account. All active listings will become non-sellable immediately.

$
curl -X DELETE https://api.listbee.so/v1/account/stripe \
>
  -H "Authorization: Bearer lb_..."
$
# → { "disconnected": true }

Fee model

ListBee deducts a percentage fee from each order. The fee depends on your plan.

The fee is applied to the full order amount before any currency conversion.

Money flow

Buyer pays $19.00
  → Stripe Checkout (hosted by ListBee, on your Stripe account)
    → Payment lands in your Stripe account
      → ListBee deducts fee via Stripe (e.g. $1.90 on Free plan)
        → You receive $17.10

Money goes directly to your Stripe account. ListBee is never an intermediary for the funds — the fee is deducted at the Stripe level, not transferred through ListBee.

Next steps

• Listings — create your first product now that Stripe is connected.
• Readiness system — understand how payment status affects listing readiness.

Copy for AI assistants

$
# ListBee — payments and Stripe integration
$
#
$
# Stripe connection options:
$
#   Option A (API-driven, no browser):
$
#     POST /v1/account/stripe-key  { "secret_key": "sk_live_..." }
$
#     → account object with readiness.operational: true
$
#
$
#   Option B (browser required, new Stripe account):
$
#     POST /v1/account/stripe/connect
$
#     → { "url": "https://connect.stripe.com/..." }  — open in browser
$
#
$
# Disconnect:
$
#   DELETE /v1/account/stripe  → { "disconnected": true }
$
#   (All listings become non-sellable immediately)
$
#
$
# Fee model:
$
#   Free plan:   10% per order, $0/mo, 50 orders/mo limit
$
#   Growth plan:  5% per order, $29/mo, unlimited
$
#   Scale plan:   3% per order, $79/mo, unlimited
$
#
$
# Money flow:
$
#   buyer → seller's Stripe account → ListBee deducts fee via Stripe
>
#   ListBee never holds funds; fee deducted at Stripe level
>
#
>
# Stripe's own processing fee (2.9% + 30¢) applies separately.
$
#
$
# Auth: Authorization: Bearer lb_...
$
# Errors: RFC 9457 { type, title, status, detail, code, param }