Docs

Drops

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

GET /drops

List drops, newest first

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

Response 200

{
  "data": [
    {
      "id": "clx8k4c9d0004qs08b2e6f7a8",
      "name": "Fall drop",
      "launch_at": "2026-11-07T17:00:00.000Z",
      "teaser_at": "2026-11-03T17:00:00.000Z",
      "preview_at": "2026-11-05T17:00:00.000Z",
      "ends_at": "2026-11-14T17:00:00.000Z",
      "sell_mode": "first_come",
      "raffle_opens_at": null,
      "raffle_winners": null,
      "raffle_claim_hours": 48,
      "raffle_unclaimed": "release",
      "raffle_notify": "csv",
      "drawn_at": null,
      "mto_closes_at": null,
      "mto_cap": null,
      "mto_ship_text": "",
      "sources": [
        {
          "kind": "new",
          "collection_id": "gid://shopify/Collection/456",
          "title": "Fall drop",
          "products": [
            {
              "id": "gid://shopify/Product/123",
              "title": "Fall hoodie"
            }
          ]
        }
      ],
      "windows": [
        {
          "hours_before": 24,
          "audience_ids": [
            "clx8k3b7c0002qs08a1d4e5f6"
          ],
          "match_all": true
        }
      ],
      "version": 3,
      "created_at": "2026-11-01T09:00:00.000Z",
      "updated_at": "2026-11-02T14:30:00.000Z"
    }
  ],
  "next_cursor": "MTc2MTk4NzYwMDAwMHxjbHg4azJ2MWEwMDAwcXMwOGgzZjJiOWRl"
}
POST /drops

Create a drop (times in UTC)

Scope drops: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 (16 fields)
FieldTypeDescription
name string
launch_at string
teaser_at string | null
preview_at string | null
ends_at string | null
sell_mode first_come | raffle | made_to_order
raffle_opens_at string | null
raffle_winners integer | null
raffle_claim_hours integer
raffle_unclaimed release | keep
raffle_notify csv | email | flow
mto_closes_at string | null
mto_cap integer | null
mto_ship_text string
sources object[]
windows object[]

Request

curl -X POST "https://app.shopbird.app/api/v1/drops" \
  -H "Authorization: Bearer sb_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "launch_at": "2026-11-01T09:00:00Z",
  "teaser_at": "2026-11-01T09:00:00Z",
  "preview_at": "2026-11-01T09:00:00Z",
  "ends_at": "2026-11-01T09:00:00Z",
  "sell_mode": "first_come",
  "raffle_opens_at": "2026-11-01T09:00:00Z",
  "raffle_winners": 1,
  "raffle_claim_hours": 1,
  "raffle_unclaimed": "release",
  "raffle_notify": "csv",
  "mto_closes_at": "2026-11-01T09:00:00Z",
  "mto_cap": 1,
  "mto_ship_text": "string",
  "sources": [
    {
      "kind": "new",
      "collection_id": "string",
      "title": "string",
      "products": [
        {
          "id": "string",
          "title": "string"
        }
      ]
    }
  ],
  "windows": [
    {
      "hours_before": 1,
      "audience_ids": [
        "string"
      ],
      "match_all": true
    }
  ]
}'

Response 201

{
  "id": "clx8k4c9d0004qs08b2e6f7a8",
  "name": "Fall drop",
  "launch_at": "2026-11-07T17:00:00.000Z",
  "teaser_at": "2026-11-03T17:00:00.000Z",
  "preview_at": "2026-11-05T17:00:00.000Z",
  "ends_at": "2026-11-14T17:00:00.000Z",
  "sell_mode": "first_come",
  "raffle_opens_at": null,
  "raffle_winners": null,
  "raffle_claim_hours": 48,
  "raffle_unclaimed": "release",
  "raffle_notify": "csv",
  "drawn_at": null,
  "mto_closes_at": null,
  "mto_cap": null,
  "mto_ship_text": "",
  "sources": [
    {
      "kind": "new",
      "collection_id": "gid://shopify/Collection/456",
      "title": "Fall drop",
      "products": [
        {
          "id": "gid://shopify/Product/123",
          "title": "Fall hoodie"
        }
      ]
    }
  ],
  "windows": [
    {
      "hours_before": 24,
      "audience_ids": [
        "clx8k3b7c0002qs08a1d4e5f6"
      ],
      "match_all": true
    }
  ],
  "version": 3,
  "created_at": "2026-11-01T09:00:00.000Z",
  "updated_at": "2026-11-02T14:30:00.000Z",
  "sync": {
    "generation": 42,
    "status": "pending"
  },
  "would_create": [
    {
      "collection": "Fall drop"
    }
  ]
}
GET /drops/{id}

Get a drop

Scope drops:read Returns 200

ParameterInTypeDescription
idrequired path string

Request

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

Response 200

{
  "id": "clx8k4c9d0004qs08b2e6f7a8",
  "name": "Fall drop",
  "launch_at": "2026-11-07T17:00:00.000Z",
  "teaser_at": "2026-11-03T17:00:00.000Z",
  "preview_at": "2026-11-05T17:00:00.000Z",
  "ends_at": "2026-11-14T17:00:00.000Z",
  "sell_mode": "first_come",
  "raffle_opens_at": null,
  "raffle_winners": null,
  "raffle_claim_hours": 48,
  "raffle_unclaimed": "release",
  "raffle_notify": "csv",
  "drawn_at": null,
  "mto_closes_at": null,
  "mto_cap": null,
  "mto_ship_text": "",
  "sources": [
    {
      "kind": "new",
      "collection_id": "gid://shopify/Collection/456",
      "title": "Fall drop",
      "products": [
        {
          "id": "gid://shopify/Product/123",
          "title": "Fall hoodie"
        }
      ]
    }
  ],
  "windows": [
    {
      "hours_before": 24,
      "audience_ids": [
        "clx8k3b7c0002qs08a1d4e5f6"
      ],
      "match_all": true
    }
  ],
  "version": 3,
  "created_at": "2026-11-01T09:00:00.000Z",
  "updated_at": "2026-11-02T14:30:00.000Z"
}
PATCH /drops/{id}

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

Scope drops: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 (16 fields)
FieldTypeDescription
name string
launch_at string
teaser_at string | null
preview_at string | null
ends_at string | null
sell_mode first_come | raffle | made_to_order
raffle_opens_at string | null
raffle_winners integer | null
raffle_claim_hours integer
raffle_unclaimed release | keep
raffle_notify csv | email | flow
mto_closes_at string | null
mto_cap integer | null
mto_ship_text string
sources object[]
windows object[]

Request

curl -X PATCH "https://app.shopbird.app/api/v1/drops/{id}" \
  -H "Authorization: Bearer sb_live_…" \
  -H 'If-Match: "v3"' \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "launch_at": "2026-11-01T09:00:00Z",
  "teaser_at": "2026-11-01T09:00:00Z",
  "preview_at": "2026-11-01T09:00:00Z",
  "ends_at": "2026-11-01T09:00:00Z",
  "sell_mode": "first_come",
  "raffle_opens_at": "2026-11-01T09:00:00Z",
  "raffle_winners": 1,
  "raffle_claim_hours": 1,
  "raffle_unclaimed": "release",
  "raffle_notify": "csv",
  "mto_closes_at": "2026-11-01T09:00:00Z",
  "mto_cap": 1,
  "mto_ship_text": "string",
  "sources": [
    {
      "kind": "new",
      "collection_id": "string",
      "title": "string",
      "products": [
        {
          "id": "string",
          "title": "string"
        }
      ]
    }
  ],
  "windows": [
    {
      "hours_before": 1,
      "audience_ids": [
        "string"
      ],
      "match_all": true
    }
  ]
}'

Response 200

{
  "id": "clx8k4c9d0004qs08b2e6f7a8",
  "name": "Fall drop",
  "launch_at": "2026-11-07T17:00:00.000Z",
  "teaser_at": "2026-11-03T17:00:00.000Z",
  "preview_at": "2026-11-05T17:00:00.000Z",
  "ends_at": "2026-11-14T17:00:00.000Z",
  "sell_mode": "first_come",
  "raffle_opens_at": null,
  "raffle_winners": null,
  "raffle_claim_hours": 48,
  "raffle_unclaimed": "release",
  "raffle_notify": "csv",
  "drawn_at": null,
  "mto_closes_at": null,
  "mto_cap": null,
  "mto_ship_text": "",
  "sources": [
    {
      "kind": "new",
      "collection_id": "gid://shopify/Collection/456",
      "title": "Fall drop",
      "products": [
        {
          "id": "gid://shopify/Product/123",
          "title": "Fall hoodie"
        }
      ]
    }
  ],
  "windows": [
    {
      "hours_before": 24,
      "audience_ids": [
        "clx8k3b7c0002qs08a1d4e5f6"
      ],
      "match_all": true
    }
  ],
  "version": 3,
  "created_at": "2026-11-01T09:00:00.000Z",
  "updated_at": "2026-11-02T14:30:00.000Z",
  "sync": {
    "generation": 42,
    "status": "pending"
  },
  "would_create": [
    {
      "collection": "Fall drop"
    }
  ]
}
DELETE /drops/{id}

Delete a drop and the locks it owns (send If-Match with its ETag)

Scope drops:write Returns 202

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

Response 202

{
  "id": "clx8k4c9d0004qs08b2e6f7a8",
  "deleting": true
}
GET /drops/{id}/raffle-entries

List a raffle's entries (customer IDs only), newest first

Scope drops: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/drops/{id}/raffle-entries" \
  -H "Authorization: Bearer sb_live_…"

Response 200

{
  "data": [
    {
      "id": "clx8k9b4c000eqs08a7d1e2f3",
      "customer_id": "gid://shopify/Customer/123",
      "entered_at": "2026-11-01T09:00:00.000Z",
      "won": true
    }
  ],
  "next_cursor": "MTc2MTk4NzYwMDAwMHxjbHg4azJ2MWEwMDAwcXMwOGgzZjJiOWRl"
}
POST /drops/{id}/raffle/draw

Draw a raffle's winners (entries close at launch)

Scope drops:write Returns 202

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/drops/{id}/raffle/draw" \
  -H "Authorization: Bearer sb_live_…"

Response 202

{
  "drawing": true
}