---
title: "Generate listings from multiple images (bulk)"
method: POST
path: "/v1/listings/bulk"
tags: ["Listings"]
---

# Generate listings from multiple images (bulk)

`POST /v1/listings/bulk`

## Request

- Base URL: `https://api.shopfront.app`
- URL: `https://api.shopfront.app/v1/listings/bulk`
- Auth: HTTP bearer

Submit multiple product images for automatic grouping and parallel listing generation.
The AI identifies product boundaries, groups images by product, then generates
a complete listing for each product in parallel.

**How it works:**
1. Submit image URLs (up to 50 images)
2. AI groups images into products
3. Each product is sent through listing generation
4. Poll `GET /v1/jobs/{jobId}` for results

For larger batches (up to 1000 images), use the presigned S3 upload flow via
`POST /v1/listings/bulk/presign` followed by `POST /v1/listings/bulk`.

## Request body

- object
  - `batchId` string, uuid, required: Client-generated UUID for batch tracking
  - `imageUrls` string[]: Image URLs to process. The AI will group these into products automatically. Limited to 50 images — use `POST /v1/listings/bulk/presign` for larger batches.
  - `imageS3Keys` string[]: S3 keys from presigned upload (for batches >50 images). Get keys from `POST /v1/listings/bulk/presign`.
  - `channels` string[], required: Marketplace channels to generate mappings for
  - `aiNotes` string: Additional context for the AI
  - `ebayMarketplace` 'EBAY_US' | 'EBAY_AU' | 'EBAY_GB' | 'EBAY_DE' | 'EBAY_CA' | 'EBAY_FR'
  - `templateId` string, uuid: Template ID for generating marketplace-specific content. Falls back to the organisation's default template if not provided.
  - `enableBackgroundRemoval` boolean: Remove background from each product's hero image
  - `enableImageEnhancement` boolean: Apply AI image enhancement to each product's hero image
  - `workflow` union: Controls which workflow the listings are saved to. - `"new"` (default): creates a fresh workflow for this batch - `"auto"`: adds to a rolling daily "API Listings" workflow - `1162` (number): adds to workflow #1162 (the number from the dashboard URL)
    - 'auto' | 'new'
    - integer

## Response `200`

Batch accepted — grouping and generation started

- object
  - `data` object
    - `totalProducts` integer: Number of products identified
    - `groups` unknown[]: Product groups with image assignments
      - unknown
  - `meta` object
    - `broadcastChannel` string
    - `displayId` integer: Workflow number in the dashboard. Poll `GET /v1/jobs/{jobId}` for results, where jobId is the workflow's UUID (available in the ProcessingJob after creation).

## Other responses

- `400`: Invalid request
- `401`: Unauthorized - missing or invalid token
- `429`: Rate limit exceeded

---

[API](https://skmtc.dev/shopfront/apis/shopfront-public-api.md) - [All operations](https://skmtc.dev/shopfront/apis/shopfront-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/shopfront/apis/shopfront-public-api/revisions/4dbfb90550d4?raw)