Stripe and Paddle revenue setup
Connect Stripe or Paddle Billing, and each game sale, refund and subscription change becomes an event. Give the checkout the same player ID that your website or game sends, and the sale joins the player's visits, so attribution credits the campaigns that brought the buyer.
What you get
- A
purchaseevent for each payment and arefundevent with a negative amount for each refund. The channel isstripeorpaddle, which a website or a game cannot send, so these rows are verified payments. - Revenue in Overview, Activity, user profiles and the Revenue report, with gross, refunds and net.
- Revenue by source and campaign in Attribution, with the goal
purchase. - MRR and subscription status from subscription events.
Connect Stripe or Paddle
You need the owner or admin role and a verified MFA session.
- Open Settings, then Integrations. In the Stripe or the Paddle section, click Create webhook endpoint.
- Copy the endpoint URL into the webhook settings of your provider, and select the events in the next section.
- Copy the signing secret of the provider into Webhook signing secret and click Save signing secret. Ingestion starts.
- Optional: add a restricted Read API key to import past payments and to link Stripe refunds on newer API versions.
- Make a test purchase and a test refund in Stripe test mode or the Paddle sandbox, and check both rows in Activity.
Signing secrets and read keys are encrypted and never returned to the browser. Each webhook is checked against its signature. Other event types are acknowledged and ignored.
Webhook events to send
| Provider | Events |
|---|---|
| Stripe | invoice.paid, checkout.session.completed, checkout.session.async_payment_succeeded, charge.refunded, customer.subscription.created, customer.subscription.updated, customer.subscription.deleted |
| Paddle Billing | transaction.completed, adjustment.created, adjustment.updated, subscription.created, subscription.updated, subscription.canceled |
Which payments count
- Stripe invoices.
invoice.paidrecords the amount paid. This covers subscriptions, invoices you send, and Checkout with invoice creation on. - Stripe one-time Checkout. A Checkout Session or Payment Link in mode
paymentwith no invoice is recorded fromcheckout.session.completedwhen it is paid. A delayed payment method, such as a bank debit, is recorded fromcheckout.session.async_payment_succeeded. The amount is the session total. The record ID is the payment intent (pi_…). - Each sale counts once. A Checkout Session with an invoice is counted by
invoice.paid, and a subscription session by its invoices, so these sessions are skipped. Webhook retries and imports of the same payment keep one row. - Paddle.
transaction.completedrecords the grand total, for one-time and recurring sales.
Link each payment to a player
Use one opaque player ID, not an email, in your analytics and in the checkout. The payment links to a player in this order:
user_idin the metadata of the object the webhook reads. Stripe: the Checkout Session, the invoice, or the subscription (Stripe copies subscription metadata to each invoice). Paddle:custom_data.- For a Stripe Checkout Session with no metadata
user_id: itsclient_reference_id. On a Payment Link, this value comes from the URL, so the buyer can change it. When the player ID must come from your server, create the Checkout Session on your server and set metadatauser_id. - The identify trait
stripe_customer_idorpaddle_customer_id. A payment that arrives before the identify call links when the trait arrives.
A refund has no metadata of its payment, so it takes the player of the other records of the same provider customer, when they name exactly one player. A customer ID that matches more than one player stays unassigned. Email is never used to guess a match. Stripe metadata does not copy between objects, so put the ID on the object that the webhook reads.
// Server: a one-time sale of a supporter pack. No invoice is needed.
const session = await stripe.checkout.sessions.create({
mode: 'payment',
line_items: [{ price: 'price_supporter_pack', quantity: 1 }],
client_reference_id: 'player_8f3k2', // read when metadata has no user_id
metadata: { user_id: 'player_8f3k2' },
success_url: 'https://example.com/thanks',
});// Server: a subscription. Stripe copies this to each invoice.
await stripe.checkout.sessions.create({
mode: 'subscription',
line_items: [{ price: 'price_monthly_supporter', quantity: 1 }],
subscription_data: { metadata: { user_id: 'player_8f3k2' } },
success_url: 'https://example.com/thanks',
});// Browser: a Paddle Billing checkout for a soundtrack.
Paddle.Checkout.open({
items: [{ priceId: 'pri_soundtrack', quantity: 1 }],
customData: { user_id: 'player_8f3k2' },
});// Browser or game: the same player ID, so visits and the payment join.
await analytics.identify('player_8f3k2');
// Or link by the provider customer, when you know it.
await analytics.identify('player_8f3k2', { stripe_customer_id: 'cus_123' });How sales join campaigns
A payment has no page, source or device of its own. Attribution follows the player: the tagged visits, short link clicks and sessions of that player before the sale get the credit, with the model you choose. A buyer with no linked player is unattributed. UTM values that you store in metadata or custom_data are not read as a source.
Refunds
- Stripe:
charge.refunded. The amount is cumulative per charge, so a second partial refund replaces the first row. - Paddle: a refund adjustment counts only when its status is
approved. - Attribution takes a refund off the payment it refunds when the refund names it. Paddle refunds name their transaction. A Stripe refund names its invoice on API versions before 2025-03-31, or its payment intent for a one-time Checkout payment. On newer API versions, the payment is looked up with the read API key. With no read key, such a refund stays in the totals but is not taken off a campaign.
Currencies, taxes and fees
- Each payment keeps its currency. Reports use the project's reporting currency (USD by default) and convert with the European Central Bank reference rate of the payment day. Add
currency_mode=onlyto a report URL to count one currency without conversion. - Amounts are what the buyer paid, tax included: the Stripe amount paid or session total, and the Paddle grand total. Provider fees and Paddle earnings are not subtracted.
Import past payments
Add a restricted read key in the same section. The key is checked before it is saved.
| Provider | Read access |
|---|---|
| Stripe | Invoices, Charges (for refunds), Subscriptions, and Checkout Sessions. A key without Checkout Sessions imports the rest and skips one-time Checkout payments. |
| Paddle | Transactions, Adjustments, Subscriptions, and Discounts (for discounted MRR) |
A first import starts 7 days back, and you can choose an earlier start. Imports resume where they stopped. A completed import runs again every day with 7 days of overlap.
What is read today
| Data | Today |
|---|---|
| Stripe invoice.paid (subscriptions, invoices, Checkout with invoice creation on) | Yes. A purchase event with the amount paid |
| Stripe one-time Checkout Session or Payment Link with no invoice | Yes. A purchase event with the session total, from checkout.session.completed or async_payment_succeeded |
| Stripe payment_intent.succeeded with no Checkout Session and no invoice | Not yet. Use Checkout or a Payment Link, or turn on invoices |
| Stripe charge.refunded, full or partial | Yes. A refund event with a negative amount |
| Paddle Billing transaction.completed, one-time or recurring | Yes. A purchase event with the grand total |
| Paddle Billing refund adjustments | Yes, when the status is approved |
| Paddle Classic webhooks | Not yet. Paddle Billing only |
| Subscriptions: MRR and status | Yes. From the subscription events |
| UTM values stored in metadata or custom_data | Not yet as a source. The source comes from the player's own visits |
| Provider fees, Paddle earnings, payouts | Not yet. Amounts are what the buyer paid, tax included |
Frequently asked questions
Do I need to turn on Stripe invoice creation for one-time sales?
No. A paid one-time Checkout Session or Payment Link with no invoice is recorded from checkout.session.completed. If you turn on invoice creation, the sale is recorded once, from invoice.paid.
Which ID links a Stripe payment to a player?
user_id in the metadata of the object the webhook reads: the Checkout Session, the invoice, or the subscription (copied to each invoice). For a Checkout Session with no metadata user_id, the client_reference_id. You can also send the identify trait stripe_customer_id.
Does a refund reduce the campaign that got credit for the sale?
Yes, when the refund names the payment. Paddle refunds always do. A Stripe refund does on API versions before 2025-03-31. On newer versions, add the read API key so the payment can be looked up.
Are amounts converted to one currency?
Each payment keeps its currency. Reports convert to the report currency with the European Central Bank reference rate of the payment day, or count only one currency with currency_mode=only.
Can I import past payments?
Yes, with a read API key. A first import starts 7 days back. You can choose an earlier start date. Completed imports run again every day with 7 days of overlap, so late payments and refunds are caught.