Breeder API

Breeder API — waitlist management

Manage waitlist entries for your pairings via the Breeder API.

Overview

Pairings with `waitlistEnabled: true` can have a waitlist of buyers. You can read and manage waitlist entries programmatically.

List waitlist entries

Returns all waitlist entries for a pairing you own, ordered by position.

Parameter	Type	Required	Description
limit	integer	Optional	Number of results per page (1–100, default 20)
cursor	string	Optional	Pagination cursor from the previous response

GET /api/breeder/pairings/{id}/waitlist

curl https://herpify.com/api/breeder/pairings/clx1a2b3/waitlist \
  -H "Authorization: Bearer hm_live_your_key_here"

Response

{
  "data": [
    {
      "id": "clx1wl1",
      "position": 1,
      "notes": "Interested in male morphs",
      "notifiedAt": null,
      "createdAt": "2026-04-10T09:00:00.000Z",
      "user": { "id": "...", "username": "jake_m", "displayName": "Jake M.", "avatarUrl": null }
    }
  ],
  "meta": { "limit": 20, "hasMore": false, "nextCursor": null }
}

Add a waitlist entry

Adds a user to the waitlist. The waitlist must be enabled on the pairing. Position is automatically assigned as the next available slot.

Parameter	Type	Required	Description
userId	string (cuid)	Required	The Herpify user ID to add to the waitlist
notes	string	Optional	Optional notes (max 500 characters)

POST /api/breeder/pairings/{id}/waitlist

curl -X POST https://herpify.com/api/breeder/pairings/clx1a2b3/waitlist \
  -H "Authorization: Bearer hm_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"userId": "clx1user123", "notes": "Deposit paid via bank transfer"}'

Remove a waitlist entry

Removes an entry from the waitlist. Positions are automatically compacted so there are no gaps.

DELETE /api/breeder/pairings/{id}/waitlist/{entryId}

curl -X DELETE https://herpify.com/api/breeder/pairings/clx1a2b3/waitlist/clx1wl1 \
  -H "Authorization: Bearer hm_live_your_key_here"

Was this article helpful?