The API lets you create a transaction or a customer merge request.

Customer Merge Request

You can make customer merge requests in standard organizations, organizations with dual eligibility enabled, and connected organizations.

Customer merge requests are defaulted to Pending. Capillary’s backend team reviews the request and either approves or rejects it. However, you can use the client_auto_approve=true query parameter in the API to automatically process the request.

In a connected organization setup, the ability to create customer merge requests depends on where the request originates. Only parent organizations can initiate merge requests. All POST requests to the /v2/requests endpoint from child organizations are blocked. Survivor and victim customers must be registered in the parent organization and all child organizations.

Conditions for Adding Merge Requests in Connected Organizations

Customer merge requests are added to the parent and child organizations based on the presence of both the victim and survivor customers. Use the following rules to determine when to add or ignore the request:

Customer Exists in Organization	Victim Available	Survivor Available	Action
Parent	Yes	Yes	Add the request
Child	No	Yes	Ignore the request You can't merge if only the survivor exists.
Child	Yes	No	Ignore the request You can't merge if only the victim exists.
Child	No	No	Ignore the request Neither of the customers exists.
Child	Yes	Yes	Multiplex and merge the customers Note: Multiplexing refers to the automatic replication of a merge request from the parent organization to all eligible child organizations.

Note: In a setup with one parent and two or more child organizations, if either the survivor or the victim customer is absent from any organization, the merge request will not be multilexed to that organization.

Prerequisites

Authentication - Basic or OAuth authentication
Access group resource - Write permission on Requests resource group.

Resource Information


URL	v2/requests
HTTP method	POST
Pagination	NA
Rate limit	NA
Batch support	NA

API Endpoint Example

https://{host}/v2/requests

Request body parameters for Transaction Request

Parameter	Type	Description
type	String	The type of the transaction, in this case, "TRANSACTION."
baseType	String	The base type of the transaction, in this case, "REGULAR_TXN_ADD."
customerIdentificationInfo	Object	Contains customer identification information, including the identifier type (externalId), identifier value, and source (INSTORE).
transaction	Object	Contains details about the transaction, such as type, billing date, bill number, discounts, bill amount, gross amount, delivery status, payment modes, custom fields, and line items.
type	String	The type of the transaction, in this case, "REGULAR."
billingDate	String	The billing date in ISO 8601 format, e.g., "2022-12-13T11:58:18+05:30."
billNumber	String	The bill number associated with the transaction, e.g., "4113641."
discount	String	The discount amount, e.g., "0."
billAmount	String	The total bill amount, e.g., "21."
note	String	Additional notes or comments for the transaction, if any.
grossAmount	String	The gross amount of the transaction, e.g., "21."
deliveryStatus	String	The delivery status of the transaction, e.g., "SHIPPED."
paymentModes	Array	An array of objects containing details about the payment modes used in the transaction.
customFields	Object	Contains custom fields related to the transaction, e.g., "paymentmode," "vendor_name," and "added_on."
lineItemsV2	Array	An array of objects containing details about individual line items in the transaction, including item codes, descriptions, amounts, rates, quantities, and discounts.
images	Array	An array of objects representing images related to the transaction, including file names, serial numbers, namespaces, and providers.

Response for Transaction Request

Parameter	Description
createdId	Transaction request id
warnings	Warnings, if any.

Request Query Parameter for Customer Merge

Parameter (Parameters marked with * are mandatory)	Data Type	Description
source*	String	Source from which the customer is created. Value: INSTORE. Currently, only INSTORE is supported.
client_auto_approve	Boolean	Automatically approves the merge request. Default value: `false` By default, the system creates all requests with a Pending status. When you set `client_auto_approve=true`, the request is still created as Pending, but the system automatically processes and updates it to Approved without manual review. Note: Avoid using the `client_auto_approve` parameter unless necessary.

Request Body Parameters for Customer Merge

Note: One of the fields marked with ** is mandatory.

Parameter(Parameters marked with * are mandatory)	Data Type	Description
victimCustomer*	Object	Details of the customer to be removed (victim).
- mobile**	String	Mobile number of the customer to be merged (victim).
- email**	String	Email address of the customer to be merged.
- externalId**	String	External ID of the customer to be merged.
- accountId **	String	Account ID of the customer to be merged.
- id**	String	Customer ID of the customer to be merged.
baseType*	String	Base type of the request. Use `"MERGE"` for customer merge.
type*	String	Type of change. Use `"CHANGE_IDENTIFIER"` for customer merge.
survivorCustomer*	Object	Details of the customer to retain (survivor).
- mobile**	String	Mobile number of the customer to retain.
- email**	String	Email address of the customer to retain.
- externalId**	String	External ID of the customer to retain.
- accountId**	String	Account ID of the customer to retain.
- id**	String	Customer ID of the customer to retain.

curl --location 'https://eu.api.capillarytech.com/v2/requests?source=INSTORE' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic ZGllYTI0YTYyZTZm' \
--header 'Cookie: _cfuvid=EWw7Wfz8Ouj54ZVF2cPldbObmSaOCCsfBD._qxSWZoM-1744468652196-0.0.1.1-604800000' \
--data-raw '{
    "victimCustomer": {
        "mobile": "919865398633",
        "email" : "[email protected]"
        
    },
    "baseType": "MERGE",
    "type": "CHANGE_IDENTIFIER",
    "survivorCustomer": {
        "mobile": "919865398634",
        "email": "[email protected]"
       
    }
}'

curl --location 'https://eu.api.capillarytech.com/v2/requests?source=INSTORE' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YXV0b3NTJkMjM0Yjcw' \
--data-raw '{
    "victimCustomer": {
        "mobile": "917569065670",
        "email" : "[email protected]",
        "externalId": "externalId7569065670"
    },
    "baseType": "MERGE",
    "type": "CHANGE_IDENTIFIER",
    "survivorCustomer": {
        "mobile": "918082558297",
        "email": "[email protected]",
        "externalId": "externalId8082558297"
    }
}'

curl --location 'https://eu.api.capillarytech.com/v2/requests?source=INSTORE' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YXVNWI5NjRiMDcxNTJkMjM0Yjcw' \
--data-raw '{
    "victimCustomer": {
        "mobile": "917569065670",
        "email" : "[email protected]",
        "externalId": "externalId7569065670"
    },
    "baseType": "MERGE",
    "type": "CHANGE_IDENTIFIER",
    "survivorCustomer": {
        "mobile": "918082558297",
        "email": "[email protected]",
        "externalId": "externalId8082558297"
    }
}'

curl --location 'https://eu.api.capillarytech.com/v2/requests?source=INSTORE_V2&client_auto_approve=true' \
--header 'Authorization: Basic YNjRiMDcxNTJkMjM0Yjcw' \
--header 'Content-Type: application/json' \
--data '{
    "victimCustomer": {
       "id":"387754951"
    },
    "baseType": "MERGE",
    "type": "CHANGE_IDENTIFIER",
    "survivorCustomer": {
        "id":"387754954"
    }
}'

Response Parameters for Customer Merge

Parameter	Data Type	Description
createdId	Integer	Unique ID of the created merge request.
warnings	Array	List of warnings, if any, returned by the API.

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

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

{
    "errors": [
        {
            "status": false,
            "code": 9021,
            "message": "Request Add/Update is blocked for the org"
        }
    ]
}

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

Error Code

Error Code	Description
9021	Request Add/Update is blocked for the child organization