> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.pivotal.app/llms.txt.
> For full documentation content, see https://docs.pivotal.app/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pivotal.app/_mcp/server.

# Connect Stripe

Stripe owns the billing truth. Once connected, Pivotal mirrors every Stripe subscription onto the matching customer and surfaces MRR, current plan, and payment status in the customer header. Your CSMs see "Plan: Growth, MRR \$1,400, payment failing" without opening Stripe.

The match key is the customer's `domain` field. Pivotal looks at each Stripe customer's email, takes the part after the `@`, and joins it to a Pivotal customer with that domain. Stripe customers on personal email domains (gmail, outlook, icloud) are skipped by default. Flip the **Match personal emails** toggle if you want them in.

## Wire it up

Go to **Admin > Integrations > Stripe** and click **Connect Stripe**.

Stripe opens its consent screen. Pivotal asks for read access on Customers, Subscriptions, Invoices, and Payment Intents. Pick the Stripe account and click **Connect**. Live mode and test mode are separate connections. Connect both if you want test data on staging customers.

Default scope is **All active subscriptions**. You can narrow this to specific products or specific Stripe lookup keys if you bill multiple companies out of one Stripe account.

Click **Run initial sync**. Pivotal walks every Stripe subscription matching the scope and writes them to customers by domain. The integration page shows matched, unmatched, and skipped counts when it finishes.

## What lands on the customer

| Pivotal field        | Source in Stripe                                                      | Notes                                                           |
| -------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------- |
| `plan`               | `subscription.items[0].price.lookup_key` (falls back to product name) | Pick a price lookup key like `growth_monthly` for clean labels. |
| `mrr`                | Sum of all active subscriptions, normalized to monthly USD            | Quarterly and annual plans divide by 3 and 12.                  |
| `payment_status`     | Most recent `invoice.status` on the customer                          | One of `paid`, `past_due`, `failing`, `none`.                   |
| `billing_started_at` | Earliest `subscription.start_date`                                    | Used for tenure calculations and the health score.              |
| `stripe_customer_id` | `customer.id`                                                         | Shown on the customer page footer with a deep link to Stripe.   |

## Read-only by design

Pivotal never writes to Stripe. There is no path to cancel a subscription, refund an invoice, or change a price from inside Pivotal. If you want billing actions on a customer page, build them with a [webhook](/product/integrations/webhooks) that points at your own backend.

## Gotcha: domain collisions

If two Stripe customers share a domain (a parent company and a subsidiary on the same email), Pivotal merges their MRR onto one Pivotal customer. The integration page flags these as **Ambiguous matches** so you can decide which Stripe customer wins, or split the Pivotal customer into two.

## Related

* [HubSpot integration](/product/integrations/connect-hubspot)
* [Health score](/product/customers/health-score)
* [Troubleshoot sync](/product/integrations/troubleshoot-sync)

Email **[help@pivotal.app](mailto:help@pivotal.app)** with a screenshot of where you got stuck and the customer or onboarding id from the URL.