Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Payments and webhooks

Metadata you set on a Stripe Checkout Session is empty when you read it

Errormetadata is {} on payment_intent.succeeded after setting it on the Checkout Session

Short answer

Stripe does not copy metadata between objects on its own. Metadata set on a Checkout Session stays on the session; the PaymentIntent behind it only gets metadata you pass in payment_intent_data.metadata. Read it from the checkout.session.completed event, or set it on the PaymentIntent too, and use a secret key when you retrieve it, because client-side keys get metadata redacted.

  • Applies to Stripe API 2026-10-28, stripe-python, Flask 3, Python 3.12
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the type of every event your webhook receives and the metadata it carries. The event type tells you which object you are reading, and whether you set metadata on that object.

    @app.post("/webhook")
    def webhook():
        event = stripe.Webhook.construct_event(
            request.data, request.headers["Stripe-Signature"], WEBHOOK_SECRET)
        print(event["type"], dict(event["data"]["object"].get("metadata", {})))
        return "", 200
  2. 2Match what you see, then jump to its fix

    1. 1checkout.session.completed shows your keys; payment_intent.succeeded or charge.succeeded shows {}.Metadata was set on the session, but you read it from the PaymentIntent or chargeFix
    2. 2The log shows only payment_intent.* or charge.* events, never checkout.session.completed.The handler is not subscribed to checkout.session.completedFix
    3. 3Retrieving the same session on the server shows the metadata, but a client-side call does not.You retrieve the session with a publishable keyFix

What does the error look like?

  • metadata is {} on payment_intent.succeeded after setting it on the Checkout Session
  • event.data.object.metadata.order_id is None in the webhook handler

Cause 1 of 3

Metadata was set on the session, but you read it from the PaymentIntent or charge

1Check

An object's metadata is not copied to related objects. Stripe only copies in a few listed cases (PaymentIntent to Charge, Payment Link to Checkout Session, and similar). Checkout Session to PaymentIntent is not one of them unless you use payment_intent_data.

grep -n "metadata" app.py

2Fix

Either read the metadata from the checkout.session.completed event, or also set it on the PaymentIntent that the session creates (payment_intent_data.metadata; for subscriptions use subscription_data.metadata).

session = stripe.checkout.Session.create(
    mode="payment",
    line_items=[{"price": PRICE_ID, "quantity": 1}],
    success_url="https://example.com/success",
    metadata={"order_id": "6943"},
    payment_intent_data={"metadata": {"order_id": "6943"}},
)

3Verify

Pay with a test card and look at both events.

stripe listen --forward-to localhost:4242/webhook

Confirmed by docs.stripe.com

Did this fix it?

Cause 2 of 3

The handler is not subscribed to checkout.session.completed

1Check

Stripe sends the session's metadata inside the checkout.session.completed event, and only to endpoints configured to receive that event type.

stripe listen --forward-to localhost:4242/webhook

2Fix

Add checkout.session.completed to the endpoint's enabled events and branch on event type in the handler.

if event["type"] == "checkout.session.completed":
    session = event["data"]["object"]
    order_id = session["metadata"]["order_id"]

3Verify

Create a test session and complete it; the handler logs the order id.

stripe trigger checkout.session.completed

Confirmed by docs.stripe.com

Did this fix it?

Cause 3 of 3

You retrieve the session with a publishable key

1Check

Stripe returns metadata only for requests made with a secret key. Requests with a publishable key, such as Stripe.js or mobile SDK calls, get it redacted.

grep -rn "pk_" static/ templates/ app.py

2Fix

Retrieve the session in your Flask route with your secret key and send the browser only what it needs.

stripe.api_key = os.environ["STRIPE_SECRET_KEY"]
session = stripe.checkout.Session.retrieve(session_id)
print(session["metadata"])

3Verify

Call the route and check that the metadata keys are present.

curl -s http://localhost:5000/session/cs_test_123

Confirmed by docs.stripe.com

Did this fix it?

How do I stop it coming back?

  • Keep metadata small: Stripe allows 50 keys, key names up to 40 characters and values up to 500 characters. Store a database id, not the whole order.
  • Decide per integration which object holds the id you need, and read from that object only.
  • Never put card or bank details in metadata.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Payments

Stripe Elements shows console warnings or errors in a Next.js checkout

Could not find Elements context; You need to wrap the part of your app that calls useElements() in an <Elements> provider.

Most React Stripe.js warnings come from four mistakes: calling loadStripe inside a component, using useStripe or useElements outside the Elements provider, using the objects before they have loaded, and a Content Security Policy that blocks js.stripe.com.

4 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.