This API links customers to external partner programs or subscription programs. You can link up to 50 customers to multiple partner programs in a single request.

Example request

curl --location 'https://eu.api.capillarytech.com/v2/partnerProgram/linkCustomer' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bmFM2YjZlY2I2MmEy' \
--data '{
    "linkCustomers": [
        {
            "customer": {
                "mobile": "919400xxxxxx"
            },
            "linkToPartnerPrograms": [
                {
                    "partnerProgramName": "Goldstar",
                    "customerPartnerReference": {
                        "partnerMembershipId": "919xxxxxxxx",
                        "partnerTierName": "Gold",
                        "partnerTierExpiryDate": "2026-12-31T23:59:59+05:30",
                        "membershipStartDate": "2025-12-23T17:55:00+05:30"
                    }
                }
            ]
        }
    ]
}'

Prerequisites

Authentication: Basic or OAuth authentication
Default access group

Resource information


URI	/v2/partnerProgram/linkCustomer
HTTP Method	POST
Batch support	Yes (up to 50 customers per request)
Rate limit	None

Body parameters

Field	Type	Required	Description
linkCustomers	array	Yes	List of customer linking requests. Maximum 50 customers per request.
.customer	object	Yes	Customer identification details. At least one identifier is required.
..id	integer	Conditional	Customer's internal Capillary ID. Any one identifier is required.
..mobile	string	Conditional	Customer's mobile number. Any one identifier is required.
..email	string	Conditional	Customer's email address. Any one identifier is required.
..externalId	string	Conditional	Customer's external identifier. Any one identifier is required.
.linkToPartnerPrograms	array	Yes	List of partner programs to link the customer to.
..partnerProgramName	string	Yes	Name of the partner program. Must match an existing partner program configured in your organization.
..customerPartnerReference	object	Optional	Details about the customer's reference in the partner program.
...partnerMembershipId	string	Yes	Customer's membership ID in the partner program. Required when `customerPartnerReference` is provided.
...partnerTierName	string	Optional	Name of the partner tier to assign to the customer. Must match an existing tier in the partner program.
...partnerTierExpiryDate	string	Optional	Expiry date for the customer's tier status. Must be today or a future date. Format: ISO 8601 (e.g., `2026-12-31T23:59:59+05:30`). Default timezone is the server's timezone.
...membershipStartDate	string	Optional	Date when the customer's membership begins. Must be today or a future date. The customer becomes an active member on this date. Format: ISO 8601 (e.g., `2025-12-23T17:55:00+05:30`). Default timezone is the server's timezone.

API Quick Reference

POST /v2/partnerProgram/linkCustomer
   └─ LinkPartnerProgramBatch
       └─ linkCustomers[] (array, required)
           ├─ customer (object, required)
           │   ├─ id (integer)
           │   ├─ mobile (string)
           │   ├─ email (string)
           │   └─ externalId (string)
           └─ linkToPartnerPrograms[] (array, required)
               ├─ partnerProgramName (string, required)
               └─ customerPartnerReference (object)
                   ├─ partnerMembershipId (string, required)
                   ├─ partnerTierName (string)
                   ├─ partnerTierExpiryDate (datetime)
                   └─ membershipStartDate (datetime)

Example response

{
    "linkCustomers": [
        {
            "customer": {
                "id": 565039504,
                "mobile": "919400xxxxxx",
                "email": "gxxxxxxx@gmail.com",
                "externalId": "X919400xxxxxx",
                "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	List of customer linking results.
.customer	object	Customer identification details and retrieval status.
..id	integer	Customer's internal Capillary ID.
..mobile	string	Customer's mobile number.
..email	string	Customer's email address.
..externalId	string	Customer's external identifier.
..status	object	Status of customer retrieval.
...status	boolean	`true` if customer was found, `false` otherwise.
...code	integer	Status code for customer retrieval. `1000` indicates success.
...message	string	Message describing the customer retrieval result.
.linkToPartnerPrograms	array	List of partner programs and their linking results.
..partnerProgramName	string	Name of the partner program.
..partnerLinkStatus	object	Status of linking the customer to the partner program.
...status	boolean	`true` if linking succeeded, `false` otherwise.
...code	integer	Status code for the linking operation. `200` indicates success.
...message	string	Message describing the linking result.
warnings	array	List of warnings, if any.

Error codes

Code	Type	Description
2001	Error	Partner program event failed. An internal error occurred while processing the linking request.
2002	Error	Required field is empty or null. Ensure `partnerProgramName` and other required fields are provided.
2003	Error	Partner tier expiry date must be today or a future date. Past dates are not allowed for `partnerTierExpiryDate`.
2005	Error	Customer not enrolled in loyalty program. The customer must be enrolled in the loyalty program before linking to a partner program.
2005	Error	Partner program already linked with customer. The customer is already linked to the specified partner program.
2006	Error	Partner program not found. Verify that the `partnerProgramName` matches an existing partner program in your organization.
2007	Error	Partner program tier not found. Verify that the `partnerTierName` matches an existing tier in the specified partner program.
2008	Error	Batch limit exceeded. The request contains more than 50 customers. Split the request into smaller batches.
2019	Error	Customer can only be linked to one supplementary partner program at a time, based on program settings.

Warning codes

Code	Type	Description
1302	Warning	Supplementary program expiry is before membership expiry. The partner program expiry date is earlier than the customer's membership expiry.

200Successful operation (default from cURL)