Connect and verify revenue

Connect Stripe for a website or SaaS

Open Apps, choose your app, then Revenue. Choose Stripe. In your own Stripe Dashboard, create a restricted API key with Read access to Charges, Refunds and Subscriptions, plus account details if your permission setup requires it. Leave all write permissions off. Paste it only into Macaron’s password field, confirm the read-only permissions and whole-account scope, then choose Connect and import. Full sk_ secret keys and public keys are rejected. Stripe does not expose the key’s complete permission configuration here, so the read-only setting is your confirmation; Macaron’s importer itself makes GET requests only. Test-mode keys are accepted and clearly labeled as test transactions, never real revenue.

Understand Stripe scope

A Stripe key authorizes an account, not one product. This first connection imports the whole account, including other products, services and currencies in it. The source account name and ID are shown above the totals. Confirm that this is the scope you want; use a separate payment account if you need a strict product boundary. The same account and environment cannot be connected to two apps in one Macaron workspace. No product-specific revenue split or currency conversion is inferred.

Connect RevenueCat for mobile apps

Choose RevenueCat, create a V2 secret API key in Project settings → API keys, and set Projects Configuration and Charts & Metrics to Read only. Leave customer information and write access off. Enter the project ID, confirm the permissions and project scope, and connect. Macaron calls only the project, overview metrics and aggregate revenue endpoints. Revenue and MRR cover the whole selected project, which can contain several apps. Metrics are production data; provider delays and definitions apply. RevenueCat converts the requested financial metrics to USD.

Read the numbers

Stripe captured payments and successful refunds use their own creation dates over the last 30 UTC calendar days including today. Refunds can refer to older payments. Captured less refunds includes tax but does not subtract processor fees or disputes; it is not profit or payouts. Each currency is shown separately. The monthly recurring estimate normalizes active fixed-price subscription items before discounts and tax. It excludes trials, past-due, metered, tiered and custom prices; it is not Stripe’s reported MRR. Scheduled cancellations remain active until they end and are not a churn rate. Paying-customer counts use Stripe customer IDs and omit guest payments without an ID. RevenueCat supplies its own revenue and MRR values; missing metrics stay unavailable.

Refresh, errors and disconnection

The first import starts after connection. Connected providers are refreshed about hourly, and Sync now can start a refresh after a one-minute cooldown. Import time and provider update time are shown separately. Each Stripe endpoint is bounded to 20 pages; reaching the bound displays an incomplete import rather than a complete total. Failed refreshes preserve the last successful import and show an error. Invalid or under-permissioned keys require replacement before automatic refresh resumes. Disconnect stops imports and removes the encrypted key while keeping the last imported totals labeled as saved data. Revoke the key in the provider dashboard to invalidate it there too.

Keep keys and financial data private

Credentials are encrypted with Macaron’s existing server encryption and isolated from coding-agent keys, terminals and integration tools. They participate in master-key rotation and are never returned by the revenue API. Do not put provider keys into a website snippet, mobile app, screenshot, source repository, report, chat or model prompt. The dashboard stores source identifiers and aggregate financial metrics, not customer emails, card details or raw transaction payloads. Stripe returns transaction objects for calculation; their customer details are discarded rather than saved. Only the app owner can access this connection; support teammates do not automatically gain financial access. Nothing is published to a public profile.

Optional: link a one-time payment to a support offer

No website snippet or app SDK is required for the revenue import itself. To correlate one-time Stripe Checkout payments with support, validate the conversation/action context in your existing server checkout flow and add these tags to both Checkout metadata and payment_intent_data.metadata. The latter makes them available on the resulting payment/charge. Macaron counts a tagged captured payment only when the app, conversation and opened upgrade action match its owned support records. The tagged amount is captured gross before refunds and is not proof that support caused the purchase. Subscription renewals are not attributed by this one-time example. Keep your existing trusted Stripe client, checkout validation and payment fulfillment.

const tags = {
  macaron_app_id: appId,
  macaron_conversation: conversationId,
  macaron_action: actionId,
};

// In your existing server-side one-time checkout handler:
const session = await stripe.checkout.sessions.create({
  ...validatedCheckoutOptions,
  mode: "payment",
  metadata: { ...validatedCheckoutOptions.metadata, ...tags },
  payment_intent_data: {
    ...validatedCheckoutOptions.payment_intent_data,
    metadata: {
      ...validatedCheckoutOptions.payment_intent_data?.metadata,
      ...tags,
    },
  },
});