Use Case - loyalty cards of a customer across sources can be added or removed.

Identifiers: mobile, email, externalId, wechat, martjackId, fbId, tmall_uname, cuid, ali_uname, jd_uname, vip_uname, line.

Limitations of the customer identifier update API:

• Only identifiers can be updated using this API
• Identifiers should be unique within a source for single account sources and unique within an account for multiple account sources.
• If an identifier that you add already exists in a different source/account, the account will be automatically merged into the existing account maintaining different entries of each source. The new account will be a victim account and the existing account is a survivor account.

Prerequisites

• Valid customer identifier(s) that you want to add to the existing account

📘

The new identifier that you want to update should be unique across the source (for sources with single accounts) and unique across the account (for sources with multiple accounts).

Example request

curl --location 'https://eu.api.capillarytech.com/v2/customers/564767826/changeIdentifier?source=INSTORE' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Authorization: Basic cnV0dWphXMGI0NzZjNg==' \
--header 'Cookie: _cfuvid=pQPy_F.YRXJFSzvmPJmB4FH7K2rncxP7s12ArteCH1E-1744806036086-0.0.1.1-604800000' \
--data '{
    "add": [
        {
            "type": "cardnumber",
            "value": "Test09000000000004end",
            "seriesCode": "Test",
            "statusLabel": "ACTIVE"
        }
    ]
}'

curl --location 'https://eu.api.capillarytech.com/v2/customers/564767826/changeIdentifier?source=INSTORE&format=json' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Authorization: Basic cnV0dWphX20NzZjNg==' \
--header 'Cookie: _cfuvid=pQPy_F.YRXJFSzvmPJmB4FH7K2rncxP7s12ArteCH1E-1744806036086-0.0.1.1-604800000' \
--data '{
    
    "remove": [
        {
            "type": "cardnumber",
            "value": "Test09000000000004end",
            "seriesCode": "Test",
            "statusLabel": "NOT_ISSUED"
        }
    ]
}'

curl --location 'https://eu.api.capillarytech.com/v2/customers/564845545/changeIdentifier?source=INSTORE' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Authorization: Basic =' \
--header 'Cookie: _cfuvid=a0NmZQvi.30LKK7NvCQJgMpK8Ig15sul9um2ZFRucDk-1757422794990-0.0.1.1-604800000' \
--data '{
    "add": [
        {
            "type": "cardnumber",
            "value": "mtest00000000057003",
            "seriesCode": "Test",
            "statusLabel": "ACTIVE"
        }
    ]
}'

Request Body Parameters

Example response

{
    "createdId": 564854782,
    "warnings": []
}

API Specific Error Code

Limitations and Known Issues with Multiple Identifier Updates

When using the /v2/customers/{customerId}/changeIdentifier API to update multiple identifiers (for example, both mobile and cuid) in a single request with source=INSTORE, there are important limitations and behaviors to be aware of:

• The API enforces a validation (checkIsSyncEnabledAndValid) that restricts simultaneous updates of certain identifier combinations. Specifically, if both mobile and cuid are included in the payload, the validation (remove.size() == 1) may block the update, resulting in only one identifier being processed or the update failing.
• The InstoreChangeIdentifierValidator may filter out certain identifiers (such as cuid), which can cause synchronization issues between systems and lead to incomplete or reverted identifier updates.
• Inconsistent payload structures between different platforms (such as Android and iOS) can further impact the upsert behavior, potentially resulting in identifiers not being updated as expected.
• If the configuration parameter CONF_RESTRICT_ORPHAN_V2_PROFILE is enabled, failed or partial updates may lead to the creation of orphan profiles (profiles without a primary identifier), which can affect downstream processes and data integrity.

Recommendation:

• To avoid these issues, update only one identifier at a time per request when using this API, especially for critical identifiers like mobile and cuid.
• Review your integration to ensure payload consistency across platforms and handle error responses appropriately.
• Be aware of the impact of the CONF_RESTRICT_ORPHAN_V2_PROFILE configuration on profile creation and maintenance.