Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.flexprice.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Customer synchronization in Flexprice ensures that customers exist in Nomod before invoice sync and payment link. Customers are synced to Nomod when invoices are being synced, ensuring proper invoice-to-customer association in Nomod.

​
Key Concepts

  • Invoice- and Payment-Link-Triggered Sync: Customers are synced only when invoice sync or payment link is triggered
  • On-Demand Sync: Sync happens automatically during invoice sync
  • One-Way Sync: Customers are synced from Flexprice to Nomod only (not bidirectional)
  • Entity Integration Mapping: Links Flexprice customers to Nomod customer IDs
  • Metadata Storage: Customer metadata stores cross-platform references
  • Duplicate Prevention: Intelligent checks prevent duplicate customer creation in Nomod

​
Synchronization Flow

Customer sync is invoice- or payment-link-triggered and happens automatically:

​
When Customer Sync Happens

Customer sync is triggered only when:
  • An invoice is being synced to Nomod
  • A payment link is requested for an invoice
  • Invoice outbound sync is enabled in the Nomod connection (invoice_sync.outbound = true) when syncing invoices
  • Invoice status changes from DRAFT to FINALIZED (for invoice sync)
Customer sync does NOT happen for:
  • Manual customer operations
  • Other flows that do not involve invoice sync or payment link

​
Customer Data Model

​
Flexprice Customer Structure

{
  "id": "cust_1234567890abcdef",
  "name": "John Doe",
  "email": "john@example.com",
  "metadata": {
    "nomod_customer_id": "cust_nomod123abc",
    "nomod_sync_timestamp": "2024-01-20T10:30:00Z"
  },
  "environment_id": "prod",
  "tenant_id": "tenant_123",
  "status": "active",
  "created_at": "2024-01-20T10:30:00Z"
}

​
Sync Configuration

​
Required Fields for Sync

FieldFlexprice → NomodNotes
name✅Customer full name (required for Nomod customer creation)
email✅Primary email address (required for Nomod customer creation)

​
Optional Fields

FieldDescription
phonePhone number (E.164 format)
addressCustomer address information
external_idYour internal customer ID
metadataCustom key-value pairs

​
Sync Process Details

​
Customer Linking

​
Metadata Storage

Customer linking is maintained through metadata fields: In Flexprice Customer: 
{
  "metadata": {
    "nomod_customer_id": "cust_nomod123abc",
    "nomod_sync_timestamp": "2024-01-20T10:30:00Z"
  }
}
In Nomod Customer: 
{
  "metadata": {
    "flexprice_customer_id": "cust_1234567890abcdef",
    "flexprice_environment": "prod",
    "flexprice_sync_timestamp": "2024-01-20T10:30:00Z"
  }
}
You can verify customer links using the API: Endpoint: GET /api/v1/customers/{customer_id}/integrations Headers: 
Authorization: Bearer your_api_key
X-Tenant-ID: your_tenant_id
X-Environment-ID: your_environment_id
Response: 
{
  "customer_id": "cust_1234567890abcdef",
  "integrations": {
    "nomod": {
      "nomod_customer_id": "cust_nomod123abc",
    }
  }
}

​
Error Handling

​
Common Sync Errors

ErrorCauseResolution
”Customer not found”Invalid customer IDVerify customer exists in Flexprice
”Email already exists”Duplicate email in NomodCheck for existing customer in Nomod dashboard
”Invalid email format”Malformed email addressFix email format in Flexprice customer
”Missing required fields”Name or email missingEnsure customer has name and email in Flexprice
”Nomod API error”Nomod connection issueCheck Nomod connection credentials and status

​
Testing Customer Sync

​
Test Environment Setup

1

Use Nomod Test Mode

Configure Nomod connection with test API keys (sk_test_...)
2

Create Test Customers

Create test customers in Flexprice with name and email (no sync yet)
3

Verify No Initial Sync

Customers should NOT exist in Nomod initially

​
Invoice Sync Testing Flow

1

Create Test Customer

Add a customer in Flexprice with name and email (no sync yet)
2

Verify No Sync

Customer should NOT exist in Nomod initially
3

Enable Invoice Sync

Ensure invoice outbound sync is enabled in the Nomod connection
4

Create and Finalize Invoice

Create an invoice for the customer and finalize it (status changes to FINALIZED)
5

Verify Auto-Sync

Customer should now exist in Nomod with linked metadata (nomod_customer_id in Flexprice customer metadata)
6

Test Duplicate Prevention

Create another invoice for the same customer and verify it uses the existing Nomod customer (no duplicate created)