Docs

Locks

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

GET /locks

List locks, newest first

Scope locks:read Returns 200

ParameterInTypeDescription
enabled query string true or false
limit query string 1–100 (default 50)
cursor query string next_cursor from the previous page

Request

curl "https://app.shopbird.app/api/v1/locks" \
  -H "Authorization: Bearer sb_live_…"

Response 200

{
  "data": [
    {
      "id": "clx8k2v1a0000qs08h3f2b9de",
      "name": "VIP early access",
      "message": "This item is locked. Enter your code:",
      "enabled": true,
      "match_all": true,
      "visibility": "buttons",
      "hide_from_lists": true,
      "active_from": "2026-11-01T09:00:00.000Z",
      "active_until": "2026-11-08T09:00:00.000Z",
      "redirect_after": null,
      "targets": [
        {
          "type": "product",
          "resource_id": "gid://shopify/Product/123",
          "title": "Fall hoodie"
        }
      ],
      "audience_ids": [
        "clx8k3b7c0002qs08a1d4e5f6"
      ],
      "managed_by": null,
      "version": 3,
      "created_at": "2026-11-01T09:00:00.000Z",
      "updated_at": "2026-11-02T14:30:00.000Z"
    }
  ],
  "next_cursor": "MTc2MTk4NzYwMDAwMHxjbHg4azJ2MWEwMDAwcXMwOGgzZjJiOWRl"
}
POST /locks

Create a lock

Scope locks: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 (11 fields)
FieldTypeDescription
name string
message string
enabled boolean
match_all boolean
visibility string | null
hide_from_lists boolean | null
active_from string | null
active_until string | null
redirect_after string | null
targets object[]
audience_ids string[]

Request

curl -X POST "https://app.shopbird.app/api/v1/locks" \
  -H "Authorization: Bearer sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "message": "string",
  "enabled": true,
  "match_all": true,
  "visibility": "string",
  "hide_from_lists": true,
  "active_from": "2026-11-01T09:00:00Z",
  "active_until": "2026-11-01T09:00:00Z",
  "redirect_after": "string",
  "targets": [
    {
      "type": "product",
      "resource_id": "string",
      "title": "string"
    }
  ],
  "audience_ids": [
    "string"
  ]
}'

Response 201

{
  "id": "clx8k2v1a0000qs08h3f2b9de",
  "name": "VIP early access",
  "message": "This item is locked. Enter your code:",
  "enabled": true,
  "match_all": true,
  "visibility": "buttons",
  "hide_from_lists": true,
  "active_from": "2026-11-01T09:00:00.000Z",
  "active_until": "2026-11-08T09:00:00.000Z",
  "redirect_after": null,
  "targets": [
    {
      "type": "product",
      "resource_id": "gid://shopify/Product/123",
      "title": "Fall hoodie"
    }
  ],
  "audience_ids": [
    "clx8k3b7c0002qs08a1d4e5f6"
  ],
  "managed_by": null,
  "version": 3,
  "created_at": "2026-11-01T09:00:00.000Z",
  "updated_at": "2026-11-02T14:30:00.000Z",
  "sync": {
    "generation": 42,
    "status": "pending"
  }
}
GET /locks/{id}

Get a lock

Scope locks:read Returns 200

ParameterInTypeDescription
idrequired path string

Request

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

Response 200

{
  "id": "clx8k2v1a0000qs08h3f2b9de",
  "name": "VIP early access",
  "message": "This item is locked. Enter your code:",
  "enabled": true,
  "match_all": true,
  "visibility": "buttons",
  "hide_from_lists": true,
  "active_from": "2026-11-01T09:00:00.000Z",
  "active_until": "2026-11-08T09:00:00.000Z",
  "redirect_after": null,
  "targets": [
    {
      "type": "product",
      "resource_id": "gid://shopify/Product/123",
      "title": "Fall hoodie"
    }
  ],
  "audience_ids": [
    "clx8k3b7c0002qs08a1d4e5f6"
  ],
  "managed_by": null,
  "version": 3,
  "created_at": "2026-11-01T09:00:00.000Z",
  "updated_at": "2026-11-02T14:30:00.000Z"
}
PATCH /locks/{id}

Update a lock (send If-Match with its ETag)

Scope locks: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 (11 fields)
FieldTypeDescription
name string
message string
enabled boolean
match_all boolean
visibility string | null
hide_from_lists boolean | null
active_from string | null
active_until string | null
redirect_after string | null
targets object[]
audience_ids string[]

Request

curl -X PATCH "https://app.shopbird.app/api/v1/locks/{id}" \
  -H "Authorization: Bearer sb_live_…" \
  -H 'If-Match: "v3"' \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "message": "string",
  "enabled": true,
  "match_all": true,
  "visibility": "string",
  "hide_from_lists": true,
  "active_from": "2026-11-01T09:00:00Z",
  "active_until": "2026-11-01T09:00:00Z",
  "redirect_after": "string",
  "targets": [
    {
      "type": "product",
      "resource_id": "string",
      "title": "string"
    }
  ],
  "audience_ids": [
    "string"
  ]
}'

Response 200

{
  "id": "clx8k2v1a0000qs08h3f2b9de",
  "name": "VIP early access",
  "message": "This item is locked. Enter your code:",
  "enabled": true,
  "match_all": true,
  "visibility": "buttons",
  "hide_from_lists": true,
  "active_from": "2026-11-01T09:00:00.000Z",
  "active_until": "2026-11-08T09:00:00.000Z",
  "redirect_after": null,
  "targets": [
    {
      "type": "product",
      "resource_id": "gid://shopify/Product/123",
      "title": "Fall hoodie"
    }
  ],
  "audience_ids": [
    "clx8k3b7c0002qs08a1d4e5f6"
  ],
  "managed_by": null,
  "version": 3,
  "created_at": "2026-11-01T09:00:00.000Z",
  "updated_at": "2026-11-02T14:30:00.000Z",
  "sync": {
    "generation": 42,
    "status": "pending"
  }
}
DELETE /locks/{id}

Delete a lock (send If-Match with its ETag)

Scope locks: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/locks/{id}" \
  -H "Authorization: Bearer sb_live_…" \
  -H 'If-Match: "v3"'

Response 200

{
  "id": "clx8k2v1a0000qs08h3f2b9de",
  "deleted": true,
  "sync": {
    "generation": 42,
    "status": "pending"
  }
}
POST /locks/{id}/enable

Turn a lock on

Scope locks: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

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

Response 200

{
  "id": "clx8k2v1a0000qs08h3f2b9de",
  "name": "VIP early access",
  "message": "This item is locked. Enter your code:",
  "enabled": true,
  "match_all": true,
  "visibility": "buttons",
  "hide_from_lists": true,
  "active_from": "2026-11-01T09:00:00.000Z",
  "active_until": "2026-11-08T09:00:00.000Z",
  "redirect_after": null,
  "targets": [
    {
      "type": "product",
      "resource_id": "gid://shopify/Product/123",
      "title": "Fall hoodie"
    }
  ],
  "audience_ids": [
    "clx8k3b7c0002qs08a1d4e5f6"
  ],
  "managed_by": null,
  "version": 3,
  "created_at": "2026-11-01T09:00:00.000Z",
  "updated_at": "2026-11-02T14:30:00.000Z",
  "sync": {
    "generation": 42,
    "status": "pending"
  }
}
POST /locks/{id}/disable

Turn a lock off

Scope locks: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

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

Response 200

{
  "id": "clx8k2v1a0000qs08h3f2b9de",
  "name": "VIP early access",
  "message": "This item is locked. Enter your code:",
  "enabled": true,
  "match_all": true,
  "visibility": "buttons",
  "hide_from_lists": true,
  "active_from": "2026-11-01T09:00:00.000Z",
  "active_until": "2026-11-08T09:00:00.000Z",
  "redirect_after": null,
  "targets": [
    {
      "type": "product",
      "resource_id": "gid://shopify/Product/123",
      "title": "Fall hoodie"
    }
  ],
  "audience_ids": [
    "clx8k3b7c0002qs08a1d4e5f6"
  ],
  "managed_by": null,
  "version": 3,
  "created_at": "2026-11-01T09:00:00.000Z",
  "updated_at": "2026-11-02T14:30:00.000Z",
  "sync": {
    "generation": 42,
    "status": "pending"
  }
}