{"openapi":"3.1.0","info":{"title":"ListBee","summary":"One API call to sell and deliver digital content.","description":"ListBee is a commerce API for AI agents, n8n workflows, and automation platforms. Create a listing with a title, price, and content — get back a checkout URL. Buyers visit the URL, pay via Stripe, and receive the content automatically.\n\n## Quick Start\n1. Sign up at [console.listbee.so](https://console.listbee.so) — creates your account and first API key\n2. `POST /v1/listings` with title + price + content — use `Authorization: Bearer lb_...`\n3. Share the checkout URL with buyers\n\n## Authentication\nAll API requests require an API key (`lb_` prefix) passed as: `Authorization: Bearer lb_...`\n\nCreate and manage API keys in the [developer console](https://console.listbee.so).","version":"1.0.0"},"servers":[{"url":"https://api.listbee.so","description":"API server"}],"paths":{"/v1/account":{"get":{"tags":["Account"],"summary":"Get account","description":"Account status and readiness. Check readiness.operational — if false, readiness.actions lists what's needed. readiness.next is the highest-priority action.","operationId":"get_account","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountResponse"}}}},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}},"security":[{"HTTPBearer":[]}]},"put":{"tags":["Account"],"summary":"Update account","description":"Update account settings: ga_measurement_id (Google Analytics tracking on checkout pages) and notify_orders (email notifications for new orders). Returns the updated account with readiness — check readiness.operational to verify the account can accept payments.","operationId":"update_account","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAccountRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountResponse"}}}},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}},"security":[{"HTTPBearer":[]}]},"delete":{"tags":["Account"],"summary":"Delete account","description":"Permanently delete the authenticated account. PII is anonymized, API keys revoked, webhooks disabled. Order history is retained for accounting. This action is irreversible.","operationId":"delete_account","responses":{"204":{"description":"Successful Response"},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}},"security":[{"HTTPBearer":[]}]}},"/v1/customers":{"get":{"tags":["Customers"],"summary":"List customers","description":"List customers (buyers) for the authenticated account. Customers are auto-created when a buyer completes their first order. Use this endpoint to get buyer email addresses for marketing, analyze purchasing patterns, or identify repeat customers. Sorted by most recent purchase first.","operationId":"list_customers","security":[{"HTTPBearer":[]}],"parameters":[{"name":"email","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by exact buyer email address.","examples":["alice@example.com"],"title":"Email"},"description":"Filter by exact buyer email address."},{"name":"created_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only customers created after this ISO 8601 datetime.","examples":["2026-03-01T00:00:00Z"],"title":"Created After"},"description":"Only customers created after this ISO 8601 datetime."},{"name":"created_before","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only customers created before this ISO 8601 datetime.","examples":["2026-03-31T23:59:59Z"],"title":"Created Before"},"description":"Only customers created before this ISO 8601 datetime."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pagination cursor from a previous response.","title":"Cursor"},"description":"Pagination cursor from a previous response."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of customers to return.","examples":[20],"default":20,"title":"Limit"},"description":"Maximum number of customers to return."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerListResponse"}}}},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/customers/{customer_id}":{"get":{"tags":["Customers"],"summary":"Get customer","description":"Get a single customer by ID. Customers are auto-created from order data — they represent unique buyer email addresses that have purchased from the seller. Use the customer's email to filter orders via GET /v1/orders?buyer_email=... for purchase history.","operationId":"get_customer","security":[{"HTTPBearer":[]}],"parameters":[{"name":"customer_id","in":"path","required":true,"schema":{"type":"string","description":"Customer ID.","examples":["cus_7kQ2xY9mN3pR5tW1vB8a01"],"title":"Customer Id"},"description":"Customer ID."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerResponse"}}}},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Customer not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/files":{"post":{"tags":["Files"],"summary":"Upload file","description":"Upload a file and receive a token valid for 24 hours. Use the token in PUT /v1/listings/{id}/deliverables (as a file deliverable), or as 'cover' when creating/updating a listing, or 'avatar' when updating a store. Typical flow: upload_file → set_deliverables → publish_listing.\n\n**Per-purpose limits:**\n- `deliverable` — up to 25 MB; PDF, EPUB, ZIP, images, audio, video, Office documents.\n- `cover` — up to 5 MB; JPEG, PNG, WebP, or GIF.\n- `avatar` — up to 2 MB; JPEG, PNG, WebP, or GIF.\n\nMIME type is verified against magic bytes. Mismatches are rejected.","operationId":"upload_file","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/Body_upload_file"}}},"required":true},"responses":{"201":{"description":"File uploaded. Token valid for 24 hours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileResponse"}}}},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"413":{"description":"File exceeds the size limit for the given purpose.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Unsupported file type, invalid purpose, or missing file.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}},"security":[{"HTTPBearer":[]}]}},"/v1/listings":{"post":{"tags":["Listings"],"summary":"Create listing","description":"Create a listing to sell digital content. Returns product page URL and readiness. If readiness.sellable is false, follow readiness.actions to resolve. readiness.next is the first action to take. When your account uses a Stripe test key, checkout URLs point to Stripe test mode.","operationId":"create_listing","security":[{"HTTPBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateListingRequest"}}}},"responses":{"201":{"description":"Listing created and published.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingResponse"}}}},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Validation error (code: `validation_error`). Check `detail` for specifics: price must be positive, slug already exists, deliverable URL unreachable or unsupported format.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded. Retry after the `Retry-After` header value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}},"get":{"tags":["Listings"],"summary":"List listings","description":"List all listings for the authenticated account. Filter by status. Cursor-paginated. Returns lightweight summaries — use GET /v1/listings/{listing_id} for full detail including deliverables, readiness, reviews, and checkout schema.","operationId":"list_listings","security":[{"HTTPBearer":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/ListingStatus"},{"type":"null"}],"description":"Filter by listing status.","examples":["active"],"title":"Status"},"description":"Filter by listing status."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pagination cursor from a previous response.","title":"Cursor"},"description":"Pagination cursor from a previous response."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of listings to return.","examples":[20],"default":20,"title":"Limit"},"description":"Maximum number of listings to return."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingListResponse"}}}},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/listings/{listing_id}":{"get":{"tags":["Listings"],"summary":"Get listing","description":"Get a single listing by ID. Check readiness.sellable — if false, readiness.actions tells you what's needed.","operationId":"get_listing","security":[{"HTTPBearer":[]}],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","description":"Listing ID (lst_ prefixed).","examples":["lst_abc123"],"title":"Listing Id"},"description":"Listing ID (lst_ prefixed)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingResponse"}}}},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Listing not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"put":{"tags":["Listings"],"summary":"Update listing","description":"Update listing fields. Slug can be changed while in draft status — input is slugified, conflicts get a random suffix. Returns updated listing with readiness.","operationId":"update_listing","security":[{"HTTPBearer":[]}],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","description":"Listing ID (lst_ prefixed).","examples":["lst_abc123"],"title":"Listing Id"},"description":"Listing ID (lst_ prefixed)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateListingRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingResponse"}}}},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Listing not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}},"delete":{"tags":["Listings"],"summary":"Delete listing","description":"Delete a listing by ID and its stored content. Irreversible. Published listings with existing orders can still be deleted — order history is preserved but the checkout URL stops working.","operationId":"delete_listing","security":[{"HTTPBearer":[]}],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","description":"Listing ID (lst_ prefixed).","examples":["lst_abc123"],"title":"Listing Id"},"description":"Listing ID (lst_ prefixed)."}],"responses":{"204":{"description":"Successful Response"},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Listing not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/listings/{listing_id}/deliverables":{"put":{"tags":["Listings"],"summary":"Set deliverables","description":"Replace all deliverables on a draft listing. Accepts an array of up to 3 deliverables (file, url, text). File tokens must be obtained via POST /v1/files first. Old file deliverables are automatically cleaned up from storage. After setting deliverables, call POST /v1/listings/{listing_id}/publish to make the listing live and buyable.","operationId":"set_deliverables","security":[{"HTTPBearer":[]}],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","description":"Listing ID (lst_ prefixed).","examples":["lst_7kQ2xY9mN3pR5tW1vB8a"],"title":"Listing Id"},"description":"Listing ID (lst_ prefixed)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetDeliverablesRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingResponse"}}}},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Listing not found or not owned by this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Listing is not in draft status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Validation error (too many, invalid token, etc).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}},"post":{"tags":["Listings"],"summary":"Add deliverable","description":"Add a single deliverable to a draft listing. Appends to the existing array. Returns the new deliverable with a unique del_ prefixed ID. Max 3 deliverables per listing — returns 409 if at capacity. When all deliverables are set, call POST /v1/listings/{listing_id}/publish to go live.","operationId":"add_deliverable","security":[{"HTTPBearer":[]}],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","description":"Listing ID (lst_ prefixed).","examples":["lst_7kQ2xY9mN3pR5tW1vB8a"],"title":"Listing Id"},"description":"Listing ID (lst_ prefixed)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddDeliverableRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeliverableResponse"}}}},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Listing not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Listing not in draft, or at max capacity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}},"delete":{"tags":["Listings"],"summary":"Remove deliverables","description":"Remove all deliverables from a draft listing. Switches the listing to external fulfillment — orders will fire order.paid webhooks instead of auto-delivering content. Draft only — returns 409 if the listing is published. After removing, check readiness via GET /v1/listings/{listing_id}.","operationId":"remove_deliverables","security":[{"HTTPBearer":[]}],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","description":"Listing ID (lst_ prefixed).","examples":["lst_abc123"],"title":"Listing Id"},"description":"Listing ID (lst_ prefixed)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingResponse"}}}},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Listing not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Listing is not in draft state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/listings/{listing_id}/deliverables/{deliverable_id}":{"delete":{"tags":["Listings"],"summary":"Remove deliverable","description":"Remove a single deliverable by its del_ ID from a draft listing. If the deliverable is a file, the CDN content is cleaned up. Draft only — returns 409 if the listing is published. After adjusting deliverables, check readiness via GET /v1/listings/{listing_id}.","operationId":"remove_deliverable","security":[{"HTTPBearer":[]}],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","description":"Listing ID (lst_ prefixed).","examples":["lst_7kQ2xY9mN3pR5tW1vB8a"],"title":"Listing Id"},"description":"Listing ID (lst_ prefixed)."},{"name":"deliverable_id","in":"path","required":true,"schema":{"type":"string","description":"Deliverable ID (del_ prefixed).","examples":["del_7kQ2xY9mN3pR5tW1vB8a"],"title":"Deliverable Id"},"description":"Deliverable ID (del_ prefixed)."}],"responses":{"204":{"description":"Successful Response"},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Listing or deliverable not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Listing is not in draft status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/listings/{listing_id}/publish":{"post":{"tags":["Listings"],"summary":"Publish listing","description":"Validate and publish a draft listing. Transitions to published state — the listing becomes live, buyable, and immutable. Fails with 409 and readiness actions if requirements are not met.","operationId":"publish_listing","security":[{"HTTPBearer":[]}],"parameters":[{"name":"listing_id","in":"path","required":true,"schema":{"type":"string","description":"Listing ID (lst_ prefixed).","examples":["lst_abc123"],"title":"Listing Id"},"description":"Listing ID (lst_ prefixed)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingResponse"}}}},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Listing not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"409":{"description":"Publish requirements not met.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/orders":{"get":{"tags":["Orders"],"summary":"List orders","description":"List orders for the authenticated account. Filter by status, listing, and date range. Paginated. Returns lightweight summaries — use GET /v1/orders/{order_id} for full detail including deliverables, readiness, checkout_data, and Stripe payment intent. Order lifecycle: PENDING → PAID → FULFILLED. Terminal: CANCELED, FAILED.","operationId":"list_orders","security":[{"HTTPBearer":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/OrderStatus"},{"type":"null"}],"description":"Filter orders by status.","examples":["paid"],"title":"Status"},"description":"Filter orders by status."},{"name":"listing","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by listing ID (lst_ prefixed).","examples":["lst_abc123"],"title":"Listing"},"description":"Filter by listing ID (lst_ prefixed)."},{"name":"buyer_email","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by exact buyer email address.","examples":["alice@example.com"],"title":"Buyer Email"},"description":"Filter by exact buyer email address."},{"name":"created_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only orders created after this ISO 8601 datetime.","examples":["2026-03-01T00:00:00Z"],"title":"Created After"},"description":"Only orders created after this ISO 8601 datetime."},{"name":"created_before","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only orders created before this ISO 8601 datetime.","examples":["2026-03-31T23:59:59Z"],"title":"Created Before"},"description":"Only orders created before this ISO 8601 datetime."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pagination cursor from a previous response.","title":"Cursor"},"description":"Pagination cursor from a previous response."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of orders to return.","examples":[20],"default":20,"title":"Limit"},"description":"Maximum number of orders to return."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderListResponse"}}}},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/orders/{order_id}":{"get":{"tags":["Orders"],"summary":"Get order","description":"Get a single order by ID. Order lifecycle: PENDING → PAID → FULFILLED. Check has_deliverables to determine fulfillment mode: if true, content was auto-delivered on payment (order is already FULFILLED). If false, the order stays PAID — call POST /v1/orders/{order_id}/fulfill to deliver content via ListBee, or handle delivery externally via the order.paid webhook. Use readiness.next to determine the recommended next action.","operationId":"get_order","security":[{"HTTPBearer":[]}],"parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","description":"Order ID (ord_ prefixed).","examples":["ord_9xM4kP7nR2qT5wY1"],"title":"Order Id"},"description":"Order ID (ord_ prefixed)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderResponse"}}}},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Order not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/orders/{order_id}/refund":{"post":{"tags":["Orders"],"summary":"Refund order","description":"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 transitions to REFUNDED — refund_amount and refunded_at update asynchronously via Stripe webhook. An order.refunded webhook event fires when the refund completes.","operationId":"refund_order","security":[{"HTTPBearer":[]}],"parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","description":"Order ID (ord_ prefixed).","examples":["ord_9xM4kP7nR2qT5wY1"],"title":"Order Id"},"description":"Order ID (ord_ prefixed)."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderResponse"}}}},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Order not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Order cannot be refunded (wrong status or no payment intent).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/v1/orders/{order_id}/fulfill":{"post":{"tags":["Orders"],"summary":"Fulfill order","description":"Deliver content to the buyer via ListBee. Call this with deliverables after your system generates or prepares content. ListBee creates an access grant, emails the buyer a download link, and transitions the order to FULFILLED. Valid for any order in PAID status. Idempotent: calling on an already-FULFILLED order returns the order unchanged (body ignored, no second email).","operationId":"fulfill_order","security":[{"HTTPBearer":[]}],"parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","description":"Order ID (ord_ prefixed).","examples":["ord_9xM4kP7nR2qT5wY1"],"title":"Order Id"},"description":"Order ID (ord_ prefixed)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfillOrderRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderResponse"}}}},"401":{"description":"Invalid or missing API key."},"404":{"description":"Order not found."},"409":{"description":"Order is not in PAID status."},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/ping":{"get":{"tags":["Utility"],"summary":"Ping","description":"Connectivity check. Returns ok if the API is reachable. No authentication required.","operationId":"ping","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PingResponse"}}}}},"security":[{"HTTPBearer":[]}]}},"/v1/store":{"get":{"tags":["Store"],"summary":"Get Store","description":"Get the current store's brand info and readiness. Store is determined by your API key.","operationId":"get_store","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreResponse"}}}}},"security":[{"HTTPBearer":[]}]},"put":{"tags":["Store"],"summary":"Update Store","description":"Update store brand info: display_name, bio, avatar (file token from POST /v1/files), slug. Response includes readiness status — check actions for what's needed before selling.","operationId":"update_store","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreUpdateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"HTTPBearer":[]}]}},"/v1/account/stripe/connect":{"post":{"tags":["Stripe"],"summary":"Start Stripe Connect onboarding","description":"Start Stripe Connect guided onboarding. Returns a URL to redirect the human to. The human completes Stripe's identity and bank account verification flow. On completion, Stripe fires an account.updated webhook and ListBee marks the account as connected. The stripe_account_id is saved immediately — payment_config is set only after webhook confirmation.","operationId":"start_stripe_connect","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StripeConnectSessionResponse"}}}},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}},"security":[{"HTTPBearer":[]}]}},"/v1/account/stripe":{"delete":{"tags":["Stripe"],"summary":"Disconnect Stripe","description":"Remove Stripe configuration from the account. All published listings become unsellable — checkout URLs return an error until Stripe is reconnected. Call POST /v1/account/stripe/connect to start a new Connect session.","operationId":"disconnect_stripe","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Disconnect Stripe"}}}},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}},"security":[{"HTTPBearer":[]}]}},"/v1/webhooks":{"get":{"tags":["Webhooks"],"summary":"List webhooks","description":"List all webhook endpoints for the authenticated account. Use POST /v1/webhooks to register new endpoints. All order event payloads include the full order snapshot — no follow-up API calls needed.","operationId":"list_webhooks","security":[{"HTTPBearer":[]}],"parameters":[{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pagination cursor from a previous response.","title":"Cursor"},"description":"Pagination cursor from a previous response."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of webhooks to return.","examples":[20],"default":20,"title":"Limit"},"description":"Maximum number of webhooks to return."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookListResponse"}}}},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"tags":["Webhooks"],"summary":"Create webhook","description":"Register a webhook endpoint. Returns the endpoint with its signing secret — store it, shown once. All order events (order.paid, order.fulfilled, order.refunded, order.disputed, order.dispute_closed, order.canceled) include a full order snapshot in the payload: order_id, listing_id, listing_slug, buyer_email, amount, currency, status, has_deliverables, payment_status, checkout_data, listing_metadata, timestamps, and deliverable info. Agents never need a follow-up API call after receiving a webhook. See the WebhookPayloadExample schema for the full payload shape.","operationId":"create_webhook","security":[{"HTTPBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookResponse"}}}},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/v1/webhooks/{webhook_id}":{"put":{"tags":["Webhooks"],"summary":"Update webhook","description":"Update a webhook endpoint URL, name, or subscribed events. Only provided fields are changed. Use POST /v1/webhooks/{webhook_id}/test to verify the updated endpoint receives events correctly.","operationId":"update_webhook","security":[{"HTTPBearer":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","description":"Webhook endpoint ID.","examples":["wh_3mK8nP2qR5tW7xY1"],"title":"Webhook Id"},"description":"Webhook endpoint ID."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateWebhookRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookResponse"}}}},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Webhook not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}},"delete":{"tags":["Webhooks"],"summary":"Delete webhook","description":"Delete a webhook endpoint. Irreversible. Pending event deliveries for this endpoint are canceled. Order events will no longer be sent to this URL.","operationId":"delete_webhook","security":[{"HTTPBearer":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","description":"Webhook endpoint ID.","examples":["wh_3mK8nP2qR5tW7xY1"],"title":"Webhook Id"},"description":"Webhook endpoint ID."}],"responses":{"204":{"description":"Successful Response"},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Webhook not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/webhooks/{webhook_id}/events":{"get":{"tags":["Webhooks"],"summary":"List webhook delivery events","description":"List delivery event history for a webhook endpoint. Use to debug failed deliveries.","operationId":"list_webhook_events","security":[{"HTTPBearer":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","description":"Webhook endpoint ID.","examples":["wh_3mK8nP2qR5tW7xY1"],"title":"Webhook Id"},"description":"Webhook endpoint ID."},{"name":"delivered","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Filter by delivery status. `true` for delivered, `false` for pending/failed.","title":"Delivered"},"description":"Filter by delivery status. `true` for delivered, `false` for pending/failed."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pagination cursor from a previous response.","title":"Cursor"},"description":"Pagination cursor from a previous response."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of events to return.","examples":[20],"default":20,"title":"Limit"},"description":"Maximum number of events to return."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEventListResponse"}}}},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Webhook not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/webhooks/{webhook_id}/events/{event_id}/retry":{"post":{"tags":["Webhooks"],"summary":"Retry a webhook event","description":"Reset a failed webhook event and re-dispatch for immediate delivery. Clears attempts, failed_at, last_error, and delivered_at, then enqueues a new delivery.","operationId":"retry_webhook_event","security":[{"HTTPBearer":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","description":"Webhook endpoint ID.","examples":["wh_3mK8nP2qR5tW7xY1"],"title":"Webhook Id"},"description":"Webhook endpoint ID."},{"name":"event_id","in":"path","required":true,"schema":{"type":"string","description":"Webhook event ID.","examples":["evt_7kQ2xY9mN3pR5tW1"],"title":"Event Id"},"description":"Webhook event ID."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEventResponse"}}}},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Webhook or event not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/webhooks/{webhook_id}/test":{"post":{"tags":["Webhooks"],"summary":"Test webhook","description":"Send a test event to a webhook endpoint and return the delivery result. Does not persist an event record. Use this to verify your endpoint is reachable and correctly processes the payload. The response includes status_code and body from your endpoint.","operationId":"test_webhook","security":[{"HTTPBearer":[]}],"parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string","description":"Webhook endpoint ID.","examples":["wh_3mK8nP2qR5tW7xY1"],"title":"Webhook Id"},"description":"Webhook endpoint ID."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTestResponse"}}}},"401":{"description":"Invalid or missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"404":{"description":"Webhook not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/bootstrap":{"post":{"tags":["Bootstrap"],"summary":"Start bootstrap — send OTP","description":"Step 1 of 3. Send a one-time passcode to the provided email. Returns a session ID to use in step 2 (POST /v1/bootstrap/verify). Public endpoint — no API key required. Use this to create a new account programmatically without the developer console.","operationId":"bootstrap_start","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BootstrapRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BootstrapResponse"}}}},"422":{"description":"Blocked or disposable email domain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"OTP rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}},"/v1/bootstrap/verify":{"post":{"tags":["Bootstrap"],"summary":"Verify OTP — confirm identity","description":"Step 2 of 3. Verify the OTP sent in step 1. On success, the session is marked verified and an account is created if this is a new email. Returns the session ID to use in step 3 (POST /v1/bootstrap/store). Public endpoint — no API key required.","operationId":"bootstrap_verify","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BootstrapVerifyRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BootstrapVerifyResponse"}}}},"400":{"description":"Invalid or expired session / invalid OTP code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"429":{"description":"Verification attempt rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/bootstrap/store":{"post":{"tags":["Bootstrap"],"summary":"Create store — final bootstrap step","description":"Step 3 of 3. Create a store on a verified bootstrap session. Returns the store object with a one-time `api_key` — store this immediately, it will not be shown again. Use the API key as `Authorization: Bearer lb_...` for all subsequent API calls. Public endpoint — no API key required.","operationId":"bootstrap_store","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BootstrapStoreRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreResponse"}}}},"400":{"description":"Session not verified or expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/plans":{"get":{"tags":["Plans"],"summary":"List plans","description":"List all available plans with pricing. Public endpoint — no authentication required. Response is cacheable.","operationId":"list_plans","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanListResponse"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetail"}}}}}}}},"components":{"schemas":{"AccountReadiness":{"properties":{"operational":{"type":"boolean","title":"Operational","description":"True when the account can sell. False means actions are needed.","examples":[true]},"actions":{"items":{"$ref":"#/components/schemas/Action"},"type":"array","title":"Actions","description":"What's needed to make this account operational. Empty when operational is true."},"next":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next","description":"Code of the highest-priority action.","examples":["connect_stripe"]}},"type":"object","required":["operational"],"title":"AccountReadiness"},"AccountResponse":{"properties":{"object":{"type":"string","const":"account","title":"Object","description":"Object type identifier. Always `account`.","default":"account","examples":["account"]},"id":{"type":"string","title":"Id","description":"Unique account ID (acc_ prefixed).","examples":["acc_7kQ2xY9mN3pR5tW1"]},"email":{"type":"string","title":"Email","description":"Account email address","examples":["seller@example.com"]},"plan":{"type":"string","title":"Plan","description":"Current plan tier. Values: free (15% fee), growth (5% fee), scale (3% fee).","examples":["free","growth","scale"]},"fee_rate":{"type":"string","title":"Fee Rate","description":"Transaction fee rate as decimal string. Determined by plan: free=0.15, growth=0.05, scale=0.03. Applied as platform fee on each order.","examples":["0.10","0.05"]},"billing_status":{"type":"string","title":"Billing Status","description":"Subscription billing status. `active` = payments current. `past_due` = payment failed, service continues during grace period. `unpaid` = grace period expired, listings may be blocked.","examples":["active","past_due"]},"currency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Currency","description":"Account currency (ISO 4217, lowercase). Set automatically from Stripe Connect. Cannot be changed after connection.","examples":["usd","eur"]},"ga_measurement_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ga Measurement Id","description":"Google Analytics 4 Measurement ID (G-XXXXXXXXXX). Set via PUT /v1/account. Injected on all your product pages and thank-you pages","examples":["G-ABC123XYZ"]},"notify_orders":{"type":"boolean","title":"Notify Orders","description":"Whether seller receives email alerts for new external orders","examples":[true]},"stats":{"$ref":"#/components/schemas/AccountStats","description":"Account aggregate statistics."},"readiness":{"$ref":"#/components/schemas/AccountReadiness","description":"Account operational readiness. `operational` is true when the account can sell. If false, `actions` lists what's needed with kind (api/human), resolve details, and `next` points to the highest-priority action."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Time at which the account was created","examples":["2026-03-15T10:00:00Z"]}},"type":"object","required":["id","email","plan","fee_rate","billing_status","notify_orders","stats","readiness","created_at"],"title":"AccountResponse"},"AccountStats":{"properties":{"total_revenue":{"type":"integer","title":"Total Revenue","description":"Total revenue in smallest currency unit (completed orders)","examples":[145000]},"total_orders":{"type":"integer","title":"Total Orders","description":"Total number of orders this month","examples":[47]},"total_listings":{"type":"integer","title":"Total Listings","description":"Total number of listings","examples":[12]}},"type":"object","required":["total_revenue","total_orders","total_listings"],"title":"AccountStats"},"Action":{"properties":{"code":{"$ref":"#/components/schemas/ActionCode","description":"Machine-readable action identifier for automation branching.","examples":["connect_stripe"]},"kind":{"$ref":"#/components/schemas/ActionKind","description":"Whether an agent can execute this directly (api) or needs human interaction (human).","examples":["api"]},"priority":{"$ref":"#/components/schemas/ActionPriority","description":"Whether this action blocks progress (required) or is an available opportunity (suggested).","examples":["required"]},"message":{"type":"string","title":"Message","description":"Human-readable explanation. AI agents relay this to users.","examples":["Set Stripe secret key to accept payments"]},"resolve":{"$ref":"#/components/schemas/ActionResolve","description":"How to resolve this action."}},"type":"object","required":["code","kind","priority","message","resolve"],"title":"Action"},"ActionCode":{"type":"string","enum":["connect_stripe","enable_charges","update_billing","configure_fulfillment","publish_listing","webhook_disabled","fulfill_order"],"title":"ActionCode"},"ActionKind":{"type":"string","enum":["api","human"],"title":"ActionKind"},"ActionPriority":{"type":"string","enum":["required","suggested"],"title":"ActionPriority"},"ActionResolve":{"properties":{"method":{"type":"string","title":"Method","description":"How to resolve: HTTP method (POST, GET) for kind=api, 'redirect' for kind=human.","examples":["POST"]},"endpoint":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Endpoint","description":"API endpoint path for kind=api actions.","examples":["/v1/account/stripe-key"]},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"Full URL for kind=human actions (browser redirect).","examples":["https://console.listbee.so/connect/stripe"]},"params":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Params","description":"Example request body for kind=api actions.","examples":[{"secret_key":"sk_live_..."}]}},"type":"object","required":["method"],"title":"ActionResolve"},"AddDeliverableRequest":{"properties":{"type":{"$ref":"#/components/schemas/DeliverableType","description":"Deliverable type: `file` (uploaded via POST /v1/files), `url` (redirect), or `text` (literal string).","examples":["file"]},"token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token","description":"File token from POST /v1/files. Required when type is `file`.","examples":["file_7kQ2xY9mN3pR5tW1vB8a01"]},"value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value","description":"URL (https required) or text content. Required when type is `url` or `text`.","examples":["https://example.com/secret-area"]}},"type":"object","required":["type"],"title":"AddDeliverableRequest","description":"Add a single deliverable to a listing."},"BlurMode":{"type":"string","enum":["true","false","auto"],"title":"BlurMode"},"Body_upload_file":{"properties":{"file":{"type":"string","contentMediaType":"application/octet-stream","title":"File","description":"The file to upload"},"purpose":{"type":"string","title":"Purpose","description":"File purpose: 'deliverable' (listing content), 'cover' (listing image), 'avatar' (account image). Defaults to 'deliverable'.","default":"deliverable","examples":["deliverable"]}},"type":"object","required":["file"],"title":"Body_upload_file"},"BootstrapRequest":{"properties":{"email":{"type":"string","format":"email","title":"Email","description":"Account owner email","examples":["seller@example.com"]}},"type":"object","required":["email"],"title":"BootstrapRequest"},"BootstrapResponse":{"properties":{"object":{"type":"string","const":"bootstrap_session","title":"Object","description":"Object type identifier.","default":"bootstrap_session","examples":["bootstrap_session"]},"session":{"type":"string","title":"Session","description":"Bootstrap session ID. Pass to the next step.","examples":["sess_abc123"]},"otp_sent":{"type":"boolean","title":"Otp Sent","description":"True when OTP was sent to the email address.","examples":[true]}},"type":"object","required":["session","otp_sent"],"title":"BootstrapResponse"},"BootstrapStoreRequest":{"properties":{"session":{"type":"string","title":"Session","description":"Verified session ID from bootstrap step 2","examples":["sess_abc123"]},"store_name":{"type":"string","maxLength":200,"minLength":1,"title":"Store Name","description":"Display name for the store","examples":["Acme Agency"]}},"type":"object","required":["session","store_name"],"title":"BootstrapStoreRequest"},"BootstrapVerifyRequest":{"properties":{"session":{"type":"string","title":"Session","description":"Session ID from bootstrap step 1","examples":["sess_abc123"]},"code":{"type":"string","maxLength":6,"minLength":6,"title":"Code","description":"6-digit OTP code from email","examples":["123456"]}},"type":"object","required":["session","code"],"title":"BootstrapVerifyRequest"},"BootstrapVerifyResponse":{"properties":{"object":{"type":"string","const":"bootstrap_session","title":"Object","description":"Object type identifier.","default":"bootstrap_session","examples":["bootstrap_session"]},"verified":{"type":"boolean","title":"Verified","description":"True when OTP was verified successfully.","examples":[true]},"session":{"type":"string","title":"Session","description":"Verified session ID. Pass to POST /v1/bootstrap/store.","examples":["sess_abc123"]}},"type":"object","required":["verified","session"],"title":"BootstrapVerifyResponse"},"CheckoutFieldInput":{"properties":{"key":{"type":"string","maxLength":50,"title":"Key","description":"Unique key for this field","examples":["size","note"]},"type":{"$ref":"#/components/schemas/CheckoutFieldType","description":"Field type","examples":["text"]},"label":{"type":"string","maxLength":100,"title":"Label","description":"Label shown to buyer","examples":["Shoe size"]},"required":{"type":"boolean","title":"Required","description":"Whether this field is required","default":true,"examples":[true]},"options":{"anyOf":[{"items":{"type":"string"},"type":"array","maxItems":50},{"type":"null"}],"title":"Options","description":"Options for select fields","examples":[["S","M","L"]]},"sort_order":{"type":"integer","minimum":0.0,"title":"Sort Order","description":"Display order. Lower values shown first. Fields with equal sort_order are ordered by position in the array.","default":0,"examples":[0,1,2]}},"type":"object","required":["key","type","label"],"title":"CheckoutFieldInput","description":"A field to collect from the buyer at checkout."},"CheckoutFieldType":{"type":"string","enum":["text","select","date"],"title":"CheckoutFieldType","description":"Types of fields that can be collected at checkout."},"CreateListingRequest":{"properties":{"checkout_schema":{"anyOf":[{"items":{"$ref":"#/components/schemas/CheckoutFieldInput"},"type":"array"},{"type":"null"}],"title":"Checkout Schema","description":"Custom fields to collect from the buyer at checkout (e.g. size, color, shipping address). Email is always collected.","examples":[[{"key":"size","label":"Size","options":["S","M","L"],"type":"select"}]]},"name":{"type":"string","title":"Name","description":"Product name shown on the product page","examples":["SEO Playbook 2026","Premium Stock Picks"]},"fulfillment_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fulfillment Url","description":"Callback URL — ListBee POSTs an enriched payload here when someone buys this listing. Use for stateless agent fulfillment: metadata + checkout_data round-tripped in the callback. Must be HTTPS in production.","examples":["https://my-agent.com/fulfill"]},"price":{"type":"integer","exclusiveMinimum":0.0,"title":"Price","description":"Price in cents (smallest currency unit). Examples: $5 = 500, $29 = 2900, $99.99 = 9999.","examples":[500,2900,9999]},"stock":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Stock","description":"Stock quantity. null = unlimited (default), 0 = out of stock, positive integer = sell N then stop. Auto-decrements on each order.","examples":[null,100,0]},"description":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}],"title":"Description","description":"Product description shown on the product page. Improves buyer conversion. Plain text, max 5000 chars.","examples":["A comprehensive guide to modern SEO techniques."]},"tagline":{"anyOf":[{"type":"string","maxLength":140},{"type":"null"}],"title":"Tagline","description":"Short tagline shown below the product name on the product page. Max 140 chars.","examples":["Updated for 2026 algorithm changes"]},"highlights":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Highlights","description":"Bullet-point features shown as badges on the product page. Max 10 items. Each should be short (2-4 words).","examples":[["50+ pages","Actionable tips","Free updates"]]},"cta":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}],"title":"Cta","description":"Buy button text on the product page. Defaults to 'Buy Now' if omitted. Max 60 chars.","examples":["Get Instant Access","Download Now"]},"cover":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cover","description":"Cover image file token from POST /v1/files. Shown prominently on the product page. Recommended: 1200x630px.","examples":["file_tok_abc123"]},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Arbitrary key-value pairs forwarded in webhook event payloads. Use for your own tracking (campaign IDs, source tags).","examples":[{"campaign":"launch-week","source":"n8n"}]},"utm_source":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Utm Source","description":"UTM source tag for Google Analytics. Defaults to 'listbee' if omitted","examples":["google","newsletter","twitter"]},"utm_medium":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Utm Medium","description":"UTM medium tag for Google Analytics. Defaults to 'product_page' if omitted","examples":["cpc","email","social"]},"utm_campaign":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Utm Campaign","description":"UTM campaign tag for Google Analytics. Defaults to the listing slug if omitted","examples":["spring-sale","launch-week"]},"compare_at_price":{"anyOf":[{"type":"integer","exclusiveMinimum":0.0},{"type":"null"}],"title":"Compare At Price","description":"Strikethrough price in cents (smallest currency unit). Must be greater than price. Examples: $39 = 3900.","examples":[3900,4900]},"badges":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Badges","description":"Short promotional badges shown on the product page (e.g. 'Best seller', 'Limited time'). Max 10 items.","examples":[["Limited time","Best seller"]]},"cover_blur":{"$ref":"#/components/schemas/BlurMode","description":"Cover image blur mode. 'true' always blurs, 'false' never blurs, 'auto' blurs when deliverable is an image file.","default":"auto","examples":["auto"]},"rating":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rating","description":"Seller-provided aggregate star rating (1-5). Shown on the product page. Values outside range clamped.","examples":[4.8,4.5]},"rating_count":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Rating Count","description":"Seller-provided review or purchase count shown alongside the rating on the product page.","examples":[1243,89]},"reviews":{"anyOf":[{"items":{"$ref":"#/components/schemas/ReviewInput"},"type":"array"},{"type":"null"}],"title":"Reviews","description":"Featured review cards shown on the product page. Seller-provided, not buyer-submitted. Max 10.","examples":[[{"content":"Best decision I've made for my health.","name":"Clara D.","rating":4.5}]]},"faqs":{"anyOf":[{"items":{"$ref":"#/components/schemas/FaqItemInput"},"type":"array"},{"type":"null"}],"title":"Faqs","description":"FAQ accordion shown on the product page. Answers common buyer questions. Max 10 items.","examples":[[{"a":"Yes, completely beginner-friendly.","q":"Is this for beginners?"}]]}},"type":"object","required":["name","price"],"title":"CreateListingRequest","description":"All optional display fields (name, description, tagline, highlights, cta, badges, cover, reviews, faqs) appear on the product page buyers see."},"CreateWebhookRequest":{"properties":{"name":{"type":"string","title":"Name","description":"A name to help you identify this endpoint in the dashboard","examples":["Order notifications"]},"url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Url","description":"The HTTPS URL that will receive POST requests for each event","examples":["https://example.com/webhooks/listbee"]},"events":{"items":{"$ref":"#/components/schemas/WebhookEventType"},"type":"array","title":"Events","description":"Event types to subscribe to. Empty = all events. Available: order.paid, order.fulfilled, order.refunded, order.disputed, order.dispute_closed, order.canceled, listing.created, listing.updated, listing.published, listing.out_of_stock, listing.deleted, customer.created.","examples":[["order.paid"]]}},"type":"object","required":["name","url"],"title":"CreateWebhookRequest"},"CustomerListResponse":{"properties":{"object":{"type":"string","const":"list","title":"Object","description":"Object type identifier.","default":"list","examples":["list"]},"data":{"items":{"$ref":"#/components/schemas/CustomerResponse"},"type":"array","title":"Data","description":"Array of customer objects."},"cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor","description":"Cursor for next page."},"has_more":{"type":"boolean","title":"Has More","description":"Whether more results exist.","examples":[false]}},"type":"object","required":["data","has_more"],"title":"CustomerListResponse"},"CustomerResponse":{"properties":{"object":{"type":"string","const":"customer","title":"Object","description":"Object type identifier. Always `customer`.","default":"customer","examples":["customer"]},"id":{"type":"string","title":"Id","description":"Unique customer ID (cus_ prefixed).","examples":["cus_7kQ2xY9mN3pR5tW1vB8a01"]},"email":{"type":"string","title":"Email","description":"Buyer email address.","examples":["alice@example.com"]},"total_orders":{"type":"integer","title":"Total Orders","description":"Total number of completed orders from this buyer.","examples":[3]},"total_spent":{"type":"integer","title":"Total Spent","description":"Total amount spent in cents (smallest currency unit).","examples":[8700]},"currency":{"type":"string","title":"Currency","description":"Currency code.","examples":["usd"]},"first_order_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"First Order At","description":"When this buyer first purchased.","examples":["2026-03-15T10:00:00Z"]},"last_order_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Order At","description":"When this buyer most recently purchased.","examples":["2026-04-01T14:30:00Z"]},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When this customer record was created.","examples":["2026-03-15T10:00:00Z"]}},"type":"object","required":["id","email","total_orders","total_spent","currency","created_at"],"title":"CustomerResponse"},"DeliverableInputRequest":{"properties":{"type":{"$ref":"#/components/schemas/DeliverableType","description":"Deliverable type: `file` (uploaded via POST /v1/files), `url` (redirect), or `text` (literal string).","examples":["file"]},"token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Token","description":"File token from POST /v1/files. Required when type is `file`.","examples":["file_7kQ2xY9mN3pR5tW1vB8a01"]},"value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value","description":"URL (https required) or text content. Required when type is `url` or `text`.","examples":["https://example.com/secret-area"]}},"type":"object","required":["type"],"title":"DeliverableInputRequest","description":"Typed deliverable input. Shared by PUT /deliverables and POST /fulfill."},"DeliverableResponse":{"properties":{"object":{"type":"string","const":"deliverable","title":"Object","description":"Object type identifier.","default":"deliverable","examples":["deliverable"]},"id":{"type":"string","title":"Id","description":"Unique deliverable identifier (del_ prefixed).","examples":["del_7kQ2xY9mN3pR5tW1vB8a01"]},"type":{"$ref":"#/components/schemas/DeliverableType","description":"Deliverable type.","examples":["file"]},"status":{"$ref":"#/components/schemas/DeliverableStatus","description":"Processing status.","examples":["ready"]},"filename":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filename","description":"Original filename (file type only).","examples":["ebook.pdf"]},"size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Size","description":"File size in bytes (file type only).","examples":[2458631]},"mime_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Mime Type","description":"MIME type (file type only).","examples":["application/pdf"]},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"Redirect URL (url type only).","examples":["https://example.com/secret"]},"content":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Content","description":"Text content (text type only).","examples":["Buy signal: AAPL"]}},"type":"object","required":["id","type","status"],"title":"DeliverableResponse"},"DeliverableStatus":{"type":"string","enum":["processing","ready","failed"],"title":"DeliverableStatus"},"DeliverableType":{"type":"string","enum":["file","url","text"],"title":"DeliverableType"},"FaqItemInput":{"properties":{"q":{"type":"string","maxLength":200,"title":"Q","description":"Question text","examples":["Is this for beginners?"]},"a":{"type":"string","maxLength":1000,"title":"A","description":"Answer text","examples":["Yes, completely beginner-friendly."]}},"type":"object","required":["q","a"],"title":"FaqItemInput"},"FileResponse":{"properties":{"object":{"type":"string","const":"file","title":"Object","description":"Object type identifier. Always `file`.","default":"file","examples":["file"]},"id":{"type":"string","title":"Id","description":"File token. Pass as 'token' to set_deliverables, or as 'cover'/'avatar' to create/update listing/account.","examples":["file_7kQ2xY9mN3pR5tW1vB8a01"]},"filename":{"type":"string","title":"Filename","description":"Original filename","examples":["ebook.pdf"]},"size":{"type":"integer","title":"Size","description":"File size in bytes","examples":[2458631]},"mime_type":{"type":"string","title":"Mime Type","description":"MIME type","examples":["application/pdf"]},"purpose":{"type":"string","title":"Purpose","description":"File purpose. Determines size and type limits: 'avatar' (2 MB, JPEG/PNG/WebP/GIF), 'cover' (5 MB, JPEG/PNG/WebP/GIF), 'deliverable' (25 MB, documents/images/audio/video).","examples":["deliverable"]},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At","description":"Token expires at this time. Upload a new file after expiry. None when file is permanently attached.","examples":["2026-04-03T15:00:00Z"]},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Time at which the file was uploaded","examples":["2026-04-03T14:00:00Z"]}},"type":"object","required":["id","filename","size","mime_type","purpose","expires_at","created_at"],"title":"FileResponse"},"FulfillOrderRequest":{"properties":{"deliverables":{"items":{"$ref":"#/components/schemas/DeliverableInputRequest"},"type":"array","maxItems":3,"minItems":1,"title":"Deliverables","description":"Generated content to deliver to the buyer (1–3 items). Mixed types allowed: file (token from POST /v1/files), url (redirect link), or text (literal string). ListBee creates an access grant from these and emails the buyer a download link."}},"type":"object","required":["deliverables"],"title":"FulfillOrderRequest","description":"Push generated content to a generated-type order. ListBee creates an access grant,\nemails the buyer a download link, and transitions the order to fulfilled."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ListingListResponse":{"properties":{"object":{"type":"string","const":"list","title":"Object","description":"Object type identifier. Always `list`.","default":"list","examples":["list"]},"data":{"items":{"$ref":"#/components/schemas/ListingSummary"},"type":"array","title":"Data","description":"Array of listing summary objects. Use GET /v1/listings/{id} for full detail."},"cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor","description":"Pass as `cursor` query param to fetch the next page","examples":["lst_7kQ2xY9mN3pR5tW1vB8a"]},"has_more":{"type":"boolean","title":"Has More","description":"True if more results exist beyond this page","default":false,"examples":[false]}},"type":"object","required":["data"],"title":"ListingListResponse"},"ListingReadiness":{"properties":{"sellable":{"type":"boolean","title":"Sellable","description":"True when buyers can purchase. False means actions are needed.","examples":[true]},"actions":{"items":{"$ref":"#/components/schemas/Action"},"type":"array","title":"Actions","description":"What's needed to make this listing sellable. Empty when sellable is true."},"next":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next","description":"Code of the highest-priority action. Agents execute this first.","examples":["connect_stripe"]}},"type":"object","required":["sellable"],"title":"ListingReadiness"},"ListingResponse":{"properties":{"object":{"type":"string","const":"listing","title":"Object","description":"Object type identifier. Always `listing`.","default":"listing","examples":["listing"]},"id":{"type":"string","title":"Id","description":"Unique listing ID (lst_ prefixed).","examples":["lst_7kQ2xY9mN3pR5tW1vB8a"]},"slug":{"type":"string","title":"Slug","description":"URL slug for the product page","examples":["seo-playbook"]},"name":{"type":"string","title":"Name","description":"Product name shown on the product page","examples":["SEO Playbook 2026"]},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"Product description shown on the product page. Plain text.","examples":["A comprehensive guide to modern SEO."]},"tagline":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tagline","description":"Short tagline shown below the product name on the product page.","examples":["Updated for 2026 algorithm changes"]},"highlights":{"items":{"type":"string"},"type":"array","title":"Highlights","description":"Bullet-point features shown as badges on the product page.","examples":[["50+ pages","Actionable tips"]]},"cta":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cta","description":"Buy button text on the product page. Defaults to 'Buy Now' if omitted.","examples":["Get Instant Access"]},"price":{"type":"integer","title":"Price","description":"Price in cents (smallest currency unit). Examples: $5 = 500, $29 = 2900, $99.99 = 9999.","examples":[500,2900,9999]},"deliverables":{"items":{"$ref":"#/components/schemas/DeliverableResponse"},"type":"array","title":"Deliverables","description":"Deliverables pre-attached to this listing. When present, ListBee auto-delivers them to buyers on payment. When empty, payment fires webhooks and fulfillment_url — your system handles delivery."},"fulfillment_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fulfillment Url","description":"Per-listing callback URL. ListBee POSTs enriched order payload here on purchase.","examples":["https://my-agent.com/fulfill"]},"has_deliverables":{"type":"boolean","title":"Has Deliverables","description":"True if deliverables are attached and have content. Determines post-payment behavior: true = ListBee auto-delivers, false = webhook/fulfillment_url fires.","examples":[true]},"checkout_schema":{"anyOf":[{"items":{"$ref":"#/components/schemas/CheckoutFieldInput"},"type":"array"},{"type":"null"}],"title":"Checkout Schema","description":"Custom fields collected from the buyer at checkout"},"has_cover":{"type":"boolean","title":"Has Cover","description":"True if a cover image exists (uploaded or generated)","examples":[true]},"compare_at_price":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Compare At Price","description":"Strikethrough price in smallest currency unit","examples":[3900]},"badges":{"items":{"type":"string"},"type":"array","title":"Badges","description":"Short promotional badges shown on the product page (e.g. 'Best seller', 'Limited time').","examples":[["Limited time"]]},"cover_blur":{"$ref":"#/components/schemas/BlurMode","description":"Cover image blur mode. 'true' always blurs, 'false' never blurs, 'auto' blurs when deliverable is an image file.","default":"auto","examples":["auto"]},"rating":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rating","description":"Seller-provided aggregate star rating (1-5). Shown on the product page.","examples":[4.8]},"rating_count":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Rating Count","description":"Seller-provided review or purchase count shown alongside the rating on the product page.","examples":[1243]},"reviews":{"items":{"$ref":"#/components/schemas/ReviewInput"},"type":"array","title":"Reviews","description":"Featured review cards shown on the product page. Seller-provided, not buyer-submitted.","examples":[[]]},"faqs":{"items":{"$ref":"#/components/schemas/FaqItemInput"},"type":"array","title":"Faqs","description":"FAQ accordion shown on the product page. Answers common buyer questions.","examples":[[]]},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Arbitrary key-value pairs forwarded in webhook event payloads. Set at creation or update.","examples":[{"source":"n8n"}]},"utm_source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Utm Source","description":"UTM source tag for Google Analytics","examples":["google"]},"utm_medium":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Utm Medium","description":"UTM medium tag for Google Analytics","examples":["cpc"]},"utm_campaign":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Utm Campaign","description":"UTM campaign tag for Google Analytics","examples":["spring-sale"]},"status":{"$ref":"#/components/schemas/ListingStatus","description":"Current listing status. Values: draft (editable, not yet live), published (live, accepting orders), deleted (soft-deleted).","examples":["published"]},"stock":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Stock","description":"Stock quantity. null = unlimited, 0 = out of stock. Auto-decrements on each order.","examples":[null,50,0]},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"Full product page URL — share this with buyers","examples":["https://buy.listbee.so/seo-playbook"]},"embed_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Embed Url","description":"Embeddable product page URL — use in iframes. Renders minimal version without header/footer.","examples":["https://buy.listbee.so/seo-playbook?embed=true"]},"readiness":{"$ref":"#/components/schemas/ListingReadiness","description":"Monetization readiness. `sellable` is true when buyers can complete a purchase. If false, `actions` lists what's needed with kind (api/human), resolve details, and `next` points to the highest-priority action."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Time at which the listing was created","examples":["2026-04-01T12:00:00Z"]}},"type":"object","required":["id","slug","name","highlights","price","has_deliverables","has_cover","status","readiness","created_at"],"title":"ListingResponse"},"ListingStatus":{"type":"string","enum":["draft","published"],"title":"ListingStatus"},"ListingSummary":{"properties":{"object":{"type":"string","const":"listing","title":"Object","description":"Object type identifier. Always `listing`.","default":"listing","examples":["listing"]},"id":{"type":"string","title":"Id","description":"Unique listing ID (lst_ prefixed).","examples":["lst_7kQ2xY9mN3pR5tW1vB8a"]},"slug":{"type":"string","title":"Slug","description":"URL slug — globally unique","examples":["seo-playbook"]},"name":{"type":"string","title":"Name","description":"Product title","examples":["SEO Playbook 2026"]},"tagline":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tagline","description":"One-line pitch","examples":["The only SEO guide you need"]},"price":{"type":"integer","title":"Price","description":"Price in cents (smallest currency unit). $29.00 = 2900.","examples":[2900]},"compare_at_price":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Compare At Price","description":"Original price for strikethrough display","examples":[4900]},"cta":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cta","description":"Call-to-action button text","examples":["Get the Playbook"]},"badges":{"items":{"type":"string"},"type":"array","title":"Badges","description":"Short badge labels","examples":[["Best seller"]]},"highlights":{"items":{"type":"string"},"type":"array","title":"Highlights","description":"Bullet point highlights"},"status":{"$ref":"#/components/schemas/ListingStatus","description":"Current listing status","examples":["published"]},"stock":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Stock","description":"Stock quantity. null = unlimited.","examples":[null,50,0]},"has_deliverables":{"type":"boolean","title":"Has Deliverables","description":"Whether listing has deliverables for auto-fulfillment","examples":[true]},"has_cover":{"type":"boolean","title":"Has Cover","description":"Whether a cover image is set","default":false},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Url","description":"Full product page URL","examples":["https://buy.listbee.so/seo-playbook"]},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Time at which the listing was created","examples":["2026-04-01T12:00:00Z"]}},"type":"object","required":["id","slug","name","price","status","has_deliverables","created_at"],"title":"ListingSummary","description":"Lightweight listing for list endpoints. Use GET /v1/listings/{id} for full detail."},"OrderListResponse":{"properties":{"object":{"type":"string","const":"list","title":"Object","description":"Object type identifier. Always `list`.","default":"list","examples":["list"]},"data":{"items":{"$ref":"#/components/schemas/OrderSummary"},"type":"array","title":"Data","description":"Array of order summary objects. Use GET /v1/orders/{id} for full detail."},"cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor","description":"Pass as `cursor` query param to fetch the next page","examples":["ord_7kQ2xY9mN3pR5tW1vB8a"]},"has_more":{"type":"boolean","title":"Has More","description":"True if more results exist beyond this page","default":false,"examples":[false]}},"type":"object","required":["data"],"title":"OrderListResponse"},"OrderReadiness":{"properties":{"fulfilled":{"type":"boolean","title":"Fulfilled","description":"True when the order has been delivered to the buyer.","examples":[true]},"actions":{"items":{"$ref":"#/components/schemas/Action"},"type":"array","title":"Actions","description":"Steps to fulfill this order. Empty when fulfilled."},"next":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next","description":"Highest-priority action code.","examples":["fulfill_order"]}},"type":"object","required":["fulfilled"],"title":"OrderReadiness"},"OrderResponse":{"properties":{"object":{"type":"string","const":"order","title":"Object","description":"Object type identifier. Always `order`.","default":"order","examples":["order"]},"id":{"type":"string","title":"Id","description":"Unique order ID (ord_ prefixed).","examples":["ord_9xM4kP7nR2qT5wY1"]},"listing_id":{"type":"string","title":"Listing Id","description":"ID of the purchased listing","examples":["lst_7kQ2xY9mN3pR5tW1vB8a"]},"buyer_email":{"type":"string","title":"Buyer Email","description":"Buyer's email address collected at Stripe Checkout. Use for customer communication.","examples":["buyer@example.com"]},"amount":{"type":"integer","title":"Amount","description":"Amount paid in cents (smallest currency unit). $29.00 = 2900.","examples":[2900]},"currency":{"type":"string","title":"Currency","description":"Three-letter ISO currency code, uppercase","examples":["USD"]},"status":{"$ref":"#/components/schemas/OrderStatus","description":"Current order status. Lifecycle: PENDING (checkout started) → PAID (payment confirmed) → FULFILLED (content delivered by ListBee). Terminal error states: CANCELED (payment failed/abandoned), FAILED (system error). PAID is the natural resting state for orders where the seller handles delivery externally. Call POST /fulfill to deliver content via ListBee and transition to FULFILLED.","examples":["paid"]},"checkout_data":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Checkout Data","description":"Custom checkout field values submitted by the buyer. Keys match the listing's checkout_schema.","examples":[{"note":"Gift wrap please","size":"M"}]},"has_deliverables":{"type":"boolean","title":"Has Deliverables","description":"Whether the listing had deliverables at purchase time. True = auto-delivered by ListBee. False = handled by seller/agent.","examples":[false]},"payment_status":{"type":"string","title":"Payment Status","description":"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.","examples":["paid"]},"listing_snapshot":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Listing Snapshot","description":"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.","examples":[{"name":"SEO Playbook 2026","price":2900,"slug":"seo-playbook-2026"}]},"seller_snapshot":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Seller Snapshot","description":"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.","examples":[{"display_name":"Acme Agency","email":"seller@example.com"}]},"deliverables":{"items":{"$ref":"#/components/schemas/DeliverableResponse"},"type":"array","title":"Deliverables","description":"Deliverables attached to this order. Auto-populated from listing deliverables on payment, or populated when POST /fulfill is called."},"actions":{"anyOf":[{"items":{"$ref":"#/components/schemas/Action"},"type":"array"},{"type":"null"}],"title":"Actions","description":"Available actions for this order. Only present when actions exist. PAID orders show FULFILL_ORDER (suggested) — deliver content to buyer via ListBee. Omitted for FULFILLED, CANCELED, FAILED orders."},"readiness":{"$ref":"#/components/schemas/OrderReadiness","description":"Order readiness state. fulfilled=True means the buyer has received the content. When fulfilled=False and status=PAID, actions contains FULFILL_ORDER — call it to deliver. Agents should check readiness.next for the highest-priority action code."},"stripe_payment_intent_id":{"type":"string","title":"Stripe Payment Intent Id","description":"Stripe PaymentIntent ID. Use for cross-referencing with Stripe dashboard or API.","examples":["pi_3abc123def456"]},"platform_fee":{"type":"integer","title":"Platform Fee","description":"Platform fee in cents deducted from this order. Amount seller receives = amount - platform_fee.","default":0,"examples":[290]},"refund_amount":{"type":"integer","title":"Refund Amount","description":"Amount refunded to buyer in cents. 0 if not refunded.","default":0,"examples":[0,2900]},"refunded_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Refunded At","description":"When the refund was processed. null if not refunded.","examples":["2026-04-01T15:30:00Z"]},"dispute_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dispute Status","description":"Stripe dispute status if disputed. Values: needs_response, under_review, won, lost.","examples":["needs_response"]},"dispute_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dispute Reason","description":"Reason for the dispute as reported by the buyer's bank.","examples":["product_not_received","fraudulent"]},"dispute_amount":{"type":"integer","title":"Dispute Amount","description":"Disputed amount in cents. 0 if not disputed.","default":0,"examples":[0,2900]},"disputed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Disputed At","description":"When the dispute was opened. null if not disputed.","examples":["2026-04-02T10:00:00Z"]},"paid_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Paid At","description":"When payment was confirmed","examples":["2026-04-02T14:30:00Z"]},"fulfilled_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Fulfilled At","description":"When order was fulfilled","examples":["2026-04-02T15:00:00Z"]},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Time at which the order was created","examples":["2026-04-02T14:00:00Z"]}},"type":"object","required":["id","listing_id","buyer_email","amount","currency","status","has_deliverables","payment_status","readiness","stripe_payment_intent_id","created_at"],"title":"OrderResponse"},"OrderStatus":{"type":"string","enum":["pending","paid","fulfilled","canceled","failed"],"title":"OrderStatus"},"OrderSummary":{"properties":{"object":{"type":"string","const":"order","title":"Object","description":"Object type identifier. Always `order`.","default":"order","examples":["order"]},"id":{"type":"string","title":"Id","description":"Unique order ID (ord_ prefixed).","examples":["ord_9xM4kP7nR2qT5wY1"]},"listing_id":{"type":"string","title":"Listing Id","description":"ID of the purchased listing","examples":["lst_7kQ2xY9mN3pR5tW1vB8a"]},"buyer_email":{"type":"string","title":"Buyer Email","description":"Buyer's email address.","examples":["buyer@example.com"]},"amount":{"type":"integer","title":"Amount","description":"Amount paid in cents.","examples":[2900]},"currency":{"type":"string","title":"Currency","description":"Three-letter ISO currency code, uppercase","examples":["USD"]},"status":{"$ref":"#/components/schemas/OrderStatus","description":"Current order status.","examples":["paid"]},"has_deliverables":{"type":"boolean","title":"Has Deliverables","description":"Whether auto-fulfilled by ListBee.","examples":[false]},"payment_status":{"type":"string","title":"Payment Status","description":"Stripe payment status: unpaid, paid, refunded.","examples":["paid"]},"platform_fee":{"type":"integer","title":"Platform Fee","description":"Platform fee in cents.","default":0,"examples":[290]},"refund_amount":{"type":"integer","title":"Refund Amount","description":"Amount refunded in cents.","default":0,"examples":[0]},"dispute_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dispute Status","description":"Stripe dispute status if disputed.","examples":["needs_response"]},"paid_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Paid At","description":"When payment was confirmed","examples":["2026-04-02T14:30:00Z"]},"fulfilled_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Fulfilled At","description":"When order was fulfilled","examples":["2026-04-02T15:00:00Z"]},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Time at which the order was created","examples":["2026-04-02T14:00:00Z"]}},"type":"object","required":["id","listing_id","buyer_email","amount","currency","status","has_deliverables","payment_status","created_at"],"title":"OrderSummary","description":"Lightweight order for list endpoints. Use GET /v1/orders/{id} for full detail."},"PingResponse":{"properties":{"object":{"type":"string","const":"ping","title":"Object","description":"Object type identifier.","default":"ping","examples":["ping"]},"status":{"type":"string","const":"ok","title":"Status","description":"API connectivity status.","default":"ok","examples":["ok"]}},"type":"object","title":"PingResponse"},"PlanListResponse":{"properties":{"object":{"type":"string","const":"list","title":"Object","description":"Object type identifier.","default":"list","examples":["list"]},"data":{"items":{"$ref":"#/components/schemas/PlanResponse"},"type":"array","title":"Data","description":"Array of plan objects."},"cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor","description":"Pass as `cursor` query param to fetch the next page.","examples":[null]},"has_more":{"type":"boolean","title":"Has More","description":"True if more results exist beyond this page.","default":false,"examples":[false]}},"type":"object","required":["data"],"title":"PlanListResponse"},"PlanResponse":{"properties":{"object":{"type":"string","const":"plan","title":"Object","description":"Object type identifier. Always `plan`.","default":"plan","examples":["plan"]},"id":{"type":"string","title":"Id","description":"Plan identifier","examples":["free"]},"name":{"type":"string","title":"Name","description":"Display name","examples":["Free"]},"tagline":{"type":"string","title":"Tagline","description":"Short description","examples":["Start instantly"]},"price_monthly":{"type":"integer","title":"Price Monthly","description":"Monthly price in USD","examples":[0]},"fee_rate":{"type":"string","title":"Fee Rate","description":"Platform fee rate as decimal string","examples":["0.10"]}},"type":"object","required":["id","name","tagline","price_monthly","fee_rate"],"title":"PlanResponse"},"ProblemDetail":{"properties":{"type":{"type":"string","title":"Type","description":"URI identifying the error type. Points to documentation.","examples":["https://docs.listbee.so/errors/invalid-request"]},"title":{"type":"string","title":"Title","description":"Short, stable, human-readable label for the error category.","examples":["Invalid Request"]},"status":{"type":"integer","title":"Status","description":"HTTP status code echoed in the body.","examples":[422]},"detail":{"type":"string","title":"Detail","description":"Specific explanation of what went wrong.","examples":["Price must be greater than 0"]},"code":{"type":"string","title":"Code","description":"Machine-readable error code for programmatic handling.","examples":["invalid_price"]},"param":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Param","description":"The request field that caused the error, if applicable.","examples":["price"]}},"type":"object","required":["type","title","status","detail","code"],"title":"ProblemDetail","description":"RFC 9457 Problem Details for HTTP APIs."},"ReviewInput":{"properties":{"name":{"type":"string","maxLength":100,"title":"Name","description":"Reviewer display name","examples":["Clara D."]},"rating":{"type":"number","title":"Rating","description":"Star rating (1–5). Values outside this range are clamped automatically","examples":[4.5]},"content":{"type":"string","maxLength":1000,"title":"Content","description":"Review body text","examples":["Excellent quality content."]}},"type":"object","required":["name","rating","content"],"title":"ReviewInput"},"SetDeliverablesRequest":{"properties":{"deliverables":{"items":{"$ref":"#/components/schemas/DeliverableInputRequest"},"type":"array","title":"Deliverables","description":"Array of deliverables. Max 3. Mixed types allowed.","examples":[[{"token":"file_7kQ2xY9mN3pR5tW1vB8a01","type":"file"}]]}},"type":"object","required":["deliverables"],"title":"SetDeliverablesRequest","description":"Replace all deliverables on a listing."},"StoreReadiness":{"properties":{"sellable":{"type":"boolean","title":"Sellable","description":"True when the store can sell. False means actions are needed.","examples":[false]},"actions":{"items":{"$ref":"#/components/schemas/Action"},"type":"array","title":"Actions","description":"What's needed to make this store sellable. Empty when sellable is true."},"next":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next","description":"Code of the highest-priority action. Agents execute this first.","examples":["connect_stripe"]}},"type":"object","required":["sellable"],"title":"StoreReadiness"},"StoreResponse":{"properties":{"object":{"type":"string","const":"store","title":"Object","description":"Object type identifier. Always `store`.","default":"store","examples":["store"]},"id":{"type":"string","title":"Id","description":"Unique store ID (st_ prefixed).","examples":["st_7kQ2xY9mN3pR5tW1vB8a"]},"display_name":{"type":"string","title":"Display Name","description":"Store display name shown to buyers.","examples":["Acme Agency"]},"slug":{"type":"string","title":"Slug","description":"URL-safe store slug used in checkout URLs.","examples":["acme-agency"]},"bio":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bio","description":"Store bio shown on product pages.","examples":["We make great things."]},"has_avatar":{"type":"boolean","title":"Has Avatar","description":"True if an avatar image has been uploaded.","default":false,"examples":[false]},"url":{"type":"string","title":"Url","description":"Public store URL.","examples":["https://buy.listbee.so/acme-agency"]},"api_key":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Api Key","description":"Raw API key, shown once at creation. Use as Bearer token.","examples":["lb_abc123"]},"readiness":{"$ref":"#/components/schemas/StoreReadiness","description":"Store readiness. Check `actions` for what's needed before you can sell."}},"type":"object","required":["id","display_name","slug","url","readiness"],"title":"StoreResponse"},"StoreUpdateRequest":{"properties":{"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name","description":"Store display name shown to buyers","examples":["Acme Agency"]},"bio":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bio","description":"Store bio shown on product pages","examples":["We make great things."]},"avatar":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Avatar","description":"File token from POST /v1/files with purpose=avatar. Upload an image first, then pass the file token here. Set to empty string to remove the avatar.","examples":["file_7kQ2xY9mN3pR5tW1vB8a01"]},"slug":{"anyOf":[{"type":"string","maxLength":60,"minLength":3,"pattern":"^[a-z0-9][a-z0-9-]*[a-z0-9]$"},{"type":"null"}],"title":"Slug","description":"URL-safe store slug used in checkout URLs. Must be 3-60 characters, start and end with alphanumeric, contain only lowercase letters, digits, and hyphens.","examples":["acme-agency"]}},"type":"object","title":"StoreUpdateRequest"},"StripeConnectSessionResponse":{"properties":{"object":{"type":"string","const":"stripe_connect_session","title":"Object","description":"Object type.","default":"stripe_connect_session","examples":["stripe_connect_session"]},"url":{"type":"string","title":"Url","description":"Stripe onboarding URL. Redirect the human here.","examples":["https://connect.stripe.com/setup/..."]},"expires_at":{"type":"string","format":"date-time","title":"Expires At","description":"When this URL expires.","examples":["2026-04-03T16:00:00Z"]}},"type":"object","required":["url","expires_at"],"title":"StripeConnectSessionResponse"},"UpdateAccountRequest":{"properties":{"ga_measurement_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ga Measurement Id","description":"Google Analytics 4 Measurement ID (G-XXXXXXXXXX). Set to null to remove","examples":["G-ABC123XYZ"]},"notify_orders":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Notify Orders","description":"Email me when I receive a new external order","examples":[true]}},"type":"object","title":"UpdateAccountRequest","description":"Partial update for account settings."},"UpdateListingRequest":{"properties":{"fulfillment_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fulfillment Url","description":"Callback URL — ListBee POSTs here on purchase. Set to null to remove. Updating this field rotates the fulfillment_secret.","examples":["https://my-agent.com/fulfill"]},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Product name","examples":["SEO Playbook 2026"]},"slug":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Slug","description":"URL slug for the product page (e.g. 'seo-playbook'). Only changeable in draft. Auto-slugified. On conflict, random suffix appended.","examples":["seo-playbook-2026"]},"price":{"anyOf":[{"type":"integer","exclusiveMinimum":0.0},{"type":"null"}],"title":"Price","description":"Price in cents (smallest currency unit). Examples: $5 = 500, $29 = 2900, $99.99 = 9999.","examples":[500,2900,9999]},"stock":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Stock","description":"Stock quantity. null = unlimited, 0 = out of stock, positive integer = sell N then stop.","examples":[100,0]},"checkout_schema":{"anyOf":[{"items":{"$ref":"#/components/schemas/CheckoutFieldInput"},"type":"array"},{"type":"null"}],"title":"Checkout Schema","description":"Custom fields to collect from the buyer at checkout. Replaces existing schema.","examples":[[{"key":"size","label":"Size","options":["S","M","L"],"type":"select"}]]},"description":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}],"title":"Description","description":"Product description shown on the product page. Improves buyer conversion. Plain text, max 5000 chars.","examples":["A comprehensive guide to modern SEO."]},"tagline":{"anyOf":[{"type":"string","maxLength":140},{"type":"null"}],"title":"Tagline","description":"Short tagline shown below the product name on the product page. Max 140 chars.","examples":["Updated for 2026"]},"highlights":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Highlights","description":"Bullet-point features shown as badges on the product page. Max 10 items. Each should be short (2-4 words).","examples":[["50+ pages","Free updates"]]},"cta":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}],"title":"Cta","description":"Buy button text on the product page. Defaults to 'Buy Now' if omitted. Max 60 chars.","examples":["Get Instant Access"]},"cover":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cover","description":"Cover image file token from POST /v1/files. Shown prominently on the product page. Recommended: 1200x630px.","examples":["file_tok_abc123"]},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Arbitrary key-value pairs forwarded in webhook event payloads. Use for your own tracking (campaign IDs, source tags).","examples":[{"source":"n8n"}]},"utm_source":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Utm Source","description":"UTM source tag for Google Analytics","examples":["google"]},"utm_medium":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Utm Medium","description":"UTM medium tag for Google Analytics","examples":["cpc"]},"utm_campaign":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Utm Campaign","description":"UTM campaign tag for Google Analytics","examples":["spring-sale"]},"compare_at_price":{"anyOf":[{"type":"integer","exclusiveMinimum":0.0},{"type":"null"}],"title":"Compare At Price","description":"Strikethrough price in cents (smallest currency unit). Must be greater than price. Examples: $39 = 3900.","examples":[3900,4900]},"badges":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Badges","description":"Short promotional badges shown on the product page (e.g. 'Best seller', 'Limited time'). Max 10 items.","examples":[["Best seller"]]},"cover_blur":{"anyOf":[{"$ref":"#/components/schemas/BlurMode"},{"type":"null"}],"description":"Cover image blur mode. 'true' always blurs, 'false' never blurs, 'auto' blurs when deliverable is an image file.","examples":["auto"]},"rating":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Rating","description":"Seller-provided aggregate star rating (1-5). Shown on the product page. Values outside range clamped.","examples":[4.8]},"rating_count":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Rating Count","description":"Seller-provided review or purchase count shown alongside the rating on the product page.","examples":[1243]},"reviews":{"anyOf":[{"items":{"$ref":"#/components/schemas/ReviewInput"},"type":"array"},{"type":"null"}],"title":"Reviews","description":"Featured review cards shown on the product page. Seller-provided, not buyer-submitted. Max 10."},"faqs":{"anyOf":[{"items":{"$ref":"#/components/schemas/FaqItemInput"},"type":"array"},{"type":"null"}],"title":"Faqs","description":"FAQ accordion shown on the product page. Answers common buyer questions. Max 10 items."}},"type":"object","title":"UpdateListingRequest","description":"Partial update — only provided fields are changed."},"UpdateWebhookRequest":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Display name","examples":["Order notifications"]},"url":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Url","description":"HTTPS endpoint URL","examples":["https://example.com/webhooks/listbee"]},"events":{"anyOf":[{"items":{"$ref":"#/components/schemas/WebhookEventType"},"type":"array"},{"type":"null"}],"title":"Events","description":"Replaces the current event subscriptions. Empty list subscribes to all events","examples":[["order.paid"]]},"enabled":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Enabled","description":"Set to `false` to pause delivery without deleting the endpoint","examples":[true]}},"type":"object","title":"UpdateWebhookRequest"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WebhookEventListResponse":{"properties":{"object":{"type":"string","const":"list","title":"Object","description":"Object type identifier. Always `list`.","default":"list","examples":["list"]},"data":{"items":{"$ref":"#/components/schemas/WebhookEventResponse"},"type":"array","title":"Data","description":"Array of webhook event objects."},"cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor","description":"Pass as `cursor` query param to fetch the next page","examples":["lst_7kQ2xY9mN3pR5tW1vB8a"]},"has_more":{"type":"boolean","title":"Has More","description":"True if more results exist beyond this page","default":false,"examples":[false]}},"type":"object","required":["data"],"title":"WebhookEventListResponse"},"WebhookEventResponse":{"properties":{"object":{"type":"string","const":"webhook_event","title":"Object","description":"Object type identifier. Always `webhook_event`.","default":"webhook_event","examples":["webhook_event"]},"id":{"type":"string","title":"Id","description":"Unique webhook event ID (evt_ prefixed).","examples":["evt_7kQ2xY9mN3pR5tW1"]},"event_type":{"$ref":"#/components/schemas/WebhookEventType","description":"The event type that triggered this delivery","examples":["order.paid"]},"status":{"type":"string","enum":["pending","delivered","failed"],"title":"Status","description":"Computed status: `delivered` if delivered_at is set, `failed` if attempts >= max_retries, otherwise `pending`.","examples":["delivered"]},"attempts":{"type":"integer","title":"Attempts","description":"Number of delivery attempts made","examples":[1]},"max_retries":{"type":"integer","title":"Max Retries","description":"Maximum delivery attempts before marking as failed","examples":[5]},"response_status":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Response Status","description":"HTTP status code from the last delivery attempt","examples":[200]},"last_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Error","description":"Error message from the last failed attempt","examples":[null]},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Time at which the event was created","examples":["2026-04-03T14:30:00Z"]},"delivered_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Delivered At","description":"Time at which the event was successfully delivered","examples":["2026-04-03T14:30:01Z"]},"failed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Failed At","description":"Time at which the event permanently failed (all retries exhausted)","examples":[null]},"next_retry_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Next Retry At","description":"Expected time for the next delivery retry","examples":[null]}},"type":"object","required":["id","event_type","status","attempts","max_retries","created_at"],"title":"WebhookEventResponse"},"WebhookEventType":{"type":"string","enum":["order.paid","order.fulfilled","order.refunded","order.disputed","order.dispute_closed","order.canceled","listing.created","listing.updated","listing.published","listing.out_of_stock","listing.deleted","customer.created"],"title":"WebhookEventType"},"WebhookListResponse":{"properties":{"object":{"type":"string","const":"list","title":"Object","description":"Object type identifier. Always `list`.","default":"list","examples":["list"]},"data":{"items":{"$ref":"#/components/schemas/WebhookResponse"},"type":"array","title":"Data","description":"Array of webhook objects."},"cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor","description":"Pass as `cursor` query param to fetch the next page.","examples":["wh_3mK8nP2qR5tW7xY1"]},"has_more":{"type":"boolean","title":"Has More","description":"True if more results exist beyond this page.","default":false,"examples":[false]}},"type":"object","required":["data"],"title":"WebhookListResponse"},"WebhookReadiness":{"properties":{"ready":{"type":"boolean","title":"Ready","description":"True when the webhook is active and receiving events.","examples":[true]},"actions":{"items":{"$ref":"#/components/schemas/Action"},"type":"array","title":"Actions","description":"Steps to fix the webhook."},"next":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next","description":"Highest-priority action code.","examples":[null]}},"type":"object","required":["ready"],"title":"WebhookReadiness"},"WebhookResponse":{"properties":{"object":{"type":"string","const":"webhook","title":"Object","description":"Object type identifier. Always `webhook`.","default":"webhook","examples":["webhook"]},"id":{"type":"string","title":"Id","description":"Unique webhook ID (wh_ prefixed).","examples":["wh_3mK8nP2qR5tW7xY1"]},"name":{"type":"string","title":"Name","description":"Display name","examples":["Order notifications"]},"url":{"type":"string","title":"Url","description":"Endpoint URL","examples":["https://example.com/webhooks/listbee"]},"secret":{"type":"string","title":"Secret","description":"HMAC-SHA256 signing secret. Use to verify webhook payload signatures. See docs for verification examples.","examples":["whsec_a1b2c3d4e5f6"]},"events":{"items":{"$ref":"#/components/schemas/WebhookEventType"},"type":"array","title":"Events","description":"Subscribed event types. Empty means all events","examples":[["order.paid"]]},"enabled":{"type":"boolean","title":"Enabled","description":"`false` when delivery is paused","examples":[true]},"disabled_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Disabled Reason","description":"Reason the webhook was disabled. `consecutive_failures` when auto-disabled after repeated delivery failures.","examples":[null]},"readiness":{"$ref":"#/components/schemas/WebhookReadiness","description":"Readiness status with actionable steps if the webhook needs attention."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Time at which the endpoint was created","examples":["2026-04-01T09:00:00Z"]}},"type":"object","required":["id","name","url","secret","events","enabled","readiness","created_at"],"title":"WebhookResponse"},"WebhookTestResponse":{"properties":{"object":{"type":"string","const":"webhook_test","title":"Object","description":"Object type identifier. Always `webhook_test`.","default":"webhook_test","examples":["webhook_test"]},"success":{"type":"boolean","title":"Success","description":"`true` if the endpoint returned a 2xx status code","examples":[true]},"status_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Status Code","description":"HTTP status code returned by the endpoint","examples":[200]},"response_body":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Response Body","description":"Response body from the endpoint, truncated to 2000 characters","examples":["OK"]},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error","description":"Error message if delivery failed entirely","examples":[null]}},"type":"object","required":["success"],"title":"WebhookTestResponse"}},"securitySchemes":{"HTTPBearer":{"type":"http","description":"API key (`lb_` prefix). Pass as: `Authorization: Bearer lb_...`","scheme":"bearer"}}},"tags":[{"name":"Account","description":"Account creation, authentication, profile, and readiness."},{"name":"Stripe","description":"Connect and manage Stripe payment configuration."},{"name":"API Keys","description":"Create, list, and revoke API keys."},{"name":"Files","description":"Upload files for deliverables, covers, and avatars."},{"name":"Listings","description":"Create, list, get, update, and delete listings."},{"name":"Orders","description":"View buyer orders and payment details."},{"name":"Customers","description":"View and search buyers who have completed orders."},{"name":"Webhooks","description":"Configure webhook endpoints for event notifications."}]}