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
- 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 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
WebhookVerificationErrorwhen the check fails.
Receive webhooks lists every event and its data.