> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Merge Customers

> This endpoint merges duplicate customer records into a single primary record.

### Body

<ParamField body="primary_customer_id" type="string">
  The customer ID that will be kept as the primary record
</ParamField>

<ParamField body="duplicate_customer_ids" type="array">
  Array of customer IDs to be merged into the primary record
</ParamField>

<ParamField body="merge_strategy" type="object">
  Strategy for handling conflicting data during merge

  <Expandable title="properties">
    <ParamField body="contacts" type="string">
      How to merge contact info: "primary\_only", "merge\_all", "most\_recent"
    </ParamField>

    <ParamField body="orders" type="string">
      How to handle orders: "transfer\_all", "keep\_separate"
    </ParamField>

    <ParamField body="addresses" type="string">
      How to merge addresses: "primary\_only", "merge\_unique", "keep\_all"
    </ParamField>

    <ParamField body="preferences" type="string">
      How to merge preferences: "primary\_only", "merge\_all", "most\_recent"
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="reason" type="string">
  The reason for merging these customer records
</ParamField>

### Response

<ResponseField name="id" type="string">
  The ID of the primary customer record after merge
</ResponseField>

<ResponseField name="merged_customer_ids" type="array">
  Array of customer IDs that were merged
</ResponseField>

<ResponseField name="merge_summary" type="object">
  Summary of what was merged

  <Expandable title="properties">
    <ResponseField name="orders_transferred" type="number">
      Number of orders transferred
    </ResponseField>

    <ResponseField name="addresses_merged" type="number">
      Number of addresses merged
    </ResponseField>

    <ResponseField name="contacts_merged" type="number">
      Number of contacts merged
    </ResponseField>

    <ResponseField name="total_lifetime_value" type="number">
      Combined lifetime value of all merged customers
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="conflicts_resolved" type="array">
  List of conflicts that were resolved during merge
</ResponseField>

<ResponseField name="merged_at" type="string">
  Timestamp when the merge was completed
</ResponseField>

<ResponseField name="merged_by" type="string">
  User who performed the merge
</ResponseField>

<ResponseField name="success" type="boolean">
  Indicates whether the merge was successful
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --location --request POST 'https://api.stateset.com/v1/customers/merge' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Token <token>' \
  --data-raw '{
      "primary_customer_id": "cust_primary_123",
      "duplicate_customer_ids": ["cust_dup_456", "cust_dup_789"],
      "merge_strategy": {
          "contacts": "merge_all",
          "orders": "transfer_all",
          "addresses": "merge_unique",
          "preferences": "most_recent"
      },
      "reason": "Duplicate accounts identified during data cleanup"
  }'
  ```

  ```graphQL GraphQL theme={null}
  mutation customerMergeMutation {
    customerMerge(
      primaryCustomerId: "${primaryCustomerId}",
      duplicateCustomerIds: ${duplicateCustomerIds},
      mergeStrategy: ${mergeStrategy},
      reason: "${reason}"
    ) {
      customer {
        id
        email
        merge_summary {
          orders_transferred
          addresses_merged
          total_lifetime_value
        }
      }
      userErrors {
        field
        message
      }
    }
  }
  ```

  ```js Node.js theme={null}
  const mergedCustomer = await stateset.customers.merge({
    primary_customer_id: 'cust_primary_123',
    duplicate_customer_ids: ['cust_dup_456', 'cust_dup_789'],
    merge_strategy: {
      contacts: 'merge_all',
      orders: 'transfer_all',
      addresses: 'merge_unique',
      preferences: 'most_recent'
    },
    reason: 'Duplicate accounts identified during data cleanup'
  });
  ```

  ```python Python theme={null}
  merged_customer = stateset.customers.merge({
    'primary_customer_id': 'cust_primary_123',
    'duplicate_customer_ids': ['cust_dup_456', 'cust_dup_789'],
    'merge_strategy': {
      'contacts': 'merge_all',
      'orders': 'transfer_all',
      'addresses': 'merge_unique',
      'preferences': 'most_recent'
    },
    'reason': 'Duplicate accounts identified during data cleanup'
  })
  ```

  ```ruby Ruby theme={null}
  merged_customer = Stateset::Customer.merge({
    primary_customer_id: 'cust_primary_123',
    duplicate_customer_ids: ['cust_dup_456', 'cust_dup_789'],
    merge_strategy: {
      contacts: 'merge_all',
      orders: 'transfer_all',
      addresses: 'merge_unique',
      preferences: 'most_recent'
    },
    reason: 'Duplicate accounts identified during data cleanup'
  })
  ```

  ```go Go theme={null}
  mergedCustomer, err := stateset.Customers.merge({
    PrimaryCustomerID: 'cust_primary_123',
    DuplicateCustomerIDs: []string{'cust_dup_456', 'cust_dup_789'},
    MergeStrategy: MergeStrategy{
      Contacts: 'merge_all',
      Orders: 'transfer_all',
      Addresses: 'merge_unique',
      Preferences: 'most_recent'
    },
    Reason: 'Duplicate accounts identified during data cleanup'
  })
  ```

  ```java Java theme={null}
  Customer mergedCustomer = stateset.customers.merge({
    primaryCustomerId: 'cust_primary_123',
    duplicateCustomerIds: ['cust_dup_456', 'cust_dup_789'],
    mergeStrategy: {
      contacts: 'merge_all',
      orders: 'transfer_all',
      addresses: 'merge_unique',
      preferences: 'most_recent'
    },
    reason: 'Duplicate accounts identified during data cleanup'
  });
  ```

  ```php PHP theme={null}
  $merged_customer = $stateset->customers->merge([
    'primary_customer_id' => 'cust_primary_123',
    'duplicate_customer_ids' => ['cust_dup_456', 'cust_dup_789'],
    'merge_strategy' => [
      'contacts' => 'merge_all',
      'orders' => 'transfer_all',
      'addresses' => 'merge_unique',
      'preferences' => 'most_recent'
    ],
    'reason' => 'Duplicate accounts identified during data cleanup'
  ]);
  ```

  ```csharp C# theme={null}
  var mergedCustomer = await stateset.Customers.Merge(new {
    PrimaryCustomerId = 'cust_primary_123',
    DuplicateCustomerIds = new[] { 'cust_dup_456', 'cust_dup_789' },
    MergeStrategy = new {
      Contacts = 'merge_all',
      Orders = 'transfer_all',
      Addresses = 'merge_unique',
      Preferences = 'most_recent'
    },
    Reason = 'Duplicate accounts identified during data cleanup'
  });
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "cust_primary_123",
    "merged_customer_ids": ["cust_dup_456", "cust_dup_789"],
    "merge_summary": {
      "orders_transferred": 15,
      "addresses_merged": 3,
      "contacts_merged": 2,
      "total_lifetime_value": 4567.89,
      "loyalty_points_combined": 2500
    },
    "conflicts_resolved": [
      {
        "field": "email",
        "primary_value": "john@example.com",
        "duplicate_values": ["j.doe@example.com", "johndoe@example.com"],
        "resolution": "kept_primary"
      },
      {
        "field": "phone",
        "primary_value": "+1-555-0123",
        "duplicate_values": ["+1-555-0124"],
        "resolution": "kept_all_as_secondary"
      }
    ],
    "merged_at": "2024-01-15T14:30:00Z",
    "merged_by": "user_admin_123",
    "success": true
  }
  ```

  ```json Error Response theme={null}
  {
    "error": {
      "code": "merge_conflict",
      "message": "Cannot merge customers with active subscriptions. Please resolve subscriptions first.",
      "details": {
        "primary_customer_subscriptions": 1,
        "duplicate_customer_subscriptions": ["cust_dup_456"],
        "resolution_required": "cancel_or_transfer_subscriptions"
      }
    }
  }
  ```
</ResponseExample>