Skip to main content

Managing Merchants

Open Merchants. The list is the home for add, open, delete, and Stripe Link Customer. Search, sort, environment, pagination, and row clicks: Merchants Overview.

Adding a New Merchant​

See Adding Merchants for the form, duplicate warning, and create toasts.

Quick steps:

  1. Click Add Merchant in the merchants toolbar
  2. Fill in Company Name, Domain, and optional fields
  3. Click Add Merchant on the form. The button shows Adding... while the create request runs.

Editing a Merchant​

See the Merchant Page Editing guide for the primary inline editing flow, including:

  • Editing merchant profile fields directly on the merchant page
  • FinMatch ID validation and uniqueness checks
  • Environment synchronization and integrity checks
  • Save/cancel behavior and API-backed persistence

Quick steps:

  1. Find the merchant in the table
  2. Click the merchant name (or "⋯" → "✏️ Edit")
  3. Click "Edit Merchant" in the page header
  4. Update the merchant information (including FinMatch ID if needed)
  5. Click "Save Changes". The header button shows Saving... while the update request runs.

Field validation and what Save writes: Editing Merchants.

Viewing Merchant Details​

  1. Find the merchant in the table
  2. Click the merchant name in the table (or "⋯" → "✏️ Edit")

The merchant page has four tabs: Overview, Enquiries, Analytics, and Admin. See Merchant Page Editing. Overview cards:

Collapsed Recent activity under those cards is the last 20 history events (same feed as Admin → History). See Merchant Page Editing.

Deleting a Merchant​

This removes the merchant record. It is not Terminate account on the Merchant Status card (that keeps the profile and blocks re-signup). Status clicks: Merchant Page Editing.

  1. Open the merchant detail page
  2. Click "Delete Merchant" in the page header
  3. Delete Merchant opens. It says This action cannot be undone!
  4. The list of files that will lose this merchant is merchants.json, merchant-router.json, and cors.json
  5. The field label is Type delete to confirm. Placeholder: Type 'delete' to confirm. Type delete.
  6. The red Delete Merchant button enables. It shows Deleting... while the delete request runs. Cancel closes without deleting.

Deletion is handled by DELETE /api/merchants/:id, which removes:

  • Merchant profile entry in merchants.json
  • Merchant routing entry in merchant-router.json
  • Merchant domains from cors.json

Searching and Filtering​

There is no Status filter on the merchants toolbar. Status is a table column only.

Search, Sort merchants, All Environments / Production / Staging / Test, Items per page, and Previous / Next: Merchants Overview.

Linking Stripe Customers​

Link or unlink from the merchant Stripe Billing card (Link / Unlink), or from the merchants table Stripe Customer column (Link Customer, or the linked customer id). James-only Settings preview (signed in as james@finmatch.io; not general operator chrome): FinMatch Account → Stripe first row is Link / Unlink (same words as the Stripe Billing card). It opens the same Link Stripe Customer picker. The merchants-table ⋯ menu is ✏️ Edit only (opens the merchant page). The Stripe page ⋯ and Not linked do not open a merchant picker.

Link Stripe Customer opens. Select Stripe Customer, then Search Customers. The search box placeholder is Search by Customer ID, Name, or Email.... Search also matches Subscription ID; the placeholder text is unchanged. Search treats Ltd and LIMITED as the same legal name, so ACCESS TRAINING (WALES) LIMITED prefills and matches Stripe Access Training (Wales) Ltd. A unique legal-name match sorts to the top. The operator still confirms in the picker. Do not auto-link.

The picker table columns are Customer ID, Name, Email, Subscription Plan, Status, FinMatch Merchant, and Action. Idle picker: Loading Stripe customers.... Empty picker: No Stripe customers found. Please load Stripe data first. That empty string is distinct from the Stripe page No Stripe customers found.

The picker uses the same live stripe-api list as the Stripe page: paginated GET /api/customers (every live customer, not the newest 100). Search filters that loaded list locally. Access Training (cus_ST325wcTyLcFPv) appears there without Create Snapshot. If they are missing, reload the Stripe tab — do not keep pressing Create Snapshot, and do not assume they are absent from Stripe.

Linking is a manual operator step. The join is only merchant.stripeCustomerId === the Stripe customer id.

After Link, merchant-api copies billing from the live Stripe subscription (active / trialing → billing active) so status is not stuck Suspended waiting for a webhook. If that fetch fails, the link still saves. Unlink still marks billing inactive.

Access Training is already merchant M273492. Do not create a second merchant. Path: Stripe tab → search Access Training → open M273492 → Link to cus_ST325wcTyLcFPv (confirm in the picker). Merchants-table search also matches Company Number (for example 04915118) even though the placeholder is still Search by Merchant ID, Company Name, or URL....

Once linked, the Stripe Customer column shows the customer ID as a clickable link. The same columns appear on the Stripe page.

Next Steps​