Docs

Concepts

How versions, sync, ETags, retries, dry runs, pages, errors and limits work.

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 Deprecation and Sunset headers 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" }'
  • No If-Match gets 428 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"
  • A retry with the same key returns the first response, marked Idempotent-Replayed: true. It carries the ETag when 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" }] }'

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_…"

A cursor or filter value Shopbird can't read gets 422 invalid. Shopbird never ignores it.

Errors

Errors are RFC 9457 application/problem+json.

  • code is stable. Branch on it.
  • request_id identifies the request. Quote it to support.
  • errors[] lists each invalid field with its path.
  • 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 path is launch.
  • 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_full until 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.