Guest customers

A guest CustomerAPI is a record XPay creates automatically the first time someone pays you without a customer record already attached to the checkout. They show up in your Customers list with a Guest badge and behave like a regular customer everywhere except a few places this page calls out.

Guests exist so two things just work:

1. You can find anyone who paid you, by name, email, or phone, even if you never built any signup or account flow on your side.
2. Lifetime spend, refunds, and payment history roll up under a single record per person, even when their contact info shifts a little across visits (capitalized email one time, lowercase the next, country prefix as 00 one time and + the next).

What you'll see

How XPay groups guest customers

When a checkout completes without a customer record attached, XPay looks for an existing guest on your account that matches and reuses it. If nothing matches, a new guest record is created. The match runs in two phases.

At checkout, by contact info

The moment a customer enters their email or phone on the checkout form, XPay looks for an existing guest with the same email or the same phone:

A match on either field reuses the existing guest record. The latest contact info becomes the primary, and the previous values stay searchable on the profile under Alternative Emails and Alternative Numbers. Nothing is lost.

After payment, by card

Once the payment succeeds, XPay records the card on the guest's profile. If the same card has been used on another guest record on your account, the two are merged into one. All transactions, refunds, and payment methods from the absorbed records move onto the surviving record, and lifetime spend is recalculated.

This is what catches the case where a customer used a different email or phone number on two separate checkouts but paid with the same card both times.

Same merchant only

Guest matching only ever happens within a single merchant account. Two different merchants on XPay never share guest records, even if the same person paid both. Test mode and live mode are separate too.

Never crosses into registered customers

Guest matching only matches guests to other guests. A guest checkout never gets auto-attached to a registered customer, even when they share an email, phone, or card. The connection is shown to you in the Related sections on each profile, but XPay won't merge the two on its own. Only you can vouch for a customer's identity, by passing a customerId on a Checkout Session (Customer lifecycle covers the code-side).

What changes on a guest profile

Open a guest customer to see their profile. The shape is the same as a registered customer's, with three differences.

Guest badge

A small Guest badge sits next to the name in the list and at the top of the detail page. Hover the badge for a one-line reminder of why the record exists.

Alternative Emails and Alternative Numbers

In the Customer Details column, two extra fields appear when the guest has used more than one email or phone over time. The primary email and phone are still on top. Everything else they've used is listed underneath, so you can correlate the same person across slight variations.

Related sections

Cross-link tables that show how this guest connects to other records. See the next section for what each one lists.

Related accounts

On every customer profile, XPay surfaces records that share an email, phone, or card with the one you're looking at. Three sections can appear, depending on which side you're on:

Use these to see the full picture: a registered customer who once paid as a guest before creating an account, or a single customer whose checkouts ended up split across more than one guest record before they paid with a shared card.

The matching is one-way and read-only. The dashboard shows you the connection. It doesn't merge guests into registered customers automatically.

What guests can't do

A guest record covers most of what you'll do day to day. Two things only registered customers can do:

Saved card on file. Every guest checkout asks for a fresh card. There's no way to charge a guest's card again later through the dashboard or through a future Checkout Session. If you want a card you can charge again (subscriptions, one-click reordering, off-session top-ups), create a registered customer instead. The developer-side guide on Customer lifecycle covers customerCreation: "always" and how to capture the resulting cus_* from the checkout.session.completed webhook.

Pass them as customerId on a Checkout Session. Guests are checkout-only records. You can browse them, see their history, and correlate them with registered customers, but you can't reference a guest's ID when creating the next Checkout Session. If a guest paid you and later signed up, the right move is to start a fresh registered customer on their first signed-in payment, then use that cus_* for everything after. The dashboard's Related sections keep the connection visible.

Where to next