When you finish, your script lists your locks and changes one with the @shopbird/sdk package.
The SDK has no dependencies. It needs Node 20 or later, Bun, Deno or Cloudflare Workers. It includes TypeScript types for every route.
Install it
npm install @shopbird/sdk
Make a client
- Create a token in Settings > API access. See Authentication.
- Put it in the
SHOPBIRD_TOKENenvironment variable. - Make a client. It reads
SHOPBIRD_TOKENwhen you don't passtoken.
import { Shopbird } from "@shopbird/sdk";
const shopbird = new Shopbird({ token: process.env.SHOPBIRD_TOKEN });
List and change locks
await a list for one page. Use for await to read every page.
const page = await shopbird.locks.list({ limit: 10 });
console.log(page.data, page.next_cursor);
for await (const lock of shopbird.locks.list({ enabled: true })) {
console.log(lock.name);
}
A write takes wait and dryRun. They match ?wait=true and ?dry_run=true in Concepts.
const lock = await shopbird.locks.create(
{
name: "Moon ring early access",
targets: [{ type: "product", resource_id: "gid://shopify/Product/123" }],
audience_ids: ["<audience id>"],
},
{ wait: true },
);
console.log(lock.sync.status); // "synced": checkout enforces the lock now
update and delete on locks, audiences and drops need the version from your last read. The SDK sends it as If-Match.
await shopbird.locks.update(lock.id, { name: "VIP only" }, { version: lock.version });
edit reads the resource, applies your change and writes it. After a 412 conflict it reads again and retries, 3 times at most.
await shopbird.audiences.edit("<audience id>", (audience) => ({ tags: [...(audience.tags ?? []), "vip"] }));
What the SDK does for you
| Rule from Concepts | What the SDK does |
|---|---|
| Idempotency keys | Sends a new Idempotency-Key on every write, and the same key on its retries. Pass idempotencyKey to set your own. |
| Retries | Retries 429, 503, other 5xx answers and network failures 2 times. It waits for Retry-After up to 60 seconds. Set maxRetries to change it. |
| Pagination | for await follows next_cursor. toArray() returns every item. |
| Sync | shopbird.sync.waitFor(generation) polls GET /api/v1/sync until checkout enforces that generation. |
| Timeouts | Each attempt stops after 60 seconds. Set timeoutMs to change it. |
Handle errors
An error answer throws ShopbirdApiError. Branch on code, which matches Errors.
import { ShopbirdApiError } from "@shopbird/sdk";
try {
await shopbird.drops.create({ name: "Fall drop", launch_at: "2026-11-20T17:00:00Z" });
} catch (error) {
if (error instanceof ShopbirdApiError && error.code === "plan_limit") {
console.log(error.tier, error.upgradeUrl);
} else {
throw error;
}
}
| Property | Value |
|---|---|
status |
The HTTP status |
code |
The stable error code |
requestId |
Quote it to support |
errors |
Each invalid field, for 422 invalid |
requiredScope |
The missing scope, for 403 insufficient_scope |
retryAfter |
Seconds from Retry-After, for 429 and 503 |
A request with no answer throws ShopbirdConnectionError.
Check webhook signatures
verifyWebhook checks the signature and the timestamp, then returns the parsed event. Pass the raw body, not parsed JSON.
import express from "express";
import { verifyWebhook } from "@shopbird/sdk";
const app = express();
app.post("/webhooks/shopbird", express.raw({ type: "application/json" }), async (req, res) => {
let delivery;
try {
delivery = await verifyWebhook(req.body, req.headers, process.env.SHOPBIRD_WEBHOOK_SECRET);
} catch {
return res.sendStatus(400);
}
// A retry repeats delivery.id. Skip IDs you have handled.
if (delivery.event.type === "lock.updated") console.log(delivery.event.data.lock_id);
res.sendStatus(204);
});
- It accepts a timestamp up to 5 minutes from now. Set
toleranceSecto change it. - During a secret rotation, pass both secrets as an array.
- It throws
WebhookVerificationErrorwhen the check fails.
Receive webhooks lists every event and its data.