Cancel one SKU in a running Sume bulk queue: use the run endpoint

A Sume bulk queue has no public cancel-queue or list-queues endpoint, so stopping one SKU means cancelling its child run: POST /v1/format-runs/{run_id}/cancel, with the formats:write scope. The call is idempotent. The response is the current receipt and a cancel_effect field: canceled if this call stopped a run in progress, no_op if the run had already finished. You pay for the generation the run completed before the cancel, and usage shows it. See Runs and results.

Use this when a price, a product or a legal line is wrong in a SKU that has already started.

Find the run id

Poll the queue's status_url, look up the item by its index, and read its run_id. If the item is still queued, run_id is null, and the docs describe no way to cancel an item that has not started, so plan for it: either wait until it starts, or keep the bad rows out of the queue in the first place by checking the sheet before you submit.

The call

Send the cancel with your key. The queue then records that item as canceled with error.code format_run_canceled, and the freed slot lets the next queued item start.

curl -sS -X POST "https://api.sume.com/v1/format-runs/$RUN_ID/cancel" \
  -H "Authorization: Bearer $SUME_API_KEY" | jq '{status: .data.status, effect: .data.cancel_effect}'

Cancel and webhooks

A canceled run never delivers a webhook. If your integration is webhook-only, a cancel produces silence, so record the cancel on your side when you send it and treat the cancel response as the confirmation. Also, canceled counts in counts.canceled, and an all-terminal queue is completed even when some items were canceled, so use the counts, not the status, to see what actually shipped.

After a cancel, re-queue the corrected SKU in a new, small queue under a new key. Do not reuse the old key. Keep a log of what was canceled, why, and what the run had already cost, which usage on the receipt reports.

• No queue-level cancel; cancel children.
• queued items have no run id yet.
• You pay for generation completed before cancel.

A decision rule for sale week

Cancel a running child only when letting it finish costs more than stopping it. A run you cancel at once saves most of its generation spend; a run you cancel near the end saves little, and you still pay for what it completed. Read the run's events_url timeline if you need to see which phase it is in before deciding.

If a whole batch is wrong, for example a price sheet with the wrong discount, you have two levers. Cancel the running children one by one, which is a short loop over run_id values from the queue receipt. And do not start the next batch from the same sheet until it is fixed. The queued items will still start as slots free up, so cancel the children as they appear, or let them finish and discard the output.

Because cancel is idempotent, a loop that cancels every run_id it sees is safe to run twice. The second pass returns no_op for runs that already stopped or finished. Record the cancel time and reason for each, and keep the receipt usage so finance can match the bill to the batch.