List Artwork

In short

• POST /api-bulk-list turns 1 to 10 artwork links per call into Listing Hub drafts, exactly as if the seller had uploaded them: the same file checks, the same AI writing and the same mockups.
• Every draft needs a listing template, which only the seller can make. The artwork must match the template’s shape within 2%, every image is checked first, and if any fails nothing is created.
• Generating uses credits: 1 per draft, or 2 when the template has more than 6 mockup scenes. If the balance can’t cover the whole request you get a 402 and nothing is created. "generate": false makes drafts without writing them and uses no credits.
• The API cannot publish. The seller reviews the drafts in the Listing Hub and lists them: on Etsy they arrive as draft listings the seller prices and publishes; for Shopify the Listing Hub produces a CSV the seller imports.
• Follow progress with GET /api-bulk-list. Once listed, it shows the Etsy listing and the PrintShrimp product, which is what makes orders print by SKU.

Before you start

• An API key (see Get Access).
• A template. Read them with GET /api-get-templates (see Quickstart). Each has a ratio of A, 2:3, 3:4 or 4:5; your artwork must be the same shape. A template with print_files: false is mockup-only and never creates products. If there are no templates, the seller makes one in Bulk List → Templates; it holds the mockup scenes, pricing, shipping, Etsy settings, AI instructions and description footer that every draft copies.
• Credits. The seller’s plan sets a monthly allowance (the Free plan includes 5), and you can’t buy more; the response and any 402 tell you the cost and what’s available.
• Artwork on public HTTPS links: JPEG or PNG, up to 50 MB, in the template’s shape within 2%. Landscape files work and only use landscape mockup scenes; square files aren’t supported yet.
• A SKU plan. Each draft gets a SKU of up to 32 characters, defaulting to the file name, and it must be unused on the account. The SKU is how orders find the artwork later, so read SKUs before choosing them.

How a listing gets made

1. You send artwork links. Each becomes a draft card in the seller’s Listing Hub, with the template’s settings copied onto it.
2. Our AI writes the title, description and tags from the image, and the mockups render at the same time. This runs in a queue on our servers.
3. The seller reviews each draft, edits anything they like and marks it Ready.
4. The seller lists it. To Etsy, that creates a physical, made-to-order draft listing on Etsy with the template’s category, shipping, processing time, return policy and quantity; the seller then sets pricing on Etsy and publishes, because Etsy drafts aren’t visible until activated. For Shopify, “List to Shopify” downloads a CSV with one product per draft that the seller imports in Shopify admin → Products → Import.
5. Listing also creates the PrintShrimp product: print files for every size of the artwork’s shape, each named product-SKU-size, skipped if that SKU already exists or the seller has PrintShrimp Product switched off. From then on an order for that SKU prints with no clicks.

Steps 1 and 2 are yours. Steps 3 to 5 are the seller’s and cannot be done through the API.

Create drafts

curl -s -X POST "https://api.printshrimp.com/functions/v1/api-bulk-list" \
  -H "x-api-key: $PS_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "template_id": "3f6c1e2a-...",
    "tags": ["vintage botanical prints"],
    "instructions": { "title": "Start the title with the plant name." },
    "items": [
      { "image_url": "https://example.com/fern.png", "sku": "FERN-001", "name": "Fern Botanical Print", "keywords": "fern, green, vintage" },
      { "image_url": "https://example.com/oak-leaf.png" }
    ]
  }'

Per-item tags and instructions replace the request-level ones for that item. All of them apply on top of the template and survive regenerating. How the AI uses keywords, instructions and tags is on AI Listings.

Response 201:

{
  "success": true,
  "template": { "template_id": "3f6c1e2a-...", "name": "Botanical", "ratio": "A", "ratio_label": "A-series" },
  "generate": true,
  "credits": { "cost": 2, "available": 340 },
  "drafts": [
    {
      "index": 0,
      "status": "created",
      "draft_id": "9b1d7c40-...",
      "sku": "FERN-001",
      "name": "Fern Botanical Print",
      "image": { "url": "https://...", "width": 3508, "height": 4961, "ratio": "A", "ratio_label": "A-series", "orientation": "portrait" },
      "mockups": 6,
      "credit_cost": 1,
      "ai_status": "queued"
    }
  ]
}

• drafts[].status is created, failed (with an error) or skipped (the request ran out of time; send that image again).
• credits.cost is the whole request; credits is null when generate is false.
• If no draft at all could be created you get a 500 with success: false and "error": "No draft could be created. See drafts[].error."

When nothing is created

Every image is checked before anything is made. Three errors mean the whole request was refused:

// 400: an image failed the checks
{
  "error": "1 of 2 images failed validation. Nothing was created.",
  "errors": [
    { "index": 1, "image_url": "https://example.com/oak-leaf.png", "error": "Artwork is 2:3 (1024x1536px) but template \"Botanical\" is A-series. Use a 2:3 template or resize the file." }
  ]
}

// 402: not enough credits for the whole batch
{ "error": "Not enough credits: this request needs 12 and you have 4. Top up or send fewer images.", "credits": { "cost": 12, "available": 4 } }

// 409: a SKU is already on the account
{ "error": "1 SKU conflict(s). Nothing was created.", "errors": [ { "index": 0, "image_url": "https://example.com/fern.png", "error": "SKU \"FERN-001\" is already used by a product or draft on your account." } ] }

Fix the items named in errors and resend the whole batch. For a 402, send fewer images or wait for the seller to upgrade or for the allowance to reset; you can’t add credits.

Credits

• A draft costs 1 credit, or 2 when the template has 7 or more mockup scenes that fit the artwork’s shape and orientation. Mockups themselves are free; credits only pay for the AI writing.
• Credits are taken when a draft starts generating, monthly allowance first, then bought credits. A generation that fails, or is stuck for over 30 minutes, is refunded automatically; one still waiting to start after 24 hours is marked failed and was never charged.
• A generation that worked is not refunded, even if the draft is never used, and regenerating a draft costs credits again.
• The Free plan includes 5 credits a month, resetting on the 1st; paid plans include more (see printshrimp.com/pages/bulk-listing). Listing to Etsy, the mockups and the API work on every plan.

Follow progress

curl -s "https://api.printshrimp.com/functions/v1/api-bulk-list?draft_id=9b1d7c40-..." \
  -H "x-api-key: $PS_API_KEY"

draft_id reads one draft, draft_ids=a,b,c reads up to 50, and no parameter lists the newest 25 with page from 1.

{
  "success": true,
  "draft": {
    "draft_id": "9b1d7c40-...",
    "created_at": "2026-10-19T10:12:03.120+00:00",
    "sku": "FERN-001",
    "name": "Fern Botanical Print",
    "template_id": "3f6c1e2a-...",
    "image": { "url": "https://...", "thumbnail_url": "https://...", "width": 3508, "height": 4961, "ratio": "A", "ratio_label": "A-series" },
    "generation": {
      "status": "done",
      "error": null,
      "queued_at": "...", "started_at": "...", "completed_at": "...",
      "title": "Fern Botanical Print, Vintage Green Wall Art",
      "short_title": "Fern Botanical Print",
      "description": "...",
      "tags": ["botanical print", "fern wall art"]
    },
    "mockups": { "total": 6, "rendered": 6, "status": "done" },
    "etsy": { "status": null, "listing_id": null, "error": null, "listed_at": null },
    "product_id": null
  }
}

• generation.status: not_started, queued, processing, done, failed. Failed drafts are not charged.
• mockups.status: none, pending, rendering, done, failed.
• etsy.status stays null until the seller lists the draft from the Listing Hub, then queued, processing, done or failed, with listing_id once it exists. product_id fills in when the PrintShrimp product is created.
• The draft_ids form returns { "success": true, "drafts": [...], "missing": [...] }, listing any id not on the account; the list form adds page and total_drafts.
• Progress doesn’t include the Etsy attributes the AI fills in; the seller sees those in the Listing Hub.

Poll the batch with draft_ids rather than one draft at a time, and back off when nothing has changed. There are no webhooks.

Rules and limits

• Rate limits: 500 POST /api-bulk-list calls an hour, 2,000 progress reads an hour, per account.
• Don’t resend a batch after a timeout without checking first. With explicit SKUs a repeat is refused with 409, which is safe; without them the file-name SKUs get a number added and you create duplicate drafts. List the newest drafts with GET /api-bulk-list to see what was made.
• The Listing Hub holds at most 500 drafts (5,000 on the Max plan). Deleting a draft there only removes the card; an Etsy listing and PrintShrimp product already made from it stay.
• Drafts become products only for sizes of the artwork’s shape. An order for any other size needs a file added before it can be paid, which the seller does in My Print Files or you do with PUT /api-update-product.
• Etsy limits the calls we can make each day across all sellers. When that runs low, listings queue (“In line for Etsy”) and go out as Etsy allows, with nothing for you or the seller to do.
• The AI doesn’t check trademarks, brand names or Etsy’s banned words. The seller’s review before listing is the only check.

What this page doesn’t cover

• What the AI sees and how to steer it: AI Listings.
• How SKUs link listings, products and orders: SKUs.
• Saving products directly, without a listing: Save Products.
• What happens once the listing sells: Sell on Etsy.

Next

Previous: Quickstart · Next: AI Listings · Back to the hub: PrintShrimp for AI agents

Last updated 19 October 2026.