When you finish, your bot or CRM tags a customer, and checkout lets them buy what your locks hold.
Make a tag audience
- In Shopbird, create an audience with the condition Customer tag, for example
discord-gold. - Link the audience to your locks.
Tag the customer
When someone qualifies, add the tag. The token needs customers:write. Use the numeric customer ID or a Customer GID.
curl -X POST https://app.shopbird.app/api/v1/customers/<customer id>/tags \
-H "Authorization: Bearer sb_live_…" \
-H "Content-Type: application/json" \
-d '{ "tags": ["discord-gold"] }'
import { Shopbird } from "@shopbird/sdk";
const shopbird = new Shopbird({ token: process.env.SHOPBIRD_TOKEN });
await shopbird.customers.addTags("<customer id>", ["discord-gold"]);
{ "customer_id": "gid://shopify/Customer/<customer id>", "tags": ["discord-gold"], "added": true }
Send the same request with DELETE to remove the tag.
| Rule | Value |
|---|---|
| When it works | At checkout at once. No sync. |
| Tags per request | 1 to 25 |
| Allowed tags | Only tags an audience uses. Others get 422 tag_not_in_use. |
| Tags checkout can check | 100 distinct customer tags across all locks. More get 422 tag_limit. |
Check access before you tag
POST /api/v1/access/evaluate answers which locks a customer would pass. The token needs access:read.
curl -X POST https://app.shopbird.app/api/v1/access/evaluate \
-H "Authorization: Bearer sb_live_…" \
-H "Content-Type: application/json" \
-d '{ "customer": { "tags": ["discord-gold"], "signed_in": true }, "codes": [] }'
const access = await shopbird.access.evaluate({
customer: { tags: ["discord-gold"], signed_in: true },
codes: [],
});
{
"data": [
{ "lock_id": "…", "name": "Gold members", "access": "open", "active": true, "code_matched": false }
]
}
access is one of these for each lock:
| Value | Meaning |
|---|---|
open |
The customer passes. |
code |
They pass with a code or a confirm step. |
checkout |
Only checkout can decide, because the lock has cart conditions. |
none |
They do not pass. |
sync_pending: true appears when a change is not live yet.
- Send up to 10 codes per request.
- A token can try 10 codes that don't match per minute. More get
429 rate_limited. - Passwords and "account created before" still need the shopper to unlock on the storefront.