Stripe checkout wont accept metadata

Question

I have integrated Stripe checkout (the latest version) and need to send additional data so I can reconcile a later webhook.

Stripe rejects the metadata with the following error

Fatal error: Uncaught exception 'Stripe\Error\InvalidRequest' with message 'Received unknown parameter: metadata' 

My partially redacted code looks like this

$object = \Stripe\Checkout\Session::create([
    'success_url' => 'www/payment_processor.php?action=success',
    'cancel_url' => 'www/payment_processor.php?action=cancel',
    'payment_method_types' => ['card'],
    'customer_email' => $email,
    'metadata' => ['user_id' => $user_id],
    'line_items' => [[
        'amount' => $amount,
        'currency' => $currency,
        'name' => 'Purchase',
        'description' => $description,
        'quantity' => 1,
    ]]
]);

I expect the metadata to be accepted and returned with the webhook, as described in the Stripe documentation.

Answer 1

First sentence of the linked documentation states:

Updateable Stripe objects—including Account, Charge, Customer, PaymentIntent, Refund, Subscription, and Transfer —have a metadata parameter.

You are creating neither of those, you are creating a Session

Answer 2

Metadata must be nested in the Session creation object:

Stripe's docs incorrectly list metadata as a parent (https://stripe.com/docs/api/checkout/sessions/create) when in fact it's a child:

https://support.stripe.com/questions/using-metadata-with-checkout-sessions

1. payment_intent_data.metadata
2. subscription_data.metadata

client_reference_id is associated with the Session only, and does not get stored in Stripe as metadata.