This page explains the rules every route follows. Read it once before you write a script.
Versions
The API lives under /api/v1.
- Within v1, changes only add things: new routes, new optional fields, new error codes.
- A change that could break a caller ships as
/api/v2. - v1 then answers with
DeprecationandSunsetheaders at least 6 months before it stops.
The OpenAPI document for v1 needs no token:
curl https://app.shopbird.app/api/v1/openapi.json
The changelog lists every change.
Changes and checkout
Shopbird saves a write at once. Checkout enforces it after the sync to Shopify, usually within seconds.
A write that changes checkout returns its sync:
"sync": { "generation": 42, "status": "pending" }
| To | Do this |
|---|---|
| Wait | Add ?wait=true. The response waits up to 20 seconds. |
| Check later | GET /api/v1/sync. Live once synced_generation is at least your generation. |
| Sync now | POST /api/v1/sync (Locksmith's "install"). |
| Skip polling | Listen for sync.completed. |
With ?wait=true, status is "synced", "pending" (took longer) or "failed" (Shopify refused it for now). The write is saved in all three cases. Shopbird retries on its own, and rebuilds a saved drop's stage locks.
Hand out codes after their write reports "synced". Then they work at once.
Edit safely with ETags
Reads return an ETag, such as "v3". Send it back as If-Match on PATCH and DELETE.
curl -X PATCH https://app.shopbird.app/api/v1/locks/<id> \
-H "Authorization: Bearer sb_live_…" \
-H 'If-Match: "v3"' \
-H "Content-Type: application/json" \
-d '{ "name": "VIP only" }'
import { Shopbird } from "@shopbird/sdk";
const shopbird = new Shopbird({ token: process.env.SHOPBIRD_TOKEN });
// The SDK sends version 3 as If-Match: "v3".
await shopbird.locks.update("<id>", { name: "VIP only" }, { version: 3 });
- No
If-Matchgets428 if_match_required. - A resource someone changed since your read gets
412 conflict. Read it again and retry. - A lock a drop manages gets
409 managed_by_drop. Edit the drop instead.
Retry safely with Idempotency-Key
Send an Idempotency-Key header with any unique string on every write.
curl -X POST https://app.shopbird.app/api/v1/sync \
-H "Authorization: Bearer sb_live_…" \
-H "Idempotency-Key: 6f1c2a90-sync"
// The SDK sends a new key on every write. Pass your own to reuse one:
await shopbird.sync.start({ idempotencyKey: "6f1c2a90-sync" });
- A retry with the same key returns the first response, marked
Idempotent-Replayed: true. It carries theETagwhen the body is a versioned resource. - A failed first attempt releases the key. The retry runs the write again.
- A retry that arrives while the first is still running gets
409 idempotency_key_in_flight. Wait a moment and retry. - Keys last 24 hours. Reusing a key with a different body returns
422 idempotency_key_reused.
The replayed body shows the original sync.status. Check GET /api/v1/sync for the current state.
Try a write with dry_run
Add ?dry_run=true to any write. Shopbird checks it and answers as if it ran. Nothing is saved, synced or sent.
curl -X POST "https://app.shopbird.app/api/v1/drops?dry_run=true" \
-H "Authorization: Bearer sb_live_…" \
-H "Content-Type: application/json" \
-d '{ "name": "Fall drop", "launch_at": "2026-11-20T17:00:00Z", "sources": [{ "kind": "new", "title": "Fall drop" }] }'
const preview = await shopbird.drops.create(
{ name: "Fall drop", launch_at: "2026-11-20T17:00:00Z", sources: [{ kind: "new", title: "Fall drop" }] },
{ dryRun: true },
);
A drop that would create a collection lists it under would_create:
"would_create": [{ "collection": "Fall drop" }]
Lists and pagination
Lists are newest first.
| Parameter | Value |
|---|---|
limit |
1 to 100. Default 50. |
cursor |
next_cursor from the previous page. It is null on the last page. |
curl "https://app.shopbird.app/api/v1/locks?limit=100&cursor=<next_cursor>" \
-H "Authorization: Bearer sb_live_…"
const page = await shopbird.locks.list({ limit: 100, cursor: "<next_cursor>" });
// Or read every page:
for await (const lock of shopbird.locks.list({ limit: 100 })) console.log(lock.name);
A cursor or filter value Shopbird can't read gets 422 invalid. Shopbird never ignores it.
Errors
Errors are RFC 9457 application/problem+json.
codeis stable. Branch on it.request_ididentifies the request. Quote it to support.errors[]lists each invalid field with itspath.- A request body over 1 MB gets
413 payload_too_large.
{
"status": 422,
"code": "invalid",
"detail": "…",
"request_id": "…",
"errors": [{ "path": "targets[0].resource_id", "code": "…", "message": "…" }]
}
Errors lists every code.
Rate limits
Each token gets bursts of 40 requests. The burst refills at 120 requests a minute.
| Header | Meaning |
|---|---|
X-RateLimit-Limit |
The burst: 40 |
X-RateLimit-Remaining |
Requests you can send now |
X-RateLimit-Reset |
Seconds until the burst is full again |
HTTP/1.1 429 Too Many Requests
Retry-After: 3
Over the limit, you get 429 with Retry-After. When Shopify is busy, Shopbird answers 503 with Retry-After. Retry after that many seconds.
Plan limits
The API needs a paid plan or the store's 14-day trial. On Free, every request gets 402 plan_limit, reads too, so a script stops cleanly.
These writes also get 402 when the plan doesn't cover them:
- Locking more pages than the plan allows.
- A drop launching in a calendar month (UTC) that already has the plan's monthly launches. This covers new drops and drops moved into that month. The error's
pathislaunch. - On Free: a whole-store lock, a raffle, made to order, early access windows or a second live drop.
{ "status": 402, "code": "plan_limit", "tier": "…", "upgrade_url": "…" }
upgrade_url is Shopify's plan page for the store. tier names the smallest plan that covers the change. A plan change never unlocks anything.
Codes and revocation
POST /api/v1/audiences/{id}/codes adds up to 100 codes per request. Send your own (8 to 32 letters, numbers or dashes) or generate them:
{ "generate": 50 }
POST /api/v1/audiences/{id}/codes/revoke revokes codes by ID or by code. Both routes are all or nothing.
- Checkout refuses a revoked code's tokens until they expire, after about 10 days.
- Checkout tracks about 250 recently revoked codes that shoppers redeemed. Codes nobody redeemed don't count.
- When that list is full, a write that would grow it gets
422 revocation_list_fulluntil older entries expire.
Two writes grow the list:
- Revoking codes.
- Linking an audience with recently revoked codes to more locks, by a lock save or a drop's early access windows.