Skip to content
CostReveal
Menu

Connecting Stripe to CostReveal, setup guide

The CostReveal team, , 6 minute read

Knowing what a customer costs to serve is half of the margin question. The other half is what they pay you. This guide covers how CostReveal reads what your customers were billed in Stripe, which records count as revenue and which do not, how revenue is matched to the same customers your costs name, each setup step, and where margin by customer appears.

What the Stripe connection reads

CostReveal reads what your customers were billed in Stripe, and sets it against what serving each of them cost. Revenue is kept apart from spend: it never changes a cost figure.

Three kinds of record count as revenue:

  • Invoices that are open or paid, excluding tax. Drafts, voided and uncollectible invoices are not revenue.
  • Credit notes that are issued, taken off the revenue of the customer they were for.
  • Charges that succeeded without paying an invoice, less what was refunded. A charge that paid an invoice is already that invoice's revenue, so it is never counted twice.

Each is dated when Stripe created it, in its own currency, exactly, by Stripe's own minor unit for that currency. CostReveal never reads payment method details.

Matching revenue to customers

This is the step that makes margin by customer work. Revenue is matched to customers the same way costs are: by a Stripe customer's metadata, read with your project's tag keys for customers, such as customer, client or tenant.

A Stripe customer whose metadata says customer = globex is the same customer as resources tagged customer = globex, or calls your usage data names for globex. So the revenue and the cost of serving globex meet on one row.

Revenue of a customer with no such metadata is shown as not mapped, never guessed from a name. Add the metadata in Stripe, or change your project's tag keys to the key your metadata already uses, and revenue is matched again at once.

What you need

  • Access to the Stripe Dashboard, to create a restricted key.
  • Customer metadata in Stripe that names each customer the way your costs do, or a project tag key that matches the metadata you already have.
  • An owner or admin role in CostReveal.

Step by step setup

1. Start the connection

In CostReveal, go to Connections and choose Connect next to Stripe.

2. Create a restricted key

In the Stripe Dashboard, under Developers, API keys, create a restricted key with Read access to Invoices, Credit notes, Charges and Customers, and nothing else. A secret key is refused, so CostReveal never holds a key that could change anything.

3. Enter the key and verify

Enter the key and choose Verify and connect. Only the format is checked as you type. When you verify, CostReveal reads this month's invoices, credit notes and charges before saving anything.

The key is stored encrypted and never shown again. Deleting it in Stripe ends access at once.

4. Check customer metadata

Open Business, under Customers, and look for revenue shown as not mapped. Add metadata to those customers in Stripe, using a key your project reads, or add your existing metadata key to the project's tag keys.

Freshness and history

Stripe states revenue as invoices are made. CostReveal reads every six hours, so revenue trails by up to six hours. The first read brings in the current month and the twelve before it; after that, each read covers the current and previous month.

Connection states

Under Connections, the connection is always in one of four states:

  • Setup not finished: the key has not been verified yet.
  • Waiting for first data: the key was verified, and the first read is due.
  • Connected: revenue was read and the latest read succeeded.
  • Needs attention: the latest read failed, for example because the key was deleted. Everything already read is kept.

Revenue and margin

Home shows the period's gross margin, once Stripe brings revenue in. Business, under Customers, shows the period's revenue, its cost and its gross margin, and each customer's revenue, cost and margin. Cost that no customer explains yet is its own row, never spread across customers, so a margin is never flattered by hiding cost.

Each customer's cost carries its evidence, as every figure does: some of it measured or tagged, some allocated, and some still unknown. That tells you how firm each margin is.

How revenue is checked

Revenue is recorded exactly as Stripe states it, by Stripe's minor unit for each currency. A record Stripe changes later, such as an invoice voided or a refund issued, is recorded as a correction that keeps what was said before. Stripe is a revenue source, so it is never added to spend, and spend checks are unaffected by it.

Getting the most from margin by customer

  1. Use one customer key everywhere. Name customers the same way in Stripe metadata, resource tags and usage data.
  2. Map every customer with revenue, so none is shown as not mapped.
  3. Send usage data for shared AI spend, so the cost of serving each customer includes the AI calls made for them.
  4. Review cost explained by no customer in Business, and shrink it with tags or rules.

Troubleshooting

  • Verify refuses the key. Use a restricted key with Read on Invoices, Credit notes, Charges and Customers. A secret key is refused.
  • Revenue shows as not mapped. Add customer metadata with a key the project reads, or add your metadata key to the project's tag keys.
  • A charge seems missing. A charge that paid an invoice is counted as that invoice's revenue, once.
  • Tax appears in revenue. It does not: invoices count excluding tax.

Using Stripe figures in CostReveal

Stripe brings revenue, which CostReveal keeps apart from spend:

  • Never in spend. Stripe figures never appear in spend totals, Explore, budgets, anomalies or forecasts, so connecting Stripe can never change what a team or customer is shown to cost.
  • Beside cost, by customer. Home shows the period's gross margin, and Business, under Customers, shows each customer's revenue, cost and margin, with cost explained by no customer yet as its own row.
  • Firm or tentative. Each customer's cost keeps its evidence, so a margin built mostly on allocated or unknown cost reads as less firm than one built on tagged cost.
  • A worked example. Suppose globex's resources are tagged customer = globex, and its Stripe customer's metadata says the same. Its revenue and the cost of serving it meet on one row, and the margin moves as either changes.

Security and access

  • What CostReveal holds. The restricted key, with Read on Invoices, Credit notes, Charges and Customers. It is encrypted with AES-256-GCM before it is stored, under keys that can be rotated, and it is never shown again after you enter it.
  • What it is used for. Reading only. CostReveal never changes anything in your account.
  • Who can change the connection. Only owners and admins in CostReveal can connect, change or remove a connection, and each of those actions is recorded in the organization's audit log, with who did it and when.
  • Isolation. Every figure is stored in CostReveal's database with your organization isolated by PostgreSQL row level security, enforced in the database itself, below the application.
  • Ending access. Delete the key in Stripe. CostReveal keeps every figure already read and says that new data has stopped.

Removing the connection

Removing the connection under Connections deletes every figure it brought in from the project. Delete the key in Stripe too. To stop reading without removing anything, delete the key: CostReveal keeps every figure already read and tells you new data has stopped.

Frequently asked questions

Does Stripe revenue change my cost figures? No. Revenue is kept apart from spend and never changes a cost figure. It is set beside cost for margin.

What counts as revenue? Open or paid invoices excluding tax, less issued credit notes, and succeeded charges that did not pay an invoice, less refunds.

How does CostReveal know which customer revenue belongs to? From the Stripe customer's metadata, read with the project's customer tag keys. Without it, revenue is shown as not mapped.

Which key does CostReveal need? A restricted key with Read on Invoices, Credit notes, Charges and Customers. A secret key is refused.

Does CostReveal see card details? No. It reads invoices, credit notes, charges and customers, never payment method details.

Where do I see margin by customer? Under Business, Customers, with each customer's revenue, cost and margin, and on Home as the period's gross margin.

Keep reading

More setup guides