Docs

Python SDK

Call the API and check webhook signatures from Python 3.9 or later.

When you finish, your script lists your locks and changes one with the shopbird package.

The SDK has no dependencies. It needs Python 3.9 or later and includes type hints.

Install it

pip install shopbird

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 a token.
from shopbird import Shopbird

shopbird = Shopbird()

List and change locks

A list returns one page. Loop over it to read every page.

page = shopbird.locks.list(limit=10)
print(page.data, page.next_cursor)

for lock in shopbird.locks.list(enabled=True):
    print(lock["name"])

A write takes wait and dry_run. They match ?wait=true and ?dry_run=true in Concepts.

lock = shopbird.locks.create(
    {
        "name": "Moon ring early access",
        "targets": [{"type": "product", "resource_id": "gid://shopify/Product/123"}],
        "audience_ids": ["<audience id>"],
    },
    wait=True,
)
print(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.

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.

shopbird.audiences.edit("<audience id>", lambda audience: {"tags": audience.get("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 idempotency_key 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 max_retries to change it.
Pagination Looping over a page follows next_cursor.
Sync shopbird.sync.wait_for(generation) polls GET /api/v1/sync until checkout enforces that generation.
Timeouts Each attempt stops after 60 seconds. Set timeout to change it.

Handle errors

An error answer raises shopbird.ApiError. Branch on code, which matches Errors.

from shopbird import ApiError

try:
    shopbird.drops.create({"name": "Fall drop", "launch_at": "2026-11-20T17:00:00Z"})
except ApiError as error:
    if error.code != "plan_limit":
        raise
    print(error.tier, error.upgrade_url)
Attribute Value
status The HTTP status
code The stable error code
request_id Quote it to support
errors Each invalid field, for 422 invalid
required_scope The missing scope, for 403 insufficient_scope
retry_after Seconds from Retry-After, for 429 and 503

A request with no answer raises shopbird.ConnectionError.

Check webhook signatures

verify_webhook checks the signature and the timestamp, then returns the parsed event. Pass the raw body, not parsed JSON.

import os
from flask import Flask, request
from shopbird import WebhookVerificationError, verify_webhook

app = Flask(__name__)

@app.post("/webhooks/shopbird")
def shopbird_webhook():
    try:
        delivery = verify_webhook(request.get_data(), request.headers, os.environ["SHOPBIRD_WEBHOOK_SECRET"])
    except WebhookVerificationError:
        return "", 400
    # A retry repeats delivery.id. Skip IDs you have handled.
    if delivery.event["type"] == "lock.updated":
        print(delivery.event["data"]["lock_id"])
    return "", 204
  • It accepts a timestamp up to 5 minutes from now. Set tolerance (seconds) to change it.
  • During a secret rotation, pass both secrets as a list.
  • It raises WebhookVerificationError when the check fails.

Receive webhooks lists every event and its data.