Docs

Run a drop by API

Create a raffle drop, wait for its locks, follow its stages and draw the winners.

When you finish, you have a raffle drop with early access, and its winners are drawn. The token needs drops:read and drops:write.

Create the drop

Times are UTC. Add ?wait=true so the response waits until the drop's locks are live.

curl -X POST "https://app.shopbird.app/api/v1/drops?wait=true" \
  -H "Authorization: Bearer sb_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: fall-drop-1" \
  -d '{
    "name": "Fall drop",
    "launch_at": "2026-11-20T17:00:00Z",
    "sell_mode": "raffle",
    "raffle_winners": 50,
    "raffle_notify": "csv",
    "sources": [{ "kind": "products", "products": [{ "id": "gid://shopify/Product/1" }] }],
    "windows": [{ "hours_before": 24, "audience_ids": ["<audience id>"] }]
  }'

You get 201, the drop and its ETag:

{
  "id": "…",
  "name": "Fall drop",
  "launch_at": "2026-11-20T17:00:00.000Z",
  "sell_mode": "raffle",
  "raffle_winners": 50,
  "raffle_claim_hours": 48,
  "version": 1,
  "sync": { "generation": 43, "status": "synced" }
}
Limit Value
Sources 20 per drop, 250 products each
Early access windows 10 per drop, 1 to 720 hours before launch
raffle_claim_hours 1 to 720. Default 48.
Plan Free can't run raffles. See Plan limits.

Wait for sync

If sync.status is "pending", the drop is saved and Shopbird keeps rebuilding its locks. Check the sync:

curl https://app.shopbird.app/api/v1/sync \
  -H "Authorization: Bearer sb_live_…"
{ "generation": 43, "synced_generation": 43, "status": "synced", "last_error": null }

The drop is live once synced_generation is at least the drop's sync.generation.

Read its stage

A drop moves through stages by its times. GET /api/v1/drops/{id} returns those times.

Stage Starts at
setup Creation
teaser teaser_at
preview preview_at
early launch_at minus the longest window's hours_before
public launch_at
ended ends_at

Stages with no time are skipped. The drop.stage_changed webhook tells you each move:

{ "type": "drop.stage_changed", "data": { "drop_id": "…", "from": "early", "to": "public" } }

After launch, the launch time, early access and sell mode can't change (409 drop_started).

Draw the raffle

Entries close at launch. Draw after that.

curl -X POST https://app.shopbird.app/api/v1/drops/<id>/raffle/draw \
  -H "Authorization: Bearer sb_live_…"
{ "drawing": true }
Answer Means
202 with drawing: true The draw started. raffle.drawn fires when it ends.
200 with already_drawn: true It was drawn before. Shopbird never draws twice.
409 raffle_not_closed Entries are still open.

GET /api/v1/drops/{id}/raffle-entries lists entries with customer IDs and won. After the draw, raffle settings can't change (409 raffle_drawn).