I am recently trying to integrate stripe payment to my SaaS product and got lots of caveats with stripe guest customers and customer portal.
These caveats are not clearly described in stripe documentation, even some big named SaaS makers like @levelsio got confused for this: https://x.com/levelsio/status/1600314461021122560
```@levelsio on X: "For some reason all my Customers on Stripe for https://t.co/Hccng2XUV1 are a Guest? I have no idea what this is. I thought it had to do with using Stripe Payment Links but even now I switched to making my own Stripe Checkout Session I just have GUESTS. Help! https://t.co/jFAmL0Cvkd" / X.
```
Basically, stripe payment needs a customer object in order to know who made the payment for some kind of accounting reasons.
In general most SaaS has its own, internal users DB, which needs to be somewhat synced with stripe customers, and SaaS customers also need to way to download invoices, change payment methods, downgrade/upgrade subscription plans etc, hence stripe also provide a no code customer portal (https://docs.stripe.com/customer-management) just for that purpose.
So when you create a stripe checkout session, you can provide a `customer`, ref: https://docs.stripe.com/api/checkout/sessions/create
However, if you do not provide `customer`, then you got some big caveats:
- the payment becomes a guest payment, stripe will groups all guest payments made using the same card, email, or phone in a unified guest customer view in dashboard
- guest customers cannot be deleted or retrieved via stripe API
- guest customers cannot even ben deleted via stripe dashboard
- guest customers cannot view invoices via customer portal
This is not the end of the story, there're TWO MORE BIG CAVEATS:
- Guest customers cannot sign in with customer portal, so if you do not manually create a customer and instead relying on stripe guest customers, then your customers cannot sign in stripe customer to manage their subscriptions
- Some options for creating stripe checkout sessions will create a non-guest customer for you by default, however, this will create customers for you even they all have the same emails. Stripe sometimes will create mulitple customers with same emails in one checkout session! For example, when enable `invoice_creation`, stripe will create non-guest customer for every checkout session
So in the end I would suggest you to create a stripe customer explicitly and attach that customer id to checkout sessions, make sure that one email only lead to one stripe customers so your SaaS users won't get confused. And there're two proper hooks to create a stripe customers:
- when a users sign up your SaaS, you create a stripe customer and record stripe customer id in your internal users DB
- when a user tries to check out a payment/subscription, you create a stripe customer and do the recording as well.
It is highly suggested to make the creation of stripe customers (keyed by email) idempotent, i.e, one email lead to one and only one stripe customers so later on when your user signs in via Stripe customer portal with email, he can get all invoices.
----
Overall stripe DX is great, however stripe's product matrix is so big that lots of options a interleaved with each other, it feels like playing a game and then suddenly you found a hidden feature, but not fun and time consuming.
These caveats are not clearly described in stripe documentation, even some big named SaaS makers like @levelsio got confused for this: https://x.com/levelsio/status/1600314461021122560
```@levelsio on X: "For some reason all my Customers on Stripe for https://t.co/Hccng2XUV1 are a Guest? I have no idea what this is. I thought it had to do with using Stripe Payment Links but even now I switched to making my own Stripe Checkout Session I just have GUESTS. Help! https://t.co/jFAmL0Cvkd" / X. ```
Basically, stripe payment needs a customer object in order to know who made the payment for some kind of accounting reasons.
In general most SaaS has its own, internal users DB, which needs to be somewhat synced with stripe customers, and SaaS customers also need to way to download invoices, change payment methods, downgrade/upgrade subscription plans etc, hence stripe also provide a no code customer portal (https://docs.stripe.com/customer-management) just for that purpose.
So when you create a stripe checkout session, you can provide a `customer`, ref: https://docs.stripe.com/api/checkout/sessions/create
However, if you do not provide `customer`, then you got some big caveats:
- the payment becomes a guest payment, stripe will groups all guest payments made using the same card, email, or phone in a unified guest customer view in dashboard
- guest customers cannot be deleted or retrieved via stripe API
- guest customers cannot even ben deleted via stripe dashboard
- guest customers cannot view invoices via customer portal
Check Guest customer FAQ: https://support.stripe.com/questions/guest-customer-faq
This is not the end of the story, there're TWO MORE BIG CAVEATS:
- Guest customers cannot sign in with customer portal, so if you do not manually create a customer and instead relying on stripe guest customers, then your customers cannot sign in stripe customer to manage their subscriptions
- Some options for creating stripe checkout sessions will create a non-guest customer for you by default, however, this will create customers for you even they all have the same emails. Stripe sometimes will create mulitple customers with same emails in one checkout session! For example, when enable `invoice_creation`, stripe will create non-guest customer for every checkout session
So in the end I would suggest you to create a stripe customer explicitly and attach that customer id to checkout sessions, make sure that one email only lead to one stripe customers so your SaaS users won't get confused. And there're two proper hooks to create a stripe customers:
- when a users sign up your SaaS, you create a stripe customer and record stripe customer id in your internal users DB
- when a user tries to check out a payment/subscription, you create a stripe customer and do the recording as well.
It is highly suggested to make the creation of stripe customers (keyed by email) idempotent, i.e, one email lead to one and only one stripe customers so later on when your user signs in via Stripe customer portal with email, he can get all invoices.
----
Overall stripe DX is great, however stripe's product matrix is so big that lots of options a interleaved with each other, it feels like playing a game and then suddenly you found a hidden feature, but not fun and time consuming.