Sign in
Waitlist Entries

Create Waitlist Entry

Joins a free waitlist plan as the authenticated user. Requires waitlist_entry:create. Repeated joins return the existing pending entry, or an approved entry with a valid membership. Paid plans are rejected; no payment method is collected and no membership is granted.

post/waitlist_entries

Headers

Idempotency-Keystring
Example:d9105228-4a08-46b1-8b91-42fed586d383

A unique key that makes this request safe to retry. See Idempotent requests.

Request body

metadataobject

Custom key-value pairs to store on the signup. Max 50 keys, 100 chars per key, 500 chars per string value. Ignored when the request returns an existing signup.

plan_idstring required

The free waitlist plan to join, prefixed plan_.

Example request

{
  "plan_id": "plan_xxxxxxxxxxxxxx"
}

Response

joined

account_idstring required

The seller account, prefixed biz_.

approval_failure_reason'plan_unavailable' | 'already_member' | 'checkout_failed' | 'unknown' | 'null' nullable required

Why the last approval attempt failed, or null when none has. plan_unavailable — the plan, product, or seller account was deleted. already_member — the user already has a membership on a one-per-user product. checkout_failed — checkout failed, usually a declined payment, and the signup was denied. unknown — another failure; retry. Cleared when approval is requeued.

buyer_account_idstring nullable required

The account the signup was submitted on behalf of, prefixed biz_, or null when the user signed up for themselves.

created_atstring required

When this signup was submitted, as an ISO 8601 timestamp.

idstring required

The waitlist signup ID, prefixed entry_.

membership_idstring nullable required

The membership created for this signup, prefixed mem_, or null when there is none. Check the membership's status to determine access.

metadataobject required

Custom key-value metadata associated with this signup.

plan_idstring required

The plan this signup belongs to, prefixed plan_.

product_idstring nullable required

The product this signup belongs to, prefixed prod_, or null when the plan has no product.

status'pending' | 'approved' | 'denied' | 'canceled' required

The signup's current state. Approval runs asynchronously, so a signup stays pending until processing completes. approved alone does not prove an active membership; check membership_id.

updated_atstring required

When this signup last changed, as an ISO 8601 timestamp.

user_idstring required

The user who submitted this signup, prefixed user_.

Example response

{
  "account_id": "biz_xxxxxxxxxxxxxx",
  "approval_failure_reason": "plan_unavailable",
  "created_at": "2026-01-01T12:00:00.000Z",
  "id": "entry_xxxxxxxxxxxxxx",
  "metadata": {},
  "plan_id": "plan_xxxxxxxxxxxxxx",
  "product_id": "prod_xxxxxxxxxxxxxx",
  "status": "canceled",
  "updated_at": "2026-01-01T12:00:00.000Z",
  "user_id": "user_xxxxxxxxxxxxxx"
}

Changes