> For the complete documentation index, see [llms.txt](https://reiwa-dev.gitbook.io/waitlist-flow-support-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://reiwa-dev.gitbook.io/waitlist-flow-support-documentation/waitlist-flow-support-documentation.md).
# WAITLIST FLOW SUPPORT DOCUMENTATION
## Getting Started
### What is Waitlist Flow?
Waitlist Flow helps you manage product waitlists and notify customers when spots become available. It is built for limited-capacity products, events, workshops, drops, and sold-out items — turning demand into orders with automated or manual claim emails and one-click checkout links.
### Key Features
* **Create waitlists** for products in your store, with optional capacity limits
* **Automatic notifications** when orders are cancelled or refunded (cancellation trigger)
* **Manual control** — free up a slot and notify the next person in line
* **Customer emails** — join confirmation plus claim emails with draft-order checkout links
* **Theme integration** — “Join Waitlist” button on product pages via the theme app extension
* **Shopify Sidekick** — ask Sidekick about waitlists, entries, and next-in-line customers from your admin
* **Multi-language admin** — embedded app available in 19 languages
* **Pro plan extras** — branded customer emails, CSV export, and priority support (see plans below)
***
## Setting Up Your First Waitlist
{% stepper %}
{% step %}
## Create a Waitlist
1. Navigate to **Waitlists** in the app
2. Click **Create Waitlist**
3. Fill in the details:
* **Title** — e.g. “Yoga Class – Jan 15 6pm”
* **Product ID** — required for claim emails and **Free Up 1 Slot** (find the numeric ID in your product URL in Shopify admin, or use the `gid://shopify/Product/…` form)
* **Variant ID** — required for products with multiple variants (sizes, colours, etc.); for single-variant products, Product ID alone is enough
* **Trigger type**
* **Cancellation** — notify automatically when matching orders are cancelled or refunded
* **Manual** — you trigger notifications with **Free Up 1 Slot**
* **Max capacity** (optional) — limit how many people can join
{% hint style="info" %}
If claim emails or **Free Up 1 Slot** fail, check that the product still exists in Shopify and that Product ID / Variant ID on the waitlist are correct. You can see these IDs on the waitlist detail page.
{% endhint %}
{% endstep %}
{% step %}
## Share Your Waitlist
1. Open the waitlist from the **Waitlists** page
2. Copy the **join link** and share it by email, social, or your site
3. Customers can also join from the theme **Waitlist Button** block (see below)
{% endstep %}
{% step %}
## Add the Theme Extension (Optional)
1. In Shopify admin go to **Online Store** → **Themes**
2. Click **Customize** on your active theme
3. Open a product page (or section where you want the button)
4. Click **Add block** and search for **Waitlist Button**
5. Configure the block:
* **Waitlist ID** — copy from the waitlist detail page in the app
* **App URL** — your app URL (e.g. `https://app.waitlistflow.app`)
* Button text and style as needed
6. Save the theme
When a customer submits the form, the button shows **Joining…** feedback while sign-up completes.
{% endstep %}
{% endstepper %}
***
## Customer Journey
1. **Join** — customer enters name and email (via join link or theme button)
2. **Confirmation email** — optional “you’re on the waitlist” message (Settings → Send join confirmation)
3. **Spot opens** — cancellation/refund (automatic) or **Free Up 1 Slot** (manual)
4. **Claim email** — customer receives a checkout link (draft order invoice)
5. **Claim window** — default 15 minutes to complete purchase (configurable in Settings)
6. **If unclaimed** — status becomes **Unclaimed**; with auto-process enabled, the next person is notified
If someone is the only person on a waitlist, they can receive the claim email soon after joining (when a product is configured on the waitlist).
***
## Managing Waitlists
### Viewing Entries
Open any waitlist to see entries sorted by position (first come, first served). Filter by status:
| Status | Meaning |
| ------------- | ------------------------------------- |
| **Waiting** | In queue for a spot |
| **Notified** | Claim email sent; claim window active |
| **Claimed** | Checkout completed |
| **Unclaimed** | Did not claim in time |
### Manual Actions
#### Free Up 1 Slot
1. Open the waitlist
2. Click **Free Up 1 Slot**
3. The next **Waiting** customer gets a claim email with a checkout link
You can also use **Send claim email** / **Resend claim email** on an individual entry for testing or manual sends.
#### Export CSV (Pro)
* From the **Waitlists** list or a **waitlist detail** page, use **Export CSV** (Pro plan)
* Exports entry data (position, name, email, status, dates) for reporting or CRM use
#### Delete Entries or Waitlists
* Delete individual entries from the waitlist detail page (positions reorder automatically)
* Delete a whole waitlist from the Waitlists overview page
***
## Settings
Open **Settings** in the app navigation.
### General
* **Expiry time** — how long customers have to claim after notification (default: 15 minutes)
* **Auto-process on expiry** — notify the next person when a claim expires
* **Send join confirmation** — email when someone joins the waitlist
* **Default max capacity** — default for new waitlists
* **Allow discount codes at checkout** — whether discount codes can be applied on draft-order claim checkouts
### Email branding (Pro)
Available on the **Pro** plan under **Settings → Email branding**:
* **Logo URL** — your brand logo in emails (shop defaults may be suggested when you first open branding)
* **Primary colour** — button and accent colour (hex)
* **Sender name** — display name on outgoing emails
* **Headline & CTA label** — optional custom copy for claim emails
* **Footer shop URL** — link back to your store
* **Hide “Powered by Waitlist Flow”** — remove app footer branding on Pro
Save branding after upgrading to Pro; confirmation and claim emails use these settings for Pro merchants.
### Contact email
Set a **contact email** in Settings if you want it stored for your store’s app configuration (support and operational use).
***
## Shopify Sidekick
Waitlist Flow includes Sidekick tools so you can work from conversation in the Shopify admin:
* List and open waitlists
* See who is waiting and search entries by email or status
* Create a new waitlist from Sidekick
* Check eligibility and notify the next customer when a spot opens (where supported)
Sidekick complements the main **Waitlists** screens; use whichever fits your workflow.
***
## How Automatic Notifications Work
### Cancellation trigger
1. A customer cancels an order or receives a refund for a line item that matches the waitlist product/variant
2. Waitlist Flow receives the webhook and notifies the next **Waiting** customer
3. They receive a claim email with a draft order link
4. They must complete checkout within your configured expiry time
### Manual trigger
Use **Free Up 1 Slot** whenever you free capacity outside cancellations (events, workshops, manual inventory changes).
***
## Subscription Plans
Manage plans under **Billing** in the app.
### Free
* 1 waitlist
* 50 notification emails per month
* Theme extension, join links, cancellation & manual triggers
* Core waitlist management
### Premium — $5.99/month
* Unlimited waitlists
* Unlimited notification emails with **usage-based billing**: $0.05 per email, capped at **$15/month** for email usage
* Typical maximum: **$20.99/month** ($5.99 base + up to $15 email usage)
* All Free features
Best if you need many waitlists and high email volume without a fixed email cap.
### Pro — $39/month
* Unlimited waitlists
* **500 notification emails per month** included — **no per-email usage charges**
* **Branded waitlist emails** (logo, colours, sender name, optional removal of app footer)
* **CSV export** for waitlist entries
* **Priority support**
* All Premium capabilities except usage-based email billing (Pro uses a flat monthly allowance instead)
Annual Pro pricing may be available on the Shopify App Store listing where configured.
### Upgrading, downgrading, and switching plans
1. Go to **Billing**
2. Choose **Upgrade to Premium** or **Upgrade to Pro** and approve the charge in Shopify
3. To downgrade, use **Downgrade to Free** on the Billing page (you keep 1 waitlist and 50 emails/month on Free)
Moving from Premium to Pro is available from Billing when Pro is offered for your store.
***
## Troubleshooting
### Emails not sending
1. Confirm the customer email is valid (not a disposable/test address if you rely on deliverability)
2. Check **Billing → Usage** for monthly email limits (Free / Pro) or billing status (Premium)
3. Ensure **Send join confirmation** is on if you expect a join email
4. For claim emails, confirm the waitlist has a valid **Product ID** (and **Variant ID** if needed)
5. Review server logs or contact support if errors persist
### Free Up 1 Slot or claim email fails
1. Verify **Product ID** and **Variant ID** on the waitlist match a live, **Active** product in Shopify
2. Archived, draft, or deleted products cannot be used for draft orders
3. Ensure at least one customer is in **Waiting** status
4. Check email limits for your plan
### Theme button slow or no feedback
After updating the theme extension, customers should see **Joining…** while the form submits. Republish the theme if you recently updated the Waitlist Button block.
### Webhooks not working (cancellation trigger)
1. Confirm webhooks are registered for your app in the Partner Dashboard
2. Ensure production app URL is correct and the app is installed on the store
3. Check Shopify admin webhook delivery logs for failures
### Theme extension not showing
1. Block added and saved in the Theme Editor
2. **Waitlist ID** and **App URL** set correctly in block settings
3. App proxy configured for your app (`/apps/waitlist-flow/…`)
### “Cannot create waitlist”
* **Free:** limit of 1 waitlist — upgrade to Premium or Pro for unlimited waitlists
* Ensure title and trigger type are filled in
### “Email limit reached”
* **Free:** 50 emails/month — upgrade or wait for the next billing period
* **Pro:** 500 emails/month included — upgrade from Free/Premium or wait for reset
* **Premium:** usage billing applies; check Billing for usage (cap $15/month for emails)
### “CSV export requires the Pro plan”
CSV export is a **Pro** feature. Upgrade under **Billing**, then use **Export CSV** on the waitlists list or detail page.
### Invalid join link
If customers see “Waitlist not found”, the link may be wrong or the waitlist was deleted. Copy a fresh join link from the app.
***
## Best Practices
1. **Use clear waitlist titles** so you can tell queues apart at a glance
2. **Set Product ID (and Variant ID)** when creating the waitlist — required for claim emails
3. **Set max capacity** when you need a hard cap on sign-ups
4. **Test the flow** with your own email: join → **Free Up 1 Slot** or **Send claim email** → complete checkout
5. **Pro merchants:** configure **Email branding** in Settings so claim emails match your store
6. **Monitor unclaimed entries** and rely on auto-process on expiry to keep the queue moving
***
## Need More Help?
* **Pro plan:** priority support as described on the App Store listing
* **All plans:** contact via the Shopify App Store support channel for Waitlist Flow
* Use **Feedback** in the app for product feedback or bug reports where available
***
## FAQ
Can I have multiple waitlists for the same product?
Yes. Each waitlist is independent — useful for different dates, variants, or campaigns.
What happens if a customer does not claim within the expiry time?
Their status becomes **Unclaimed**. If **Auto-process on expiry** is enabled in Settings, the next waiting customer is notified automatically.
Can I export waitlist data?
Yes, on the **Pro** plan. Use **Export CSV** from the Waitlists page or an individual waitlist to download entries (email, name, status, position, and related fields).
Can I customize how emails look?
On **Pro**, use **Settings → Email branding** to set your logo, brand colour, sender name, optional headline/CTA text, and hide “Powered by Waitlist Flow”. Free and Premium plans use the standard Waitlist Flow email design.
Do customers need a Shopify account to join?
No. They only need a name and email (email is required for notifications).
What is the difference between Premium and Pro?
**Premium** suits high volume with pay-per-email usage (capped). **Pro** suits merchants who want a predictable **$39/month** flat rate, **500 included emails/month**, **branded emails**, **CSV export**, and **priority support** without usage charges.
Can Sidekick manage my waitlists?
Yes. Sidekick can list waitlists, show entries, help create waitlists, and support notifying the next customer in supported flows — alongside the main app screens.
Why did my customer only get one email?
Join confirmation and claim emails are separate. Confirmation is sent on join (if enabled). The claim email is sent when a spot opens (cancellation, refund, **Free Up 1 Slot**, or auto-process). Ensure the waitlist has a product configured and the customer is next in line.
Single-variant product — do I need Variant ID?
Usually **Product ID only** is enough. For products with multiple variants, add **Variant ID** so the correct item is added to the draft order.
Can I customize email templates?
Not at present but it's in the roadmap to offer this in Premium
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://reiwa-dev.gitbook.io/waitlist-flow-support-documentation/waitlist-flow-support-documentation.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.