API ReferenceListings

Create listing

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.

Authentication

AuthorizationBearer

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

Request

This endpoint expects an object.
namestringRequired
Product name shown on the product page
content_typeenumRequired

Content type determines post-payment behavior. static: ListBee delivers pre-attached content. generated: agent creates content after payment, ListBee delivers. webhook: ListBee fires order.paid, seller’s system takes over.

Allowed values:
priceintegerRequired
Price in cents (smallest currency unit). Examples: $5 = 500, $29 = 2900, $99.99 = 9999.
checkout_schemalist of objects or nullOptional

Custom fields to collect from the buyer at checkout (e.g. size, color, shipping address). Email is always collected.

stockinteger or nullOptional>=0

Stock quantity. null = unlimited (default), 0 = out of stock, positive integer = sell N then stop. Auto-decrements on each order.

descriptionstring or nullOptional<=5000 characters
Product description shown on the product page. Improves buyer conversion. Plain text, max 5000 chars.
taglinestring or nullOptional<=140 characters
Short tagline shown below the product name on the product page. Max 140 chars.
highlightslist of strings or nullOptional

Bullet-point features shown as badges on the product page. Max 10 items. Each should be short (2-4 words).

ctastring or nullOptional<=60 characters
Buy button text on the product page. Defaults to 'Buy Now' if omitted. Max 60 chars.
coverstring or nullOptional

Cover image file token from POST /v1/files. Shown prominently on the product page. Recommended: 1200x630px.

metadatamap from strings to any or nullOptional

Arbitrary key-value pairs forwarded in webhook event payloads. Use for your own tracking (campaign IDs, source tags).

utm_sourcestring or nullOptional<=100 characters
UTM source tag for Google Analytics. Defaults to 'listbee' if omitted
utm_mediumstring or nullOptional<=100 characters

UTM medium tag for Google Analytics. Defaults to ‘product_page’ if omitted

utm_campaignstring or nullOptional<=100 characters
UTM campaign tag for Google Analytics. Defaults to the listing slug if omitted
compare_at_priceinteger or nullOptional

Strikethrough price in cents (smallest currency unit). Must be greater than price. Examples: $39 = 3900.

badgeslist of strings or nullOptional

Short promotional badges shown on the product page (e.g. ‘Best seller’, ‘Limited time’). Max 10 items.

cover_blurenumOptional
Cover image blur mode. 'true' always blurs, 'false' never blurs, 'auto' blurs when deliverable is an image file.
Allowed values:
ratingdouble or nullOptional

Seller-provided aggregate star rating (1-5). Shown on the product page. Values outside range clamped.

rating_countinteger or nullOptional>=0

Seller-provided review or purchase count shown alongside the rating on the product page.

reviewslist of objects or nullOptional

Featured review cards shown on the product page. Seller-provided, not buyer-submitted. Max 10.

faqslist of objects or nullOptional
FAQ accordion shown on the product page. Answers common buyer questions. Max 10 items.

Response

Listing created and published.
idstring
Unique identifier
slugstring
URL slug for the product page
namestring
Product name shown on the product page
highlightslist of strings

Bullet-point features shown as badges on the product page.

priceinteger
Price in cents (smallest currency unit). Examples: $5 = 500, $29 = 2900, $99.99 = 9999.
content_typeenum

Content type: static (pre-attached content, ListBee delivers), generated (content created after payment, ListBee delivers), webhook (paid order handed to seller’s system).

Allowed values:
has_coverboolean

True if a cover image exists (uploaded or generated)

statusenum
Current listing status
Allowed values:
readinessobject

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_atdatetime
Time at which the listing was created
object"listing"

Object type identifier. Always listing.

descriptionstring or null
Product description shown on the product page. Plain text.
taglinestring or null
Short tagline shown below the product name on the product page.
ctastring or null
Buy button text on the product page. Defaults to 'Buy Now' if omitted.
deliverableslist of objects

Deliverables pre-attached to this listing. Required for static content_type — ListBee delivers these to buyers on payment. Empty for generated (content created per-order) and webhook (seller handles delivery) listings.

checkout_schemalist of objects or null
Custom fields collected from the buyer at checkout
compare_at_priceinteger or null
Strikethrough price in smallest currency unit
badgeslist of strings

Short promotional badges shown on the product page (e.g. ‘Best seller’, ‘Limited time’).

cover_blurenum
Cover image blur mode. 'true' always blurs, 'false' never blurs, 'auto' blurs when deliverable is an image file.
Allowed values:
ratingdouble or null

Seller-provided aggregate star rating (1-5). Shown on the product page.

rating_countinteger or null

Seller-provided review or purchase count shown alongside the rating on the product page.

reviewslist of objects

Featured review cards shown on the product page. Seller-provided, not buyer-submitted.

faqslist of objects
FAQ accordion shown on the product page. Answers common buyer questions.
metadatamap from strings to any or null

Arbitrary key-value pairs forwarded in webhook event payloads. Set at creation or update.

utm_sourcestring or null
UTM source tag for Google Analytics
utm_mediumstring or null
UTM medium tag for Google Analytics
utm_campaignstring or null
UTM campaign tag for Google Analytics
stockinteger or null

Stock quantity. null = unlimited, 0 = out of stock. Auto-decrements on each order.

urlstring or null

Full product page URL — share this with buyers

embed_urlstring or null

Embeddable product page URL — use in iframes. Renders minimal version without header/footer.

Errors

401
Unauthorized Error
422
Unprocessable Entity Error
429
Too Many Requests Error