Skip to main content

​
Overview

Customer synchronization in Tirdad 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 Tirdad to Nomod only (not bidirectional)
  • Entity Integration Mapping: Links Tirdad 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

​
Tirdad 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

FieldTirdad → 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 Tirdad Customer: 
{
  "metadata": {
    "nomod_customer_id": "cust_nomod123abc",
    "nomod_sync_timestamp": "2024-01-20T10:30:00Z"
  }
}
In Nomod Customer: 
{
  "metadata": {
    "tirdad_customer_id": "cust_1234567890abcdef",
    "tirdad_environment": "prod",
    "tirdad_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 Tirdad
”Email already exists”Duplicate email in NomodCheck for existing customer in Nomod dashboard
”Invalid email format”Malformed email addressFix email format in Tirdad customer
”Missing required fields”Name or email missingEnsure customer has name and email in Tirdad
”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 Tirdad 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 Tirdad 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 Tirdad customer metadata)
6

Test Duplicate Prevention

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