Docs

JavaScript SDK

Call the API and check webhook signatures from Node, Bun, Deno or Cloudflare Workers.

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

  1. Create a token in Settings > API access. See Authentication.
  2. Put it in the SHOPBIRD_TOKEN environment variable.
  3. Make a client. It reads SHOPBIRD_TOKEN when you don't pass token.
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 toleranceSec to change it.
  • During a secret rotation, pass both secrets as an array.
  • It throws WebhookVerificationError when the check fails.

Receive webhooks lists every event and its data.