Link Customer to Partner Program

post https://{host}/v2/partnerProgram/linkCustomer

This API allows you to link customers to external partner programs or subscription programs.

Example request

curl --location 'https://eu.api.capillarytech.com/v2/partnerProgram/linkCustomer' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bmFM2YjZlY2I2MmEy' \
--header 'Cookie: _cfuvid=k8zSJjLsLwFLJ7j5C_trJgTjB5aw1e6GEVynFpyYGYQ-1758545477838-0.0.1.1-604800000; _cfuvid=Klv7acSJgcFtHhnlTu2TE5ukUxjXoBDToYvE8UAOFKY-1758630285622-0.0.1.1-604800000' \
--data '{
    "linkCustomers": [
        {
            "customer": {
                "email": "",
                "externalId": "",
                "mobile": "9400xxxxxx"
            },
            "linkToPartnerPrograms": [
                {
                    "customerPartnerReference": {
                        "membershipStartDate": "2025-12-23T17:55:00 +05:30",
                        "partnerMembershipId": "919xxxxxxxx"
                    },
                    "partnerProgramName": "Goldstar"
                }
            ]
        }
    ]
}'

Prerequisites

Authentication: Basic or OAuth authentication.
Default access group

Rate limit

Demo and Testing Clusters: 1,000 requests per minute per API key
Other Organizations: The rate limit is brand-specific.

To modify the limit, create a ticket with the Capillary Product support team.

Body parameters

Field	Type	Required	Description
linkCustomers	Array	Yes	Specifies the list of customer linking requests. Multiple customers can be linked in one request.
..customer	Object	Yes	Specifies customer identification details. At least one identifier must be provided. Supported identifiers : `externalid`, `mobile`, `email`
....externalId	String	Yes	Specifies the customer's external identifier. Any one identifier is required.
....mobile	String	Optional	Specifies the customer's mobile number. Any one identifier is required.
....email	String	Optional	Specifies the customer's email address. Any one identifier is required.
..linkToPartnerPrograms	Array	Yes	Specifies the list of partner programs to link the customer to. Multiple programs can be linked in a single request.
....partnerProgramName	String	Yes	Specifies the name of the partner program. Determines which program the customer is linked to.
....customerPartnerReference	Object	Yes	Specifies details about the customer's reference in the partner program.
......partnerMembershipId	String	Yes	Specifies the customer's membership ID in the partner program.
......partnerTierName	String	Optional	Specifies the name of the partner tier. Determines the tier assigned to the customer.
......partnerTierExpiryDate	String	Optional	Indicates when a customer's specific tier status, such as Gold or Silver, is set to expire. After this date, the customer will no longer receive the benefits associated with that tier. You should use this field only if your program has different levels and you want to set a specific expiration date for a member's tier status. Example: If partnerTierExpiryDate is set to December 31, 2025, for a Gold Member like Priya, her Gold status and its associated benefits will expire on that specific date. This is the case even if her general membership in the loyalty program remains active. The supported time format is ISO 8601, and the default timezone is the server's timezone.
......membershipStartDate	String	Optional	Specifies the exact date when a customer's membership in a program starts. A customer is considered an active member and can access benefits only on or after this specified date. For instance, if Rahul's membershipStartDate is set to September 17, 2025, he becomes an active member on that day. The date must be in the ISO 8601 format, and the default timezone is the server's timezone.

Example response

{
    "linkCustomers": [
        {
            "customer": {
                "id": 565039504,
                "mobile": "919400xxxxxx",
                "email": "[email protected]",
                "status": {
                    "status": true,
                    "code": 1000,
                    "message": "Customer successfully retrieved"
                }
            },
            "linkToPartnerPrograms": [
                {
                    "partnerProgramName": "Goldstar",
                    "partnerLinkStatus": {
                        "status": true,
                        "code": 200,
                        "message": "Success"
                    }
                }
            ]
        }
    ],
    "warnings": []
}

Response parameters

Field	Type	Description
linkCustomers	Array	Defines a list of customer linking statuses.
..customer	Object	Specifies customer identification details and their status.
....id	Long	Indicates the customer's internal ID. Example: `565039504`
....mobile	String	Specifies the customer's mobile number.
....email	String	Indicates the customer's email address.
....externalId	String	Indicates the customer's external identifier.
....status	Object	Defines the status of customer retrieval.
......status	Boolean	Indicates the success or failure of the customer retrieval. Possible values: `true`, `false`
......message	String	Specifies a message related to the customer retrieval status.
......code	Integer	Indicates a numeric code for the customer retrieval status.
..linkToPartnerPrograms	Array of Objects	Specifies a list of partner programs and their linking statuses.
....partnerProgramName	String	Defines the name of the partner program. Example: `"1stProgram"`, `"NoTierPartnerProgram"`
....partnerLinkStatus	Object	Indicates the status of linking the customer to a specific partner program. This field might be absent if there's no specific linking status (e.g., if the customer wasn't found).
......status	Boolean	Indicates the success or failure of the partner program linking. Possible values: `true`, `false`.
......message	String	Specifies a message related to the partner program linking status. Example: "partner tier expiry date should be future date or today date".
......code	Integer	Indicates a numeric code for the partner program linking status.

Error codes

Code	Description
400	Invalid Request: Cannot find customer for provided mobile/external-id/e-mail/id. Verify that the `mobile`, `externalId`, `email`, or `id` provided in the `customer` object corresponds to an existing customer in the system and is correct.
400	Invalid Request: partner tier expiry date should be future date or today date. Ensure the `partnerTierExpiryDate` in the `customerPartnerReference` object is set to a date that is either today or a future date. Past dates are not allowed for tier expiry.
400	Invalid Request: ERR_PE_INVALID_DATA. This indicates invalid data within the Points Engine. Review all fields in the `customerPartnerReference` object for correctness, data types, and adherence to any specific constraints not explicitly mentioned.
400	Invalid Request: ERR_PARTNER_MEMBERSHIP_START_DATE. Verify that the `membershipStartDate` in the `customerPartnerReference` object is a valid date and adheres to any rules regarding its relation to the current date or other dates within the system.

Language

URL

Click Try It! to start a request and see the response here!