Link Customer to Partner Program

post

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

Endpoint for POST /v2/partnerProgram/linkCustomer

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

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 <YOUR_AUTH_TOKEN>' \
--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"
                    },
                    "configAttributes": [
                        {
                            "name": "tier_label",
                            "value": "Gold"
                        }
                    ]
                }
            ]
        }
    ]
}'

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

Prerequisites

Authentication: Basic or OAuth authentication
Partner program 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.
..configAttributes	array	Optional	Loyalty configuration attributes to capture for this link. Each attribute is stored against the customer's enrollment and returned by the Get customer activity history API, and echoed back in this API's own response. Each `name` must match a loyalty configuration attribute configured for the partner program, can appear only once in the request, and must have a non-blank `value`.
...name	string	Conditional	Name of the loyalty configuration attribute. Required for each attribute in the array.
...value	string	Conditional	Value of the loyalty configuration attribute. Required for each attribute in the array. There is no character limit for this parameter.

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)
               └─ configAttributes[] (array)
                   ├─ name (string)
                   └─ value (string)

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",
                    "configAttributes": [
                        {
                            "name": "loyaltyTier",
                            "value": "Gold"
                        }
                    ],
                    "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.
..configAttributes	array	Echoes back the loyalty configuration attributes submitted in the request for this partner program, if any.
...name	string	Name of the loyalty configuration attribute.
...value	string	Value of the loyalty configuration attribute.
..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

These codes appear inside the partnerLinkStatus object for the specific customer/partner program pair in the response — the API returns HTTP 200 even when an individual linking attempt fails.

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.
999999	Error	Generic error returned for invalid `configAttributes` in the request — for example, an attribute `name` that isn't configured for the partner program, a duplicate `name` in the same request, or a blank `value`. The response message does not currently distinguish between these cases; check your request against the `configAttributes` validation rules above.

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.

Responses

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

500

Internal Server Error

Language

URL

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json