Time	Status	User Agent
Retrieving recent requests…

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.

What this API supports

Link a customer to one or more partner programs in a single request.
Schedule a future-dated membership relinking for supplementary programs — if the customer is already linked, setting a future membershipStartDate queues a pending relink instead of returning an error.

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"
                    }
                }
            ]
        }
    ]
}'

curl --location 'https://eu.api.capillarytech.com/v2/partnerProgram/linkCustomer' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bmFM2YjZlY2I2MmEy' \
--data '{
    "linkCustomers": [
        {
            "customer": {
                "mobile": "917800048833"
            },
            "linkToPartnerPrograms": [
                {
                    "partnerProgramName": "SPP_1",
                    "customerPartnerReference": {
                        "membershipStartDate": "2027-01-01T00:00:00+05:30"
                    }
                }
            ]
        }
    ]
}'

Prerequisites

Authentication: Basic or OAuth authentication
Default access group
For future-dated relinking of supplementary programs: the ALLOW_MEMBERSHIP_RELINKING configuration must be enabled for your organisation. To enable this, raise a JIRA ticket to the Capillary product support team.

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	Conditional	Customer's membership ID in the partner program. Required for a new enrollment. Not required when scheduling a future-dated relinking for a customer who is already linked (in that case, the membership ID is already on record).
...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. Format: ISO 8601 (e.g., `2027-01-01T00:00:00+05:30`). Must be today or a future date. If the customer is already linked to this supplementary partner program, providing a future date schedules a relinking on that date. To cancel a scheduled relinking before it activates, use the Update Customer API with `updateType: MEMBERSHIP_RELINKING_CANCELLED`. Requires `ALLOW_MEMBERSHIP_RELINKING` to be enabled for the org.

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": "[email protected]",
                "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. If you are trying to schedule a future relinking, ensure `membershipStartDate` is after the customer's current membership end date — a date earlier than the current end date returns this error instead of queuing a relink.
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.
2025	Error	`membershipStartDate` is in the past. Provide a today-or-future date when scheduling a relinking.
2026	Error	Membership relinking is not enabled for this organisation. To enable `ALLOW_MEMBERSHIP_RELINKING`, raise a JIRA ticket to the Capillary product support team.

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.

Example request

Prerequisites

Resource information

Body parameters

API Quick Reference

Example response

Response parameters

Error codes

Warning codes

200Successful operation (default from cURL)