Stripe

With the Stripe integration, you can:

Attribute payments and subscriptions collected through Stripe back to the install and ad campaign that drove them.
See Stripe revenue alongside your app-store revenue in Appstack.

To successfully connect Stripe, you must:

Have Owner/Admin access to an Appstack organization.

Have your own backend create the Stripe objects your app charges through (Checkout Sessions, Subscriptions, or PaymentIntents). This integration is server-side, and can’t be done from the app alone.

This page covers attaching the Appstack ID to your Stripe data. If you haven’t installed the Appstack app from the Stripe App Marketplace and connected your account to your organization yet, do that first. From Appstack, go to Integrations > Stripe.

Why this needs your backend

Every other Appstack integration reads a value your app’s SDK already has. Stripe is different: the objects that generate your revenue events (Customer, Subscription, Checkout Session) are created by your server, not by code running on the device. There’s no SDK hook that can reach them. Stripe also enforces this at the API level: it only returns an object’s metadata to requests made with your secret key. A publishable key (the kind that ships inside a mobile app) never sees it, even if you try. So this has to be implemented once, in whatever backend code creates your Stripe objects. The upside is that it’s a small amount of work. Attach the ID once, when the customer checks out, and Stripe carries it forward automatically for the life of that subscription. You never touch it again for that customer, including at renewal, a year later.

Connect to Stripe

Follow the steps to attribute your Stripe revenue:

Get the Appstack ID in your app

Read the Appstack ID on-device, the same way you would for any partner integration, and send it to your own backend along with whatever request kicks off checkout.This isn’t a new endpoint: your app already calls your own backend to create the Checkout Session, since only server-side code can hold a Stripe secret key. Add the Appstack ID as one more field on that existing request.

let appstackId = AppstackAttributionSdk.shared.getAppstackId()
// Send appstackId to your backend along with the checkout request.

val appstackId = AppstackAttributionSdk.getAppstackId()
// Send appstackId to your backend along with the checkout request.

const appstackId = await AppstackAttributionSdk.getAppstackId();
// Send appstackId to your backend along with the checkout request.

final appstackId = await AppstackAttributionSdk.instance.getAppstackId();
// Send appstackId to your backend along with the checkout request.

Attach it when you create the Checkout Session

Which parameter you use depends on what you’re selling. Use exactly the key name appstack_id: that’s what Appstack reads back out on our side.Subscriptions — set it under subscription_data.metadata. Stripe copies it onto the Subscription it creates, and from there onto every invoice that subscription ever generates, including renewals:

curl https://api.stripe.com/v1/checkout/sessions \
  -u "sk_live_...:" \
  -d mode=subscription \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "success_url=https://example.com/success" \
  -d "subscription_data[metadata][appstack_id]={{APPSTACK_ID}}"

const session = await stripe.checkout.sessions.create({
  mode: "subscription",
  line_items: [{ price: priceId, quantity: 1 }],
  success_url: "https://example.com/success",
  subscription_data: {
    metadata: { appstack_id: appstackId },
  },
});

session = stripe.checkout.Session.create(
    mode="subscription",
    line_items=[{"price": price_id, "quantity": 1}],
    success_url="https://example.com/success",
    subscription_data={"metadata": {"appstack_id": appstack_id}},
)

One-time payments — set it under payment_intent_data.metadata instead. Stripe copies it onto the PaymentIntent, and from there onto the resulting Charge:

curl https://api.stripe.com/v1/checkout/sessions \
  -u "sk_live_...:" \
  -d mode=payment \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "success_url=https://example.com/success" \
  -d "payment_intent_data[metadata][appstack_id]={{APPSTACK_ID}}"

const session = await stripe.checkout.sessions.create({
  mode: "payment",
  line_items: [{ price: priceId, quantity: 1 }],
  success_url: "https://example.com/success",
  payment_intent_data: {
    metadata: { appstack_id: appstackId },
  },
});

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

Using a Payment Link instead of your own backend? You won’t have server code running at click time, so use the client_reference_id URL parameter instead:The link has to be built dynamically in your app at open time, with the real ID inserted: a static link copied from the Stripe dashboard has nowhere to put a per-user value.

https://buy.stripe.com/your_link?client_reference_id=APPSTACK_ID_HERE

This only reaches the initial purchase, not renewals. See the note below.

Setting the top-level metadata on the Checkout Session is not enough: that only reaches the checkout.session.completed event. Use subscription_data.metadata or payment_intent_data.metadata so Stripe copies it onto the underlying object, or the ID won’t be there on any of the events that follow.

Why setting it once at checkout is enoughStripe takes an immutable snapshot of a subscription’s metadata onto every invoice it generates, for as long as that subscription exists. You don’t need to re-attach anything on renewal. Stripe does it automatically.

Payment Links carry lessclient_reference_id only reaches the checkout.session.completed event. It never propagates to invoices, so it can attribute the first purchase but not a subscription’s renewals. It also silently drops values with characters outside A-Za-z0-9-_, with no error, so double-check the ID reaches Stripe intact.

List of events

These are the raw Stripe events Appstack reads once your integration is set up. There’s no separate Appstack-specific naming for Stripe yet: you’ll see these under their normal Stripe names.

Name	Definition
`checkout.session.completed`	Fired once, when a customer finishes checking out. The ID set here reaches only this event; use the metadata parameters above for anything that needs to survive past this point.
`customer.subscription.created`	Fired when a new subscription starts. Carries the ID if `subscription_data.metadata` was set at checkout.
`invoice.paid`	Fired each time an invoice is successfully paid: the initial invoice and every renewal after it. This is where subscription revenue is read from.
`invoice.payment_failed`	Fired when a renewal attempt fails to charge the customer.
`customer.subscription.deleted`	Fired when a subscription is canceled or ends.
`charge.succeeded`	Fired for a one-time payment. Carries the ID if `payment_intent_data.metadata` was set. Does not carry it for a subscription’s renewal charges: read `invoice.paid` for those instead.

Troubleshooting

General tips

Set it server-side, not client-side. A publishable key can’t read or write metadata: attempting this from the app itself fails silently or is rejected by Stripe, depending on the call. It has to run wherever your backend creates the Checkout Session.
Use the indirect parameter, not the top-level one. subscription_data.metadata / payment_intent_data.metadata, not the Checkout Session’s own metadata field. See the warning above.
Use the exact key appstack_id. A typo or different casing means Appstack never finds it, with no error on either side.
Read invoices for subscription revenue, not charges. A subscription’s renewal charges don’t carry your metadata: only the invoice does.
Contact support: if issues persist, reach out with specific error messages at support@appstack.tech.

Common issues

Issue	How to fix
ID appears on `checkout.session.completed` but nowhere else	You set the Checkout Session’s top-level `metadata` instead of `subscription_data.metadata` / `payment_intent_data.metadata`. The top-level field never propagates past that one event.
ID is on the first invoice but missing from later renewals	Confirm you’re reading `parent.subscription_details.metadata` (or the equivalent field for your account’s API version) on the invoice, not the invoice’s own top-level `metadata`, which Stripe never populates from the subscription.
ID missing from `charge.succeeded` for a subscription payment	Expected. Renewal charges are created by Stripe, not by your backend, so there’s nothing for the metadata to copy from. Read `invoice.paid` instead.
ID missing after using a Payment Link	Check the `client_reference_id` value only contains letters, numbers, dashes, and underscores: anything else is dropped silently by Stripe, and note this path doesn’t cover renewals regardless.
Nothing arrives at all	Confirm the Appstack app is installed on this Stripe account and connected to your organization (Integrations > Stripe in Appstack): this metadata step only matters once events are already flowing.

Getting started

Mobile SDKs

Developer tools

Integrations

Products

API reference

Why this needs your backend

Connect to Stripe

List of events

Troubleshooting

General tips

Common issues

​Why this needs your backend

​Connect to Stripe

​List of events

​Troubleshooting

​General tips

​Common issues

Why this needs your backend

Connect to Stripe

List of events

Troubleshooting

General tips

Common issues