Skip to main content

Merchant Page Editing

Complete guide to editing merchants directly on the merchant detail page.

Overview​

The merchant detail page (/admin/merchants/{merchantId}) is now the primary interface for viewing and editing merchant information. The edit modal has been removed, and all editing happens inline on the merchant page.

Accessing the Merchant Page​

From Merchants Table​

  1. Click Company Name: Click on any merchant's company name in the merchants table
  2. Actions Menu: Click the "⋯" (three dots) button → "✏️ Edit"

From Other Pages​

  • Stripe Page: Click on linked merchant name to navigate to merchant page
  • Direct URL: Navigate to /admin/merchants/{merchantId} (e.g., /admin/merchants/M000101)

Merchant Page Structure​

The merchant page displays information in cards:

  1. Merchant Information - ID, company name, company number, domain, CreditSafe link
  2. Stripe Billing - Customer ID, name, email, phone, address, billing status (with Link/Unlink button)
  3. Contact Information - Contact type, name, email, phone
  4. Lender Configuration - Enabled lenders and credit products
  5. App Settings - Environment, snippet code, deployment status, features

Inline Editing​

Enabling Edit Mode​

  1. Navigate to the merchant page
  2. Click the "Edit Merchant" button at the bottom
  3. Fields in the Merchant Information card become editable
  4. Button changes to "Save Changes"
  5. A "Cancel" button appears

Editing Fields​

When in edit mode, the following fields become editable:

  • Company Name - Text input
  • Domain - URL input (automatically adds https:// if missing)
  • Company Number - Text input (optional)

Note: Merchant ID can be edited. Changes are validated and processed via the merchant ID change flow.

Saving Changes​

  1. Make your edits
  2. Click "Save Changes"
  3. Changes are validated and saved to the API
  4. Page refreshes with updated data
  5. Edit mode exits automatically

Canceling Edits​

  1. Click "Cancel" button
  2. All changes are discarded
  3. Page reverts to read-only view
  4. Original data is restored

Stripe Billing Management​

The Stripe Billing card has a Link/Unlink button in the header:

  • "Link" - Shows when no Stripe customer is linked
  • "Unlink" - Shows when a Stripe customer is already linked (green background)

Linking a Stripe Customer​

  1. Click "Link" button in Stripe Billing card header
  2. Modal opens showing all Stripe customers
  3. Search by Customer ID, Name, or Email
  4. View customer details:
    • Customer ID
    • Name
    • Email
    • Subscription Plan
    • Current FinMatch Merchant (if linked)
  5. Click "Link" button next to desired customer
  6. Connection is saved to merchants.json
  7. Page refreshes showing linked customer

Unlinking a Stripe Customer​

  1. Click "Unlink" button in Stripe Billing card header
  2. Confirm the action
  3. Connection is removed from merchants.json
  4. Page refreshes showing "Not linked" status

Universal Card Editing Layer​

The merchant page uses a universal editing layer that can be extended to other cards:

Current Support​

  • ✅ Merchant Information card - Full inline editing
  • ⏳ Stripe Billing card - Link/Unlink functionality
  • ✅ Contact Information card - Inline editing (saved through Contacts API sync)
  • ⏳ Lender Configuration card - Coming soon
  • ✅ App Settings card - Environment integrity check + snippet checks

Future Expansion​

Each card can independently enable edit mode, allowing granular control over what can be edited.

Side Navigation​

The side navigation works correctly on merchant detail pages:

  • Dashboard → ../../
  • Merchants → ../../merchants/
  • Stripe → ../../stripe/
  • Lenders → ../../lenders/
  • Analytics → ../../analytics/
  • Documentation → ../../docs/

Navigation automatically detects merchant detail pages and adjusts paths accordingly.

The breadcrumb shows:

  • Merchants → {Merchant Name}

Clicking "Merchants" returns to the merchants table.

API Integration​

Update Merchant​

Endpoint: PUT /api/merchants/{merchantId}

Request Body:

{
  "merchantName": "Updated Company Name",
  "companyName": "Updated Company Name",
  "domain": "https://updated-domain.com",
  "companyNo": "12345678"
}

Response: Updated merchant object

Endpoint: PUT /api/merchants/{merchantId}/stripe-connection

Request Body:

{
  "stripeCustomerId": "cus_xxxxx"
}

Response: Updated merchant object with Stripe connection

Endpoint: DELETE /api/merchants/{merchantId}/stripe-connection

Response: Updated merchant object without Stripe connection

Best Practices​

  1. Always Save: Click "Save Changes" after editing, or "Cancel" to discard
  2. Validate Domain: Domain is automatically normalized (adds https:// if missing)
  3. Check Stripe Status: Verify Stripe customer is correctly linked before saving
  4. Use Search: Use search in Stripe linking modal to find customers quickly
  5. Review Changes: Page refreshes after save - verify changes are correct

Troubleshooting​

Edit Mode Not Working​

Check:

  1. Merchant page is loaded (window.currentMerchantDetails exists)
  2. JavaScript console for errors
  3. Network tab for API call failures

Check:

  1. Stripe customers are loaded (stripeCustomers array exists)
  2. API endpoint is accessible
  3. Merchant ID is correct

Check:

  1. URL path includes merchant ID (e.g., /admin/merchants/M000101)
  2. nav-builder.js is loaded
  3. Navigation uses ../../ for merchant detail pages