TikTok Shop campaigns lock SKUs: render variant clips first

Per TikTok Shop's campaign FAQ, you cannot add or remove variations or SKUs while a product is registered in a campaign. You have to withdraw the product first. So settle the variant list before you enroll, and render one clip per variant against that frozen list.

What the FAQ says

Freeze, then count

Make the SKU list the input to your production plan. Three colors by four sizes is 12 variants, and a clip per variant is 12 items. A bulk queue accepts 1 to 100 items, so one queue covers it. If a size is missing from the list at enrollment, the FAQ means you either live without it or withdraw the product and register it again.

Only render separate clips for variants that look different to a viewer. A size change rarely needs its own clip; a color change usually does. That keeps the batch small.

Queue one clip per variant

Bulk runs create a server-side queue of ordinary Format runs. concurrency is required (1 to 16), items holds 1 to 100 bodies, and each item names at least one of instruction, input, previous_run_id or attachments. Use a fresh Idempotency-Key per batch; replaying a spent key returns the old queue. The example uses the docs' placeholder URLs and handle.

curl -sS -X POST "https://api.sume.com/v1/formats/acme/product-promo/bulk-runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "concurrency": 3,
    "items": [
      { "instruction": "Clip for the red variant", "input": { "url": "https://example.com/red.jpg" }, "generation_spend_cap_usd": 5 },
      { "instruction": "Clip for the blue variant", "input": { "url": "https://example.com/blue.jpg" }, "generation_spend_cap_usd": 5 }
    ]
  }'

If the list changes anyway

If a variant must be added after enrollment, the FAQ route is to withdraw the product, change it and register again. Registering again likely means another application review, which the FAQ puts at 5 to 14 business days, so it is cheaper to leave a rarely sold variant out than to add it late.

On the production side, a change to the list means rendering again only for the affected variants. Keep the item index of each variant in your queue notes, so a re-run touches one item and not the whole batch.

Spend caps

The $5 per item above is an example cap, not a Sume price. With the cap on every item, a 12-item queue cannot spend more than 12 x $5 = $60 on generation, whatever the children do. Poll GET /v1/format-run-queues/{id} and read counts.failed before you call the batch done.