API ReferenceListings

Update listing

Update listing fields. Slug can be changed while in draft status — input is slugified, conflicts get a random suffix. Returns updated listing with readiness.

Authentication

AuthorizationBearer

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

Path parameters

listing_idstringRequired

Listing ID (lst_ prefixed).

Request

This endpoint expects an object.
content_typeenum or nullOptional
Content type determines post-payment delivery behavior. Only changeable while in draft status. static: ListBee delivers pre-attached deliverables automatically on payment. generated: order enters PROCESSING state after payment — call POST /fulfill with the generated content to deliver it. webhook: order.paid webhook fires, your system handles delivery entirely. Switching away from static automatically removes any attached deliverables.
Allowed values:
namestring or nullOptional
Product name
slugstring or nullOptional<=80 characters

URL slug for the product page (e.g. ‘seo-playbook’). Only changeable in draft. Auto-slugified. On conflict, random suffix appended.

priceinteger or nullOptional
Price in cents (smallest currency unit). Examples: $5 = 500, $29 = 2900, $99.99 = 9999.
stockinteger or nullOptional>=0

Stock quantity. null = unlimited, 0 = out of stock, positive integer = sell N then stop.

checkout_schemalist of objects or nullOptional
Custom fields to collect from the buyer at checkout. Replaces existing schema.
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
utm_mediumstring or nullOptional<=100 characters
UTM medium tag for Google Analytics
utm_campaignstring or nullOptional<=100 characters
UTM campaign tag for Google Analytics
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_blurenum or nullOptional
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

Successful Response
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
404
Not Found Error
422
Unprocessable Entity Error