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>"] }]
}'
import { Shopbird } from "@shopbird/sdk";
const shopbird = new Shopbird({ token: process.env.SHOPBIRD_TOKEN });
const drop = await shopbird.drops.create(
{
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>"] }],
},
{ wait: true, idempotencyKey: "fall-drop-1" },
);
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_…"
const sync = await shopbird.sync.status();
// Or wait until checkout enforces a write:
await shopbird.sync.waitFor(drop.sync.generation);
{ "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_…"
await shopbird.drops.drawRaffle("<id>");
{ "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).