SHshopfront
Listings

Generate a marketplace-ready listing

Generate a complete listing from product images using AI. Returns core listing data, marketplace mappings (eBay, Depop, Grailed, Shopify), pricing recommendations, and image URLs.

Modes:

  • sync (default for API tokens): Returns the generated listing in the HTTP response. No enrichment — fast path for API consumers.
  • async (default for JWT/frontend): Returns { jobId, displayId } immediately. Listing is persisted and enriched in the background.

The mode is auto-detected from your auth type, or you can set it explicitly via mode.

Idempotency (sync mode): Pass an Idempotency-Key header to safely retry requests. If a response was already generated for this key within the last 24 hours, the cached response is returned.

Usage limits: This endpoint checks your organisation's monthly allowance and billing status before generation. Returns 402 if your monthly limit has been reached or billing is blocked; read the returned error.

post/v1/listings/generate

Request

  • Base URL
    https://api.shopfront.app
  • Auth
    HTTP bearer

Headers

Idempotency-Keystring

Idempotency key for safe retries (sync mode only). Cached results are returned for 24 hours.

Request body

requestIdstring uuid required

Client-generated UUID for request tracking

imageUrlsstring[]

Image URLs to download. The first image is used as the hero. Supports JPEG, PNG, WebP, AVIF, GIF, TIFF, HEIC and HEIF; other formats are refused with 400 UNSUPPORTED_IMAGE_FORMAT. Non-JPEG images are converted to JPEG.

imagesstring[]

Images as base64-encoded strings. The first image is used as the hero. Each string should be raw base64 data (no data:image/...;base64, prefix needed). Use this if you already have image data in memory. For most cases, imageUrls is simpler. Supports JPEG, PNG, WebP, AVIF, GIF, TIFF, HEIC and HEIF; other formats are refused with 400 UNSUPPORTED_IMAGE_FORMAT. Non-JPEG images are converted to JPEG.

channelsstring[]

Marketplace channels to generate mappings for. Empty = core listing only.

mode'sync' | 'async'

Response mode. Defaults to sync for API token callers, async for JWT/frontend callers.

  • sync: Returns full listing in the HTTP response body (no enrichment)
  • async: Returns { jobId, displayId }, runs persist + enrichment in background
persistboolean

Whether to save the listing to the database. Defaults to false in sync mode, true in async mode.

applyChannelTemplatesboolean

Apply per-channel templates to generate marketplace-specific titles and descriptions. Uses the templates configured in Settings → Marketplaces → Templates for each channel. Set to false to skip and use the core listing content for all channels.

templateIdstring uuid nullable

Base template ID. Null explicitly selects No template. When omitted, the visible organisation general default applies, if one exists.

enableBackgroundRemovalboolean

Remove the background from the hero image and replace with a clean white backdrop. Processing duration varies.

enableImageEnhancementboolean

Apply AI image enhancement to the hero image (lighting adjustments, preservation of product colours and details). Processing duration varies.

aiNotesstring

Additional context for the AI (e.g., "Small scuff on left toe, purchased 2023")

ebayMarketplace'EBAY_US' | 'EBAY_AU' | 'EBAY_GB' | 'EBAY_DE' | 'EBAY_CA' | 'EBAY_FR'

eBay marketplace for category mapping

targetCurrencystring

Currency for pricing results (ISO 4217 three-letter code)

Example request

{
  "imageUrls": [
    "https://i.ebayimg.com/images/g/abc/front.jpg",
    "https://i.ebayimg.com/images/g/abc/back.jpg",
    "https://i.ebayimg.com/images/g/abc/tag.jpg"
  ],
  "images": [
    "/9j/4AAQSkZJRg...",
    "/9j/4AAQSkZJRg..."
  ]
}

Response

Sync mode — full listing returned

Example response

{
  "data": {
    "listing": {
      "conditionNotes": "Minor surface wear; fully functional.",
      "packageWeight": 0.45,
      "packageWeightConfidence": 0.7,
      "packageDimensions": {
        "height": 15,
        "width": 25,
        "length": 35
      },
      "packageDimensionsConfidence": 0.7,
      "identificationConfidence": 0.95
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.