Skip to main content

Managing Stripe Customers

Open Admin → Stripe. The H1 is Stripe. The subtitle is Manage Stripe billing and customer relationships.

Do not paste Stripe secret keys into these docs.

Toolbar, left to right:

  1. Search placeholder Search by Customer ID, Name, or Email.... Filters the loaded table locally as you type (or Enter). It does not hit Stripe again. Matching also includes Subscription ID. The placeholder text is unchanged.
  2. Last billing snapshot is the label. The line under it shows live listing info, a snapshot timestamp, or No snapshot available.
  3. Create Snapshot is optional archive only. Do not click it to see billed customers.

Idle table: Loading Stripe customers.... Empty table after fetch: No Stripe customers found.

The only row click that opens a merchant is a green Linked name in FinMatch Merchant. Not linked is gray italic and does not open a merchant picker. Actions ⋯ does nothing today (connection manager is not loaded). Link from Merchants.

Viewing Customers​

  1. Navigate to Stripe from the main navigation
  2. The table loads automatically from paginated GET /api/customers (every live customer, not the newest 100). It refreshes about every 60 seconds while the tab is open. Older billed merchants (for example Access Training, cus_ST325wcTyLcFPv) appear on that live list. Do not click Create Snapshot to find them. Do not wait on a docs cache.
  3. Use the search bar to filter by Customer ID, Name, Email, or Subscription ID. Search still filters the loaded table locally; it does not hit Stripe again. The placeholder remains Search by Customer ID, Name, or Email....

Understanding the Table​

Customer Information​

Each row shows:

  • Customer ID - Unique Stripe identifier (e.g., cus_ABC123)
  • Name - Customer name or business name
  • Email - Primary contact email
  • Subscription Plan - Name of the active subscription plan
  • Status - Color-coded subscription status badge
  • Next Billing - Date of next billing cycle
  • Created - When the customer was created in Stripe

Subscription Status​

The status badge indicates the subscription state:

  • 🟢 Active - Subscription is active and billing normally
  • 🔴 Past Due - Payment failed, subscription needs attention
  • ⚫ Canceled - Subscription has been canceled
  • ⚪ None - Customer has no active subscription

The "FinMatch Merchant" column shows:

  • Linked - Clickable merchant name (green). That is the only row click that opens a merchant page.
  • Not linked - Gray italic text indicating no connection

The Actions ⋯ on this page does nothing today (connection manager is not loaded). Not linked does not open a merchant picker. Do not hunt for a customer-detail popup from the row. Link from Merchants.

Linking Customers to Merchants​

To link a Stripe customer to a FinMatch merchant:

  1. Open the merchant (Stripe Billing card Link, or merchants table "🔗 Link Customer"). James-only Settings preview: FinMatch Account → Stripe first row Link.
  2. Link Stripe Customer opens. Search by Customer ID, Name, Email, or Subscription ID. Ltd and LIMITED match as the same legal name. Confirm in the picker. Do not auto-link.
  3. After Link, billing hydrates from the live Stripe subscription (active / trialing → billing active). Unlink still marks billing inactive.

Once linked, the Stripe page will show the merchant name in the "FinMatch Merchant" column. Do not click Create Snapshot to load customers or to link them.

Searching Customers​

Use the search bar at the top of the Stripe page to quickly find customers:

  • Type part of a Customer ID (e.g., cus_ABC)
  • Type a customer name
  • Type an email address
  • Type a Subscription ID

The placeholder is still Search by Customer ID, Name, or Email.... The table filters in real-time as you type.

Last billing snapshot and Create Snapshot​

The table is a live paginated list (GET /api/customers), not a snapshot file. Opening Stripe loads that list and polls about every 60 seconds while the tab stays open. Stripe webhooks upsert one customer so a billing change can appear on the next poll. Last billing snapshot shows live listing info, a snapshot timestamp, or No snapshot available.

Create Snapshot writes an optional archive. The button label does not change. Do not click it to see billed customers. Do not keep pressing it. If you archive anyway, toast Creating snapshot..., then Snapshot created successfully! (with a parenthetical weekday and created_at when present). The table reloads from live GET /api/customers.

Failure: API message / error, or Failed to create snapshot. Please try again. 404 without JSON: Snapshot endpoint not found. The Stripe API service may need to be deployed with the latest code.

Do not use Create Snapshot to link merchants. Use Linking Stripe customers.

Common Tasks​

Finding a Customer by Email​

  1. Type the email address in the search bar
  2. The table filters to show matching customers
  3. If FinMatch Merchant is linked, click the merchant name to open that merchant. The row itself has no customer-detail view.

Checking Subscription Status​

  1. Look at the Status column for color-coded badges
  2. Green = Active, Red = Needs attention, Gray = Inactive
  3. Check Next Billing date for upcoming charges

Viewing Linked Merchants​

  1. Look for green clickable text in the "FinMatch Merchant" column
  2. Click the merchant name to navigate to the merchant details page
  3. Gray "Not linked" text means the customer isn't connected to any merchant

Troubleshooting​

Table Shows "Loading Stripe customers..."​

  • The idle cell is Loading Stripe customers..., not a bare Loading.
  • Check your internet connection
  • Verify the Stripe API service is running
  • Check browser console for errors

No Customers Showing​

  • Empty fetch copy is No Stripe customers found
  • Verify you have customers in your Stripe account
  • Check that the API is returning data
  • Ensure you're viewing the correct Stripe account (live vs test mode)

Subscription Data Missing​

  • Some customers may not have subscriptions
  • Check if the customer has an active subscription in Stripe Dashboard
  • Verify the API is returning expanded subscription data