Docs

Audiences

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

GET /audiences

List audiences, newest first

Scope audiences:read Returns 200

ParameterInTypeDescription
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" \
  -H "Authorization: Bearer sb_live_…"

Response 200

{
  "data": [
    {
      "id": "clx8k3b7c0002qs08a1d4e5f6",
      "name": "VIP customers",
      "conditions": [
        "tags",
        "codes"
      ],
      "match_all": true,
      "tags": [
        "vip"
      ],
      "tag_match_all": true,
      "has_password": true,
      "confirm_prompt": null,
      "confirm_button": null,
      "joined_before": null,
      "active_codes": 120,
      "version": 3,
      "created_at": "2026-11-01T09:00:00.000Z",
      "updated_at": "2026-11-02T14:30:00.000Z"
    }
  ],
  "next_cursor": "MTc2MTk4NzYwMDAwMHxjbHg4azJ2MWEwMDAwcXMwOGgzZjJiOWRl"
}
POST /audiences

Create an audience

Scope audiences:write Returns 201

ParameterInTypeDescription
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 (10 fields)
FieldTypeDescription
name string
conditions password | codes | tags | signedIn | confirm | joined[]
match_all boolean
password string
tags string[]
tag_match_all boolean
confirm_prompt string | null
confirm_button string | null
joined_before string | null
codes object[]

Request

curl -X POST "https://app.shopbird.app/api/v1/audiences" \
  -H "Authorization: Bearer sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "conditions": [
    "password"
  ],
  "match_all": true,
  "password": "string",
  "tags": [
    "string"
  ],
  "tag_match_all": true,
  "confirm_prompt": "string",
  "confirm_button": "string",
  "joined_before": "string",
  "codes": [
    {
      "code": "string",
      "label": "string"
    }
  ]
}'

Response 201

{
  "id": "clx8k3b7c0002qs08a1d4e5f6",
  "name": "VIP customers",
  "conditions": [
    "tags",
    "codes"
  ],
  "match_all": true,
  "tags": [
    "vip"
  ],
  "tag_match_all": true,
  "has_password": true,
  "confirm_prompt": null,
  "confirm_button": null,
  "joined_before": null,
  "active_codes": 120,
  "version": 3,
  "created_at": "2026-11-01T09:00:00.000Z",
  "updated_at": "2026-11-02T14:30:00.000Z"
}
GET /audiences/{id}

Get an audience

Scope audiences:read Returns 200

ParameterInTypeDescription
idrequired path string

Request

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

Response 200

{
  "id": "clx8k3b7c0002qs08a1d4e5f6",
  "name": "VIP customers",
  "conditions": [
    "tags",
    "codes"
  ],
  "match_all": true,
  "tags": [
    "vip"
  ],
  "tag_match_all": true,
  "has_password": true,
  "confirm_prompt": null,
  "confirm_button": null,
  "joined_before": null,
  "active_codes": 120,
  "version": 3,
  "created_at": "2026-11-01T09:00:00.000Z",
  "updated_at": "2026-11-02T14:30:00.000Z"
}
PATCH /audiences/{id}

Update an audience (send If-Match with its ETag)

Scope audiences: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)
If-Match header string The ETag from your last read; required where the resource is versioned
Request body (10 fields)
FieldTypeDescription
name string
conditions password | codes | tags | signedIn | confirm | joined[]
match_all boolean
password string
tags string[]
tag_match_all boolean
confirm_prompt string | null
confirm_button string | null
joined_before string | null
codes object[]

Request

curl -X PATCH "https://app.shopbird.app/api/v1/audiences/{id}" \
  -H "Authorization: Bearer sb_live_…" \
  -H 'If-Match: "v3"' \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "conditions": [
    "password"
  ],
  "match_all": true,
  "password": "string",
  "tags": [
    "string"
  ],
  "tag_match_all": true,
  "confirm_prompt": "string",
  "confirm_button": "string",
  "joined_before": "string",
  "codes": [
    {
      "code": "string",
      "label": "string"
    }
  ]
}'

Response 200

{
  "id": "clx8k3b7c0002qs08a1d4e5f6",
  "name": "VIP customers",
  "conditions": [
    "tags",
    "codes"
  ],
  "match_all": true,
  "tags": [
    "vip"
  ],
  "tag_match_all": true,
  "has_password": true,
  "confirm_prompt": null,
  "confirm_button": null,
  "joined_before": null,
  "active_codes": 120,
  "version": 3,
  "created_at": "2026-11-01T09:00:00.000Z",
  "updated_at": "2026-11-02T14:30:00.000Z",
  "sync": {
    "generation": 42,
    "status": "pending"
  }
}
DELETE /audiences/{id}

Delete an audience (send If-Match with its ETag)

Scope audiences: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)
If-Match header string The ETag from your last read; required where the resource is versioned

Request

curl -X DELETE "https://app.shopbird.app/api/v1/audiences/{id}" \
  -H "Authorization: Bearer sb_live_…" \
  -H 'If-Match: "v3"'

Response 200

{
  "id": "clx8k2v1a0000qs08h3f2b9de",
  "deleted": true,
  "sync": {
    "generation": 42,
    "status": "pending"
  }
}