Stripe subscription webhooks missing metadata and client_reference_id

Question

I'm having issues linking stripe webhooks to customers, since I generally use the client_reference_id or metadata field, however subscription webhooks seem to not have these fields. For example the event checkout.session.completed does contain the client_reference_id, whereas invoice.paid does not.

NodeJS code to generate payment:

        const session = await stripe.checkout.sessions.create({
            payment_method_types: ['card'],
            line_items: [
            {
                price_data: {
                    currency: 'usd',
                    product_data: {
                        name: `Premium license`,
                    },
                    unit_amount: 600,
                    recurring: {
                        interval: "month",
                        interval_count: 1
                    },
                },
                quantity: 1
            }],
            subscription_data: {
                trial_period_days: 1,
            },
            metadata: { 'userId': userId },
            client_reference_id: userId,
            mode: 'subscription',
            customer_email: customerEmail,
            success_url: `...`,
            cancel_url: `...`,
        });

Answer 1

Yes, it's a major missing that there is no option to link between events. This becomes critical when you can't rely on the order of webhook events.

I did work around this using metadata though. Pass your own reference id, say, my_database_reference_id to the metadata of both checkout.session.create and also in the subscription_data in checkout creation. This can be the same value you pass inside client_reference_id. Now you can use this while listening to webhook, to connect between the checkout session and subscription object, irrespective of the order it comes in.

NB: Please be warned that metadata can be edited by the Stripe Account, so please be careful if you are a platform and relying on this for any logic.

Answer 2

The client_reference_id is a property of Checkout Session objects in Stripe, but not any other Stripe objects.

Subscription events (like customer.subscription.created) describe Subscription objects, and Invoice events (like invoice.paid) describe Invoices, neither of which are Checkout Sessions, so the property is missing.

Typically the way all of this is linked together is with the Customer object (cus_123) in Stripe, which should be present on all of the events mentioned in the customer property. Checkout will create the Customer object for you if you don't specify an existing one.