It took me a while to wrap my head around the 3 different options to integrate for Stripe, especially as our own implementation combines Checkout and API (Customers) - and then the differences were super easy to confuse. Maybe this helps you to clarify the documentation:
-
One confusing thing was just which fields were required, and how they help Dub to figure things out:
- For Option 1:
dub_id → client_reference_id on the checkout session → checkout.session.completed webhook delivers it to Dub.
- For Option 2:
dub_id → passed as clickId in the server-side dub.track.lead({ clickId, customerExternalId, ... }) call. Dub stores the click ↔ customer association in its own database, not in Stripe. Then on Stripe's side, only metadata.dubCustomerExternalId is set on the checkout session. When checkout.session.completed fires, Dub sees that metadata, looks up customerExternalId in its DB, and finds the previously-recorded click. For recurring invoice.paid events, Dub goes Stripe customer ID → customerExternalId (previously backfilled) → click.
- For Option 3:
dub_id → metadata.dubClickId on the created Stripe customer, alongside metadata.dubCustomerExternalId. The customer.created / customer.updated webhook delivers both to Dub, which records the lead and the click ↔ customer association. Then invoice.paid events get attributed via the customer's stored metadata.
This way, it is also clear that even though we use Stripe Checkout in some cases, as we created the Stripe Customer earlier via API, there is no need to trigger another dub.track.lead() (which would probably just lead to a duplicate lead).
-
The second confusing thing was just "Stripe Customers". That term I would use more for the Stripe side customer object, and that exists for all three options in the end. "Server-side Stripe" or "Stripe API" would probably be easier to match against the actual implementation.
-
"Tracking free trials" would also benefit from having the webhook or fired event mentioned. There I can only assume how it really works.
With these three points taken into account, the Stripe integration docs could be much clearer.
It took me a while to wrap my head around the 3 different options to integrate for Stripe, especially as our own implementation combines Checkout and API (Customers) - and then the differences were super easy to confuse. Maybe this helps you to clarify the documentation:
One confusing thing was just which fields were required, and how they help Dub to figure things out:
dub_id→client_reference_idon the checkout session →checkout.session.completedwebhook delivers it to Dub.dub_id→ passed asclickIdin the server-sidedub.track.lead({ clickId, customerExternalId, ... })call. Dub stores the click ↔ customer association in its own database, not in Stripe. Then on Stripe's side, onlymetadata.dubCustomerExternalIdis set on the checkout session. Whencheckout.session.completedfires, Dub sees that metadata, looks upcustomerExternalIdin its DB, and finds the previously-recorded click. For recurringinvoice.paidevents, Dub goes Stripe customer ID →customerExternalId(previously backfilled) → click.dub_id→metadata.dubClickIdon the created Stripe customer, alongsidemetadata.dubCustomerExternalId. Thecustomer.created/customer.updatedwebhook delivers both to Dub, which records the lead and the click ↔ customer association. Theninvoice.paidevents get attributed via the customer's stored metadata.This way, it is also clear that even though we use Stripe Checkout in some cases, as we created the Stripe Customer earlier via API, there is no need to trigger another
dub.track.lead()(which would probably just lead to a duplicate lead).The second confusing thing was just "Stripe Customers". That term I would use more for the Stripe side customer object, and that exists for all three options in the end. "Server-side Stripe" or "Stripe API" would probably be easier to match against the actual implementation.
"Tracking free trials" would also benefit from having the webhook or fired event mentioned. There I can only assume how it really works.
With these three points taken into account, the Stripe integration docs could be much clearer.