Docs

Codes

Every codes endpoint, with its scope, parameters, a request and a response.

GET /audiences/{id}/codes

List an audience's active codes, newest first

Scope codes:read Returns 200

ParameterInTypeDescription
idrequired path string
limit query string 1–100 (default 50)
cursor query string next_cursor from the previous page

Request

curl "https://app.shopbird.app/api/v1/audiences/{id}/codes" \
  -H "Authorization: Bearer sb_live_…"

Response 200

{
  "data": [
    {
      "id": "clx8k5d0e0006qs08c3f7a8b9",
      "code": "FALLVIP-7K2Q",
      "label": "Newsletter",
      "created_at": "2026-11-01T09:00:00.000Z"
    }
  ],
  "next_cursor": "MTc2MTk4NzYwMDAwMHxjbHg4azJ2MWEwMDAwcXMwOGgzZjJiOWRl"
}
POST /audiences/{id}/codes

Add codes (up to 100, or generate up to 100); all or nothing

Scope codes:write Returns 201

ParameterInTypeDescription
idrequired path string
dry_run query true true: validate and return the would-be result; nothing is saved
wait query true true: wait up to 20 s until the change is live at checkout
Idempotency-Key header string Retrying with the same key never applies the write twice (kept 24 h)
Request body (2 fields)
FieldTypeDescription
codes object[]
generate integer

Request

curl -X POST "https://app.shopbird.app/api/v1/audiences/{id}/codes" \
  -H "Authorization: Bearer sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "generate": 50
}'

Response 201

{
  "data": [
    {
      "id": "clx8k5d0e0006qs08c3f7a8b9",
      "code": "FALLVIP-7K2Q",
      "label": "Newsletter",
      "created_at": "2026-11-01T09:00:00.000Z"
    }
  ],
  "sync": {
    "generation": 42,
    "status": "pending"
  }
}
POST /audiences/{id}/codes/revoke

Revoke codes by ID or code; all or nothing

Scope codes:write Returns 200

ParameterInTypeDescription
idrequired path string
dry_run query true true: validate and return the would-be result; nothing is saved
wait query true true: wait up to 20 s until the change is live at checkout
Idempotency-Key header string Retrying with the same key never applies the write twice (kept 24 h)
Request body (2 fields)
FieldTypeDescription
ids string[]
codes string[]

Request

curl -X POST "https://app.shopbird.app/api/v1/audiences/{id}/codes/revoke" \
  -H "Authorization: Bearer sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "ids": [
    "string"
  ],
  "codes": [
    "string"
  ]
}'

Response 200

{
  "revoked": [
    "clx8k5d0e0006qs08c3f7a8b9"
  ],
  "already_revoked": [],
  "sync": {
    "generation": 42,
    "status": "pending"
  }
}