Referrals

Every successful signup gets two things back from the API:

A 6-character referral_code the subscriber shares with friends.
A status_url the subscriber can revisit to see their position and copy their share link.

When a friend signs up with a ?queueup_ref=ABC234 query param on the page, the widget reads it, forwards it to the API, and the original subscriber’s spot moves up. No code on your side, as long as the widget is on the page. The query key is namespaced so it does not collide with the ?ref= you may already use for your own source tracking.

Turn referrals on or off

Referrals are on by default for every waitlist. To disable them, open the waitlist setup page, go to the Referrals section, and turn off Enable referrals. While disabled, the API stops minting referral codes and status links, and any inbound ?queueup_ref= value is ignored. Existing subscribers who already have a code keep theirs, but it stops earning bumps until you re-enable.

Tune the skip amount

The default jump per referral is 5 spots. You can change this from the Referrals section in the dashboard. Pick anything between 1 and 100. A higher value rewards top referrers more aggressively but makes the line less time-ordered.

How it works

A new visitor lands on https://yoursite.example/. They submit the embed form.
The widget receives referral_code and status_url in the response and emits a queueup:success event with both.
They share their link as https://yoursite.example/?queueup_ref=ABC234.
A friend visits that URL. The widget auto-reads ?queueup_ref=ABC234. The friend submits.
On the server, the original subscriber’s priority_score bumps by your configured skip amount (default 5). Their position improves.
Either subscriber can revisit status_url to see their current spot.

The widget itself doesn’t know which page on your site hosts the form. To produce a clean share link of the form https://yoursite.example/?queueup_ref=ABC234, configure the Signup URL in the dashboard.

Open your waitlist’s setup page.
Find the Signup URL field.
Enter the public URL where the embed lives.
Save.

This URL is appended with ?queueup_ref=<code> to build the share link rendered on the hosted status page. If you leave it blank, the status page shows the bare code instead of a clickable link, and subscribers must paste the code by hand.

Listen for the success payload

The minimum integration is none. The widget reads ?queueup_ref= automatically and forwards it on submit. To show your own share UI inline, listen for queueup:success:

<queueup-form waitlist-id="wl_abc123"></queueup-form>

<div id="thanks" hidden>
  <p>Thanks. Your spot will move up every time a friend signs up.</p>
  <p>Your link: <code id="share-link"></code></p>
  <a id="status-link" target="_blank">Check your status</a>
</div>

<script>
  document.querySelector("queueup-form").addEventListener("queueup:success", (e) => {
    const { referralCode, statusUrl } = e.detail;
    if (!referralCode) return;
    const link = `https://yoursite.example/?queueup_ref=${referralCode}`;
    document.getElementById("share-link").textContent = link;
    document.getElementById("status-link").href = statusUrl;
    document.getElementById("thanks").hidden = false;
  });
</script>

The same payload arrives for both new signups and returning users. An existing subscriber re-submitting their email gets the same statusToken, referralCode, and statusUrl they had before, so your handler can treat both cases identically.

One-line redirect to the hosted page

If you’d rather hand off the share UX entirely, set success-redirect="status" on the element. The widget plays its in-place success animation, then navigates to the hosted status page after a short delay.

<queueup-form
  waitlist-id="wl_abc123"
  success-redirect="status"
></queueup-form>

The redirect is cross-origin: subscribers leave your site for the QueueUp hosted page. If you want them to stay on your domain, omit the attribute and render your own confirmation from the queueup:success payload.

Manual referral code

If you have your own routing (e.g. the friend lands on a custom landing page that already encodes the referral), pass the code via the referral-code attribute. It takes precedence over the URL parameter.

<queueup-form
  waitlist-id="wl_abc123"
  referral-code="ABC234"
></queueup-form>

To opt out of URL reading entirely, set auto-ref="off".

Edge cases

Invalid codes are dropped silently. A typo’d or malformed ?queueup_ref= value is treated as no referral. The signup still succeeds.
Self-referral is ignored. Subscribers who somehow paste their own code into a friend’s slot do not bump their own score.
Cross-waitlist codes do nothing. A code from waitlist A on a form for waitlist B is treated as no referral.
Idempotent re-signup does not double-credit. If a subscriber re-submits their email, the original referrer is not credited a second time.
Disabled waitlists. While Enable referrals is off, the subscribe response carries no referral_code or status_url. Re-enabling does not retroactively mint codes for the rows that signed up while it was off.