API ReferenceOrders

Refund order

Issue a full refund for an order. The refund is processed through Stripe on the seller’s connected account. Only orders with status paid or fulfilled can be refunded. If the order is already refunded, returns the order as-is (idempotent). The order’s refund_amount and refunded_at update asynchronously via Stripe webhook.

Authentication

AuthorizationBearer

API key (lb_ prefix). Pass as: Authorization: Bearer lb_...

Path parameters

order_idstringRequired
Order ID.

Response

Successful Response
idstring
Unique identifier
listing_idstring
ID of the purchased listing
buyer_emailstring
Buyer's email address collected at Stripe Checkout. Use for customer communication.
amountinteger

Amount paid in cents (smallest currency unit). $29.00 = 2900.

currencystring

Three-letter ISO currency code, uppercase

statusenum
Current order status. Full lifecycle: PENDING (checkout started) → PAID (payment confirmed) → PROCESSING (generated listings only: agent generating content) → FULFILLED (content delivered or order closed). Terminal error states: CANCELED (payment failed/abandoned), FAILED (system error). Use content_type to determine which statuses apply: static skips PROCESSING and auto-fulfills; generated enters PROCESSING until POST /fulfill is called; webhook stays PAID — delivery handled externally.
content_typestring

Content type of the listing at the time of purchase. Determines the delivery model: static = ListBee auto-delivered pre-attached content on payment; generated = your system creates content after payment and pushes it via POST /fulfill; webhook = order.paid fired, your system handles delivery entirely. Use this to branch post-payment logic without re-fetching the listing.

payment_statusstring

Stripe payment status, independent of order fulfillment status. Values: unpaid (payment not yet confirmed), paid (payment captured), refunded (full refund issued). An order can be fulfilled while payment_status is still paid — refund happens separately.

stripe_payment_intent_idstring

Stripe PaymentIntent ID. Use for cross-referencing with Stripe dashboard or API.

created_atdatetime
Time at which the order was created
object"order"

Object type identifier. Always order.

checkout_datamap from strings to any or null

Custom checkout field values submitted by the buyer. Keys match the listing’s checkout_schema.

listing_snapshotmap from strings to any or null

Immutable snapshot of listing data captured at payment time. Contains name, price, slug, and other listing fields as they existed when the buyer paid. Use this as the authoritative record of what was purchased — the listing may have changed since.

seller_snapshotmap from strings to any or null

Immutable snapshot of seller identity captured at payment time. Contains display_name and other account fields as they existed when the buyer paid. Useful for receipts and audit trails when account details change later.

handed_off_atdatetime or null

Timestamp when the order was handed off to the seller’s external system via order.paid webhook. Only set for webhook content_type listings. Null for static and generated listings.

deliverableslist of objects

Deliverables attached to this order. For static listings: auto-populated from the listing’s deliverables when payment is confirmed. For generated listings: populated when your system calls POST /fulfill with the generated content. For webhook listings: always empty — your system delivers content outside ListBee.

platform_feeintegerDefaults to 0

Platform fee in cents deducted from this order. Amount seller receives = amount - platform_fee.

refund_amountintegerDefaults to 0
Amount refunded to buyer in cents. 0 if not refunded.
refunded_atdatetime or null
When the refund was processed. null if not refunded.
dispute_statusstring or null

Stripe dispute status if disputed. Values: needs_response, under_review, won, lost.

dispute_reasonstring or null
Reason for the dispute as reported by the buyer's bank.
dispute_amountintegerDefaults to 0
Disputed amount in cents. 0 if not disputed.
disputed_atdatetime or null
When the dispute was opened. null if not disputed.
paid_atdatetime or null
When payment was confirmed
fulfilled_atdatetime or null
When order was fulfilled

Errors

401
Unauthorized Error
404
Not Found Error
422
Unprocessable Entity Error