NAV Navbar
Logo
json xml

Release Updates

This section provides the quarterly breakup of existing API updates and new API releases.

Q2 Releases (2021-2022)

Q2 Releases (2020)

Q4 Releases (2019-20)

Getting Started

The Capillary APIs are RESTful APIs that help third party applications manage an Organization’s CRM and Loyalty Program through the Capillary platform. This document provides all the APIs that can be used to integrate with the Capillary Applications, their descriptions, resource information, request parameters, request URIs, and sample requests.

Organization Setup

An organization associated with Capillary is registered in InTouch. Based on the organization’s architecture, store TILL or Store Center accounts are created besides zones, concepts, and stores. Only Capillary users have access to register an organization in inTouch. For more information, contact your Account Manager or Delivery Manager of Capillary.

To set up an organization as a Capillary admin, see Setting up Organization.

Authentication

Capillary APIs can be accessed either using Basic auth (TILL/Store Center credentials), or OAuth (Client key and secret associated to a Till/Store Center) . Please note that it is mandatory to use only the store specific Till/Store Center credentials as the data in the API response depends on this identification.

When to use Basic & OAuth?*

Basic oAuth
Can be used for POS integrations where API requests come to Capillary server directly from POS front end or POS store server. Shall be used for backend integrations (from one backend to another backend). For example, POS integrations where API requests come to Capillary server from API gateway or a central server; FTP integrations where backend service need to be authenticated; 3rd party integration where API requests come to Capillary from a backend platform.

Process 1: Basic Authentication

To obtain access to the entities of the Capillary Rest APIs, you need to authenticate the TILL/store center account that you are referring to for using the HTTP Basic Authentication.

Authorization Header is used for validating authentication credentials. The Authorization Header is constructed as shown below:

Authorization: Basic <Base64 encoded (username: md5(password))>

In the Authorization Header pass the encoded Base64 form of username and md5 formatted password.

Headers Required for Basic Auth

Process 2: OAuth

OAuth provides better security and helps you create secure passages to access your org’s data through Capillary APIs. To generate oAuth client key and secret see API Authentication Configuration.

Generate Access Token

Once you get key and secret, you can generate access token or JWT (JSON Web Token) using the token/generate API. JWT is a compact URL and JSON-based used to transfer data securely between two parties.

Resource Information

URI /oauth/token/generate
API Version v3
HTTP Method POST
Authentication Required? No
Batch Support? No

Other Headers Required

Endpoint

https://{host}/v3/oauth/token/generate

POST Request Schema

{ "key": "", "secret": "" }

Sample Request

https://eu.api.capillarytech.com/v3/oauth/token/generate

Sample POST Request

{
  "key": "WnCygRI1Fmlf6YudKwTxQq1LI",
  "secret": "hoqSBz6VwefECaZA8Q3oNx4V4H3pMDITksarZVES"
}

Sample Response

{
    "data": {
     "accessToken": "eyJraWQiOiJrMSIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJDYXBpbGxhcnkiLCJleHAiOjE1NzUyNzAyNzAsImp0aSI6IjJaX2FqUjcwYzJABChVUjlDVTVpUlEiLCJpYXQiOjE1NzUyNjk5NzAsInN1YiI6Im5hbWVfODQzNjIwODIwMSIsImNsaWVudF9pZCI6MjEsIm9yZ19pZCI6MTExNSwidG9rZW5fdXNlIjoidG9rZW5fYWNjZXNzIn0.Ala1-XTDlPtrHFQfCtJKsXe3h_WVyq4QOGI3ZnLNJqOa-yJc1UPGbypUysWemzEaiQC_BJ0n9G68SYkVZGi4CSVOhHRNA_dILe8y1Sa90YZKwHVHogJmIKzLmksJrTbjn8s8hSMePBaaUcEdUZ1XssxdFrZhEHHN1fWVYtkdb74PB3sZ7OMDqKUysON8YTNQxLgKOJ3kq0o2QUUDQo1q3gxXFuswate6-jj3oBkcdd1ohhXkPIWZlAb_1lRcLr-ECaaBfh473gayeMVV_6khdKJ7cXrUQ3CXppkrPIzBb7rS6I93iWZw0IlmWbaGduTmPPOhLX6HZLOb84Y28st-cw",
        "ttlSeconds": 300
    },
    "errors": null
}

Using Access Token

Once you generate the access token, you can use it to authenticate API calls as shown below.

Set the authentication to No Auth and pass the following headers.

Required Headers

Header Value
X-CAP-API-OAUTH-TOKEN* Generated access token. If the token expires, you need to regenerate the access token.
Content-Type* This should be set as application/json.
Accept* This should also be set as application/json.
X-CAP-API-ATTRIBUTION-ENTITY-TYPE Till or store from which you want to post the data. Supported Values: TILL, STORE_CODE, STORE_NAME, STORE_EXTERNAL_ID, STORE_EXTERNAL_ID_1, STORE_EXTERNAL_ID_2. The default value is TILL.
X-CAP-API-ATTRIBUTION-ENTITY-CODE Pass the entity value based on the entity type. For example, if X-CAP-API-ATTRIBUTION-ENTITY-TYPE is STORE_CODE, then X-CAP-API-ATTRIBUTION-ENTITY-CODE is the store code that you want to tag to POST data. By default, it considers the Till associated with the client key and secret.

For example, to get transaction details, you can use the following details. Before making a API call, make sure the token has access to the required resource.

Headers

Accept | application/json Content-Type | application/json X-CAP-API-OAUTH-TOKEN | eyJraWQiOiJrMSIsImFsZyI6IlJTMjU2In0.wiOlwiV1JJ…

Sample Request URL

https://eu.api.capillarytech.com/v2/transaction/38233952?type=REGULAR

Tracking Request

{
  "Date": "Wed, 16 Dec 2015 06:05:13 GMT",
  "Content-Type": "application/json; charset=utf-8",
  "Cache-Control": "must-revalidate,no-cache,no-store",
  "X-Cap-Requestid": "5670FF17B7D58",
  "Server": "CapWS",
  "Content-Encoding": "gzip",
  "X-Cache": "MISS from localhost",
  "Transfer-Encoding": "chunked",
  "Connection": "keep-alive"
}

A unique id is generated for every request made using Capillary APIs and is sent to the requester in the Response Headers as “X-Cap-Requestid”. You can use this request id to track the request end-to-end. <aside class=“notice” It is recommended to note the X-Cap-Requestid of a request for future requirements.

Headers Required

Capillary CRM V1.1 APIs support both XML and JSON formats for requests and responses. You can set header as per your required format.

Header Description Value
Accept Request format from the server side Pass application/json for JSON format, application/xml for XML format.
Content-Type Determine desired representation client the side Pass application/json for JSON format, application/xml for XML format.

Resource Information

Type Description
Request URL https://{host}/v1.1/{entity}/{method}?{QueryParams}&{format}
Host The server to which the API calls are made (cluster URL).
India: apac.api.capillary.co.in
APAC2: apac2.api.capillarytech.com
EU: eu.api.capillarytech.com
US: us.api.capillarytech.com
China: cdn-api.capillarytech.cn.com [or] api.capillarytech.cn.com
API Version Number v1.1
Entity Resource for which actions are performed. Example: communications, coupon, customer, organization, points, product, store, and transaction
HTTP Methods The Capillary Cloud REST APIs support the standard HTTP methods - GET and POST
Format Preferred format of requesting data - xml, json. By default, these APIs return data in the format represented in Headers. You can explicitly override by passing format=json or format=xml
Example: https://eu.api.capillarytech.com/v1.1/customer/add?format=json

Response Codes

# API level Response Code

<status>
<success>true</success>
<code>200</code>
<message>Operation Successful</message>
</status>
# API level Response Code

{
  "status": {
    "success": "true",
    "code": "200",
    "message": "Operation Successful"
  }
}
# Item Level Response Code

<item_status>
<success>false</success>
<code>1001</code>
<message>Invalid Mobile Number</message>
</item_status>
# Item Level Response Code
{
  "item_status": {
    "success": "false",
    "code": "1001",
    "message": "Invalid Mobile Number"
  }
}

API responses are generated at request level and item level.

API Level Response Codes

Code Description
200 Success
201 Some requests have failed due to errors
500 All requests have failed due to errors
400 Input is invalid, Please check request parameters or input xml/json
401 Please check your username/password or authentication token
402 Version is not supported for this resource
404 Incorrect resource
405 Incorrect HTTP Method
406 Operation is not supported for the resource
407 Unknown Error happened while processing the request
408 Network MAC ID does not match

Item Level Response Codes

Each entity has a different set of response codes. Item level response codes for each entity is provided in the respective entity section.

Customer

A customer is an individual who either buys goods/services, or subscribes to the organization’s newsletters. An organization refers to a store, business firm, hospital or restaurant.

Based on the registration status, customers are categorized into three types:

The customer entity contains APIs related to registering customers into the loyalty program, managing loyalty accounts and updating subscription status of both registered and non-registered customers. It stores customer related information such as identifiers, profile details, custom field details, transactions, preferences, subscription details (mobile number/email id), tier details, points history and coupons history.

Customer APIs allow you to do the following.

Register Customer

Sample Request URL

https://us.api.capillarytech.com/v1.1/customer/add?format=json

Sample POST Request

{ 
   "root":{ 
      "customer":[ 
         { 
            "mobile":"44700900000",
            "card_details": {
            "card_number": "GOLD20000000032435",
            "series_code": ""
            },
            "email":"tom@example.com",
            "external_id":"TOM345",
            "firstname":"Tom",
            "lastname":"Cruise",
            "registered_on":"2012-09-11 11:11:11",
            "updated_on":"",
            "registered_till":"NorthEast",
            "associated_with":"two.till01",
            "referral_code":"SDX123",
            "source":"INSTORE",
            "type":"LOYALTY",
            "subscriptions":{ 
               "subscription":[ 
                  { 
                     "priority":"TRANS",
                     "scope":"all",
                     "is_subscribed":"0",
                     "channel":"email"
                  },
                  { 
                     "priority":"BULK",
                     "scope":"all",
                     "is_subscribed":"0",
                     "channel":"email"
                  },
                  { 
                     "priority":"TRANS",
                     "scope":"all",
                     "is_subscribed":"0",
                     "channel":"sms"
                  },
                  { 
                     "priority":"BULK",
                     "scope":"all",
                     "is_subscribed":"0",
                     "channel":"sms"
                  }
               ]
            },
            "extended_fields":{ 
               "field":[ 
                  { 
                     "name":"gender",
                     "value":"Male"
                  },
                  { 
                     "name":"city",
                     "value":"Bangalore"
                  },
                  { 
                     "name":"dob",
                     "value":"1998/12/01"
                  }
               ]
            },
            "custom_fields":{ 
               "field":[ 
                  { 
                     "name":"Hobbies",
                     "value":"[“Playing”]"
                  },
                  { 
                     "name":"FavoriteColor",
                     "value":"Green"
                  }
               ]
            }
         },
         { 
            "mobile":"44700900011",
            "email":"rita.john@example.com",
            "external_id":"XYPZ006",
            "firstname":"Rita",
            "lastname":"John",
            "registered_on":"2018-09-11 11:11:15",
            "referral_code":"BGH123",
            "source":"WECHAT",
            "type":"NON_LOYALTY",
            "extended_fields":{ 
               "field":[ 
                  { 
                     "name":"gender",
                     "value":"female"
                  },
                  { 
                     "name":"city",
                     "value":"Bangalore"
                  },
                  { 
                     "name":"dob",
                     "value":"1998/09/01"
                  }
               ]
            },
            "subscriptions":{ 
               "subscription":[ 
                  { 
                     "priority":"TRANS",
                     "scope":"all",
                     "is_subscribed":"0",
                     "channel":"email"
                  },
                  { 
                     "priority":"BULK",
                     "scope":"all",
                     "is_subscribed":"0",
                     "channel":"email"
                  },
                  { 
                     "priority":"TRANS",
                     "scope":"all",
                     "is_subscribed":"0",
                     "channel":"sms"
                  },
                  { 
                     "priority":"BULK",
                     "scope":"all",
                     "is_subscribed":"0",
                     "channel":"sms"
                  }
               ]
            },
            "custom_fields":{ 
               "field":[ 
                  { 
                     "name":"Hobbies",
                     "value":"[“Singing”]>"
                  },
                  { 
                     "name":"FavoriteColor",
                     "value":"Blue"
                  }
               ]
            }
         }
      ]
   }
}
<?xml version="1.0" encoding="UTF-8" ?>
<root>
    <customer>
        <mobile>44700900000</mobile>
        <card_details>
            <card_number>GOLD20000000032435</card_number>
            <series_code></series_code>
        </card_details>
        <email>tom@example.com</email>
        <external_id>TOM345</external_id>
        <firstname>Tom</firstname>
        <lastname>Cruise</lastname>
        <registered_on>2012-09-11 11:11:11</registered_on>
        <updated_on></updated_on>
        <registered_till>NorthEast</registered_till>
        <associated_with>two.till01</associated_with>
        <referral_code>SDX123</referral_code>
        <source>INSTORE</source>
        <type>LOYALTY</type>
        <subscriptions>
            <subscription>
                <priority>TRANS</priority>
                <scope>all</scope>
                <is_subscribed>0</is_subscribed>
                <channel>email</channel>
            </subscription>
            <subscription>
                <priority>BULK</priority>
                <scope>all</scope>
                <is_subscribed>0</is_subscribed>
                <channel>email</channel>
            </subscription>
            <subscription>
                <priority>TRANS</priority>
                <scope>all</scope>
                <is_subscribed>0</is_subscribed>
                <channel>sms</channel>
            </subscription>
            <subscription>
                <priority>BULK</priority>
                <scope>all</scope>
                <is_subscribed>0</is_subscribed>
                <channel>sms</channel>
            </subscription>
        </subscriptions>
        <extended_fields>
            <field>
                <name>gender</name>
                <value>Male</value>
            </field>
            <field>
                <name>city</name>
                <value>Bangalore</value>
            </field>
            <field>
                <name>dob</name>
                <value>1998/12/01</value>
            </field>
        </extended_fields>
        <custom_fields>
            <field>
                <name>Hobbies</name>
                <value>[“Playing”]</value>
            </field>
            <field>
                <name>FavoriteColor</name>
                <value>Green</value>
            </field>
        </custom_fields>
    </customer>
    <customer>
        <mobile>44700900011</mobile>
        <email>rita.john@example.com</email>
        <external_id>XYPZ006</external_id>
        <firstname>Rita</firstname>
        <lastname>John</lastname>
        <registered_on>2018-09-11 11:11:15</registered_on>
        <referral_code>BGH123</referral_code>
        <source>WECHAT</source>
        <type>NON_LOYALTY</type>
        <extended_fields>
            <field>
                <name>gender</name>
                <value>female</value>
            </field>
            <field>
                <name>city</name>
                <value>Bangalore</value>
            </field>
            <field>
                <name>dob</name>
                <value>1998/09/01</value>
            </field>
        </extended_fields>
        <subscriptions>
            <subscription>
                <priority>TRANS</priority>
                <scope>all</scope>
                <is_subscribed>0</is_subscribed>
                <channel>email</channel>
            </subscription>
            <subscription>
                <priority>BULK</priority>
                <scope>all</scope>
                <is_subscribed>0</is_subscribed>
                <channel>email</channel>
            </subscription>
            <subscription>
                <priority>TRANS</priority>
                <scope>all</scope>
                <is_subscribed>0</is_subscribed>
                <channel>sms</channel>
            </subscription>
            <subscription>
                <priority>BULK</priority>
                <scope>all</scope>
                <is_subscribed>0</is_subscribed>
                <channel>sms</channel>
            </subscription>
        </subscriptions>
        <custom_fields>
            <field>
                <name>Hobbies</name><value>[“Singing”]></value>
        </field>
        <field>
            <name>FavoriteColor</name>
            <value>Blue</value>
        </field>
    </custom_fields>
</customer>
</root>

Sample Response

<?xml version="1.0" encoding="UTF-8" ?>
<response>
    <status>
        <success>true</success>
        <code>200</code>
        <message>Success</message>
        <total>2</total>
        <success_count>2</success_count>
    </status>
    <customers>
        <customer>
            <user_id>343445381</user_id>
            <firstname>Tom</firstname>
            <lastname>Cruise</lastname>
            <mobile>44700900000</mobile>
            <email>tom@example.com</email>
            <external_id>TOM345</external_id>
            <lifetime_points>0</lifetime_points>
            <loyalty_points>0</loyalty_points>
            <current_slab>bronze</current_slab>
            <tier_expiry_date>2112-09-11 23:59:59</tier_expiry_date>
            <points_summaries>
                <points_summary>
                    <programId>1016</programId>
                    <redeemed>0</redeemed>
                    <expired>0</expired>
                    <returned>0</returned>
                    <adjusted>0</adjusted>
                    <lifetimePoints>0</lifetimePoints>
                    <loyaltyPoints>0</loyaltyPoints>
                    <cumulativePurchases>0</cumulativePurchases>
                    <currentSlab>bronze</currentSlab>
                    <nextSlab>silver</nextSlab>
                    <nextSlabSerialNumber>2</nextSlabSerialNumber>
                    <nextSlabDescription>silver</nextSlabDescription>
                    <slabSNo>1</slabSNo>
                    <slabExpiryDate>2112-09-11 23:59:59</slabExpiryDate>
                    <totalPoints></totalPoints>
                </points_summary>
            </points_summaries>
            <lifetime_purchases>0</lifetime_purchases>
            <registered_on>2012-09-11 11:11:11</registered_on>
            <updated_on>2019-12-09 11:19:23</updated_on>
            <type>LOYALTY</type>
            <custom_fields></custom_fields>
            <extended_fields>
                <field>
                    <name>gender</name>
                    <value>Male</value>
                </field>
                <field>
                    <name>city</name>
                    <value>Bangalore</value>
                </field>
                <field>
                    <name>dob</name>
                    <value>1998-12-01</value>
                </field>
            </extended_fields>
            <subscriptions></subscriptions>
            <side_effects></side_effects>
            <item_status>
                <success>true</success>
                <code>1000</code>
                <message>Customer registration successful</message>
                <warnings>
                    <warning>1017</warning>
                </warnings>
            </item_status>
        </customer>
        <customer>
            <user_id>343445382</user_id>
            <firstname>Rita</firstname>
            <lastname>John</lastname>
            <mobile>44700900011</mobile>
            <email>rita.john@example.com</email>
            <external_id>XYPZ006</external_id>
            <lifetime_points>0</lifetime_points>
            <loyalty_points>0</loyalty_points>
            <current_slab>bronze</current_slab>
            <tier_expiry_date>2112-09-11 23:59:59</tier_expiry_date>
            <points_summaries>
                <points_summary>
                    <programId>1016</programId>
                    <redeemed>0</redeemed>
                    <expired>0</expired>
                    <returned>0</returned>
                    <adjusted>0</adjusted>
                    <lifetimePoints>0</lifetimePoints>
                    <loyaltyPoints>0</loyaltyPoints>
                    <cumulativePurchases>0</cumulativePurchases>
                    <currentSlab>bronze</currentSlab>
                    <nextSlab>silver</nextSlab>
                    <nextSlabSerialNumber>2</nextSlabSerialNumber>
                    <nextSlabDescription>silver</nextSlabDescription>
                    <slabSNo>1</slabSNo>
                    <slabExpiryDate>2112-09-11 23:59:59</slabExpiryDate>
                    <totalPoints></totalPoints>
                </points_summary>
            </points_summaries>
            <lifetime_purchases>0</lifetime_purchases>
            <registered_on>2012-09-11 11:11:15</registered_on>
            <updated_on>2019-12-09 11:19:23</updated_on>
            <type>LOYALTY</type>
            <source>instore</source>
            <fraud_status>NONE</fraud_status>
            <custom_fields></custom_fields>
            <extended_fields>
                <field>
                    <name>gender</name>
                    <value>Female</value>
                </field>
                <field>
                    <name>city</name>
                    <value>Bangalore</value>
                </field>
                <field>
                    <name>dob</name>
                    <value>1998-09-01</value>
                </field>
            </extended_fields>
            <subscriptions>
                <subscription>
                    <channel>SMS</channel>
                    <priority>TRANS</priority>
                    <scope>ALL</scope>
                    <status>0</status>
                </subscription>
                <subscription>
                    <channel>EMAIL</channel>
                    <priority>BULK</priority>
                    <scope>ALL</scope>
                    <status>0</status>
                </subscription>
                <subscription>
                    <channel>SMS</channel>
                    <priority>BULK</priority>
                    <scope>ALL</scope>
                    <status>0</status>
                </subscription>
                <subscription>
                    <channel>EMAIL</channel>
                    <priority>TRANS</priority>
                    <scope>ALL</scope>
                    <status>0</status>
                </subscription>
            </subscriptions>
            <side_effects></side_effects>
            <item_status>
                <success>true</success>
                <code>1000</code>
                <message>Customer registration successful</message>
                <warnings>
                    <warning>1017</warning>
                </warnings>
            </item_status>
        </customer>
    </customers>
</response>

<?xml version="1.0" encoding="UTF-8"?>
<root>
   <response>
      <customers>
         <customer>
            <element>
               <current_slab>bronze</current_slab>
               <custom_fields>
                  <field />
               </custom_fields>
               <email>tom@example.com</email>
               <extended_fields>
                  <field>
                     <element>
                        <name>gender</name>
                        <value>Male</value>
                     </element>
                     <element>
                        <name>city</name>
                        <value>Bangalore</value>
                     </element>
                     <element>
                        <name>dob</name>
                        <value>1998-12-01</value>
                     </element>
                  </field>
               </extended_fields>
               <external_id>TOM345</external_id>
               <firstname>Tom</firstname>
               <item_status>
                  <code>1000</code>
                  <message>Customer registration successful</message>
                  <success>true</success>
                  <warnings>
                     <warning>
                        <element>1017</element>
                     </warning>
                  </warnings>
               </item_status>
               <lastname>Cruise</lastname>
               <lifetime_points>0</lifetime_points>
               <lifetime_purchases>0</lifetime_purchases>
               <loyalty_points>0</loyalty_points>
               <mobile>44700900000</mobile>
               <points_summaries>
                  <points_summary>
                     <element>
                        <adjusted>0</adjusted>
                        <cumulativePurchases>0</cumulativePurchases>
                        <currentSlab>bronze</currentSlab>
                        <expired>0</expired>
                        <lifetimePoints>0</lifetimePoints>
                        <loyaltyPoints>0</loyaltyPoints>
                        <nextSlab>silver</nextSlab>
                        <nextSlabDescription>silver</nextSlabDescription>
                        <nextSlabSerialNumber>2</nextSlabSerialNumber>
                        <programId>1016</programId>
                        <redeemed>0</redeemed>
                        <returned>0</returned>
                        <slabExpiryDate>2112-09-11 23:59:59</slabExpiryDate>
                        <slabSNo>1</slabSNo>
                        <totalPoints />
                     </element>
                  </points_summary>
               </points_summaries>
               <registered_on>2012-09-11 11:11:11</registered_on>
               <side_effects>
                  <effect />
               </side_effects>
               <source>instore</source>
               <subscriptions>
                  <subscription />
               </subscriptions>
               <tier_expiry_date>2112-09-11 23:59:59</tier_expiry_date>
               <type>LOYALTY</type>
               <updated_on>2019-12-09 11:19:23</updated_on>
               <user_id>343445381</user_id>
            </element>
            <element>
               <current_slab>bronze</current_slab>
               <custom_fields>
                  <field />
               </custom_fields>
               <email>rita.john@example.com</email>
               <extended_fields>
                  <field>
                     <element>
                        <name>gender</name>
                        <value>Female</value>
                     </element>
                     <element>
                        <name>city</name>
                        <value>Bangalore</value>
                     </element>
                     <element>
                        <name>dob</name>
                        <value>1998-09-01</value>
                     </element>
                  </field>
               </extended_fields>
               <external_id>XYPZ006</external_id>
               <firstname>Rita</firstname>
               <fraud_status>NONE</fraud_status>
               <item_status>
                  <code>1000</code>
                  <message>Customer registration successful</message>
                  <success>true</success>
                  <warnings>
                     <warning>
                        <element>1017</element>
                     </warning>
                  </warnings>
               </item_status>
               <lastname>John</lastname>
               <lifetime_points>0</lifetime_points>
               <lifetime_purchases>0</lifetime_purchases>
               <loyalty_points>0</loyalty_points>
               <mobile>44700900011</mobile>
               <points_summaries>
                  <points_summary>
                     <element>
                        <adjusted>0</adjusted>
                        <cumulativePurchases>0</cumulativePurchases>
                        <currentSlab>bronze</currentSlab>
                        <expired>0</expired>
                        <lifetimePoints>0</lifetimePoints>
                        <loyaltyPoints>0</loyaltyPoints>
                        <nextSlab>silver</nextSlab>
                        <nextSlabDescription>silver</nextSlabDescription>
                        <nextSlabSerialNumber>2</nextSlabSerialNumber>
                        <programId>1016</programId>
                        <redeemed>0</redeemed>
                        <returned>0</returned>
                        <slabExpiryDate>2112-09-11 23:59:59</slabExpiryDate>
                        <slabSNo>1</slabSNo>
                        <totalPoints />
                     </element>
                  </points_summary>
               </points_summaries>
               <registered_on>2012-09-11 11:11:15</registered_on>
               <side_effects>
                  <effect />
               </side_effects>
               <source>instore</source>
               <subscriptions>
                  <subscription>
                     <element>
                        <channel>SMS</channel>
                        <priority>TRANS</priority>
                        <scope>ALL</scope>
                        <status>0</status>
                     </element>
                     <element>
                        <channel>EMAIL</channel>
                        <priority>BULK</priority>
                        <scope>ALL</scope>
                        <status>0</status>
                     </element>
                     <element>
                        <channel>SMS</channel>
                        <priority>BULK</priority>
                        <scope>ALL</scope>
                        <status>0</status>
                     </element>
                     <element>
                        <channel>EMAIL</channel>
                        <priority>TRANS</priority>
                        <scope>ALL</scope>
                        <status>0</status>
                     </element>
                  </subscription>
               </subscriptions>
               <tier_expiry_date>2112-09-11 23:59:59</tier_expiry_date>
               <type>LOYALTY</type>
               <updated_on>2019-12-09 11:19:23</updated_on>
               <user_id>343445382</user_id>
            </element>
         </customer>
      </customers>
      <status>
         <code>200</code>
         <message>Success</message>
         <success>true</success>
         <success_count>2</success_count>
         <total>2</total>
      </status>
   </response>
</root>

Registers customers in the org’s loyalty program with the primary identifier (mobile number/email id/external id).

Updates existing customer details (other than identifiers such as mobile number, email id, and external id) if you try registering an existing identifier.

Behavior of the API when an existing identifier is passed. * Updates existing customer details other than existing identifier(s) such as mobile number, email id, or external id. * Updates null identifiers from null to a value, but not value to value. Existing identifiers cannot be updated. * Updates secondary identifiers if the respective configuration is enabled on InTouch Profile > Organization Settings > Miscellaneous > Registration Configuration page. * CONF_ALLOW_MOBILE_UPDATE (for mobile number). * CONF_ALLOW_EMAIL_UPDATE (for email id). * CONF_LOYALTY_ALLOW_EXTERNAL_ID_UPDATE (for external id). * If CONFIG_SKIP_SECONDARY_ID_ON_PRIMARY_MISMATCH is enabled, if the primary identifier is different but any of the secondary identifiers exist, a new customer is registered with the primary identifier ignoring the secondary identifier. The config is available on the Registration Page of InTouch Profile > Organization Settings > Miscellaneous. * Also, this config overrides CONF_PRIMARY_IDENTIFIER_STRICT_CHECK. * Adds/updates custom field details. * Adds/updates extended field values.

Resource Information

URI customer/add
Authentication Yes
HTTP Method POST
Batch Support Yes

Request URL

https://{host}/v1.1/customer/add?format={xml/json}

Request Body Parameters

The mandatory attributes for customer registration depends on the configurations set on InTouch Settings > Registration Configuration. You need to know your org configurations before using this API.

Parameter Datatype Description
mobile** long Mobile number of the customer with country code.
email** string Email ID of the customer.
external_id** string External ID of the customer if applicable for the org.
firstname string First name of the customer.
lastname string Last name of the customer.
card_number string Card number to issue to the customer. Applicable for manual (auto_generate disabled) card issual.
series_code string Unique series code from which the card needs to issue. Applicable for auto-generated card issual.
type enum Type of registration. Values: LOYALTY (for loyalty customer), NON_LOYALTY (registered one or more identifiers but not enrolled in the loyalty program), NOT_INTERESTED (not interested to register identifiers or enrol in the loyalty program).
registered_on date-time Date on which the customer is registered. Format: YYYY-MM-DD HH:MM:SS,
Example: 2016-09-11 11:11:11
registered_till string The TILL at which customer is registered.
associated_with string Till code that you want to associate with the customer.
custom_fields obj Provide the custom field values of the customer in name and value pairs. You can only pass custom fields that are configured for the org.
extended_fields obj Provide the extended field details of the customer in name and value pairs. You can only pass extended fields that are configured for the org.
subscriptions obj Provide the subscription details of the customer.
priority enum Type of message. Value: TRANS for personalized or transaction messages, BULK for promotional messages.
is_subscribed enum Specify 1 for subscribed, 0 for unsubscribed.
channel enum Current communication channel. Value: sms, email.
side_effects obj Effect of customer registration on other things.

Response Parameters

Parameter Datatype Description
user_id long Unique ID of the customer generated by the system.
total int Number of customers passed for registration.
success_count int Number of customers that registered successfully.
lifetime_points int Total loyalty points earned by the customer to date.
lifetime_purchases int Total purchases amount (loyalty or non-loyalty transactions) of the customer across all stores of the org.
loyalty_points int Current active loyalty points (neither redeemed nor expired) of the customer.
current_slab string Current loyalty tier of the customer.
tier_expiry_date date-time Expiry date of the current tier in YYYY-MM-DD HH:MM:SS format.
points_summaries obj Shows the details of the loyalty points.
programId long Unique ID of the loyalty program associated to the points summary.
redeemed int In total points earned from the program, the total number of points that are redeemed.
expired int In total points earned from the program, the total number of points that are expired.
returned int In total points earned from the program, the total number of points that are returned. Usually, for transaction returns.
adjusted int Points that are either credited to or debited from the customer account in adjustments. The value will be negative if debited points are more than credited, and positive if credited points are more than debited.
cumulativePurchases double Total purchases amount of the customer in the stores associated to the current loyalty program.
currentSlab string Current tier of the customer in the loyalty program.
nextSlab string Next loyalty tier of the customer.
nextSlabSerialNumber int Serial number of the next tier. Lowest tier will have 1, succeeding tier will have 2 and so on.
nextSlabDescription string Description of the next tier as saved in the loyalty program.
slabSNo int Serial number of the current tier of the customer. Lowest tier will have 1, succeeding tier will have 2 and so on.
slabExpiryDate date-time Expiry date of the current loyalty tier of the customer in YYYY-MM-DD HH:MM:SS.
registered_on date-time Date on which the customer is enrolled in the org’s loyalty.
updated_on date-time Recent date on which the customer details are updated.
type enum Loyalty type of the customer. LOYALTY if the customer is enrolled in the org’s loyalty program, NON_LOYALTY if customer has not enrolled in the loyalty program but registered mobile number or email id with the org.
custom_fields obj Custom field details of the customer - custom field name (name) and custom field value (value).
extended_fields obj Extended field details of the customer - extended field name (name) and extended field value (value).
subscriptions obj Mobile number and email ID subscription details of the customer.
channel enum Subscription channel. Value: SMS, EMAIL.
priority enum Type of subscription. Value: TRANS for transaction or personalized messages, BULK for campaign or promotion messages.
status enum 0 for unsubscribed, 1 for subscribed.
side_effects obj Effect of customer registration in other details. For example, loyalty program.

Update Customer Details

Sample Request URL

https://us.api.capillarytech.com/v1.1/customer/update?format=json

Sample POST Request

{ 
   "root":{ 
      "customer":[ 
         { 
            "mobile":"44700900011",
            "email":"",
            "external_id":"",
            "firstname":"Rita",
            "lastname":"James",
            "updated_on":"2019-09-11 10:12:00",
            "registered_till":"",
            "associated_with":"",
            "type":"LOYALTY",
            "fraud_status":{ 
               "status":""
            },
            "subscriptions":{ 
               "subscription":[ 
                  { 
                     "priority":"TRANS",
                     "scope":"all",
                     "is_subscribed":"1",
                     "channel":"email"
                  },
                  { 
                     "priority":"BULK",
                     "scope":"all",
                     "is_subscribed":"0",
                     "channel":"email"
                  },
                  { 
                     "priority":"TRANS",
                     "scope":"all",
                     "is_subscribed":"1",
                     "channel":"sms"
                  },
                  { 
                     "priority":"BULK",
                     "scope":"all",
                     "is_subscribed":"1",
                     "channel":"sms"
                  }
               ]
            },
            "extended_fields":{ 
               "field":[ 
                  { 
                     "name":"gender",
                     "value":"male"
                  },
                  { 
                     "name":"Nationality",
                     "value":"Indian"
                  }
               ]
            },
            "custom_fields":{ 
               "field":[ 
                  { 
                     "name":"age",
                     "value":"[“46”]"
                  }
               ]
            }
         }
      ]
   }
}
<?xml version="1.0" encoding="UTF-8"?>
<root>
   <root>
      <customer>
         <element>
            <associated_with />
            <custom_fields>
               <field>
                  <element>
                     <name>age</name>
                     <value>[“46”]</value>
                  </element>
               </field>
            </custom_fields>
            <email />
            <extended_fields>
               <field>
                  <element>
                     <name>gender</name>
                     <value>male</value>
                  </element>
                  <element>
                     <name>Nationality</name>
                     <value>Indian</value>
                  </element>
               </field>
            </extended_fields>
            <external_id />
            <firstname>Rita</firstname>
            <fraud_status>
               <status />
            </fraud_status>
            <lastname>James</lastname>
            <mobile>917713643123</mobile>
            <ndnc_status />
            <registered_till />
            <subscriptions>
               <subscription>
                  <element>
                     <channel>email</channel>
                     <is_subscribed>1</is_subscribed>
                     <priority>TRANS</priority>
                     <scope>all</scope>
                  </element>
                  <element>
                     <channel>email</channel>
                     <is_subscribed>0</is_subscribed>
                     <priority>BULK</priority>
                     <scope>all</scope>
                  </element>
                  <element>
                     <channel>sms</channel>
                     <is_subscribed>1</is_subscribed>
                     <priority>TRANS</priority>
                     <scope>all</scope>
                  </element>
                  <element>
                     <channel>sms</channel>
                     <is_subscribed>1</is_subscribed>
                     <priority>BULK</priority>
                     <scope>all</scope>
                  </element>
               </subscription>
            </subscriptions>
            <type>LOYALTY</type>
            <updated_on>2019-09-11 10:12:00</updated_on>
         </element>
      </customer>
   </root>
</root>

Sample Response

{ 
   "response":{ 
      "status":{ 
         "success":"true",
         "code":200,
         "message":"Success",
         "total":"1",
         "success_count":"1"
      },
      "customers":{ 
         "customer":[ 
            { 
               "user_id":343445382,
               "firstname":"Rita",
               "lastname":"James",
               "mobile":"917713643123",
               "email":"rita.john@example.com",
               "external_id":"XYPZ006",
               "lifetime_points":0,
               "loyalty_points":0,
               "current_slab":"bronze",
               "tier_expiry_date":"2112-09-11 23:59:59",
               "points_summaries":{ 
                  "points_summary":[ 
                     { 
                        "programId":"1016",
                        "redeemed":"100",
                        "expired":"20",
                        "returned":"0",
                        "adjusted":"0",
                        "lifetimePoints":"2400",
                        "loyaltyPoints":"2280",
                        "cumulativePurchases":"23400",
                        "currentSlab":"bronze",
                        "nextSlab":"silver",
                        "nextSlabSerialNumber":"2",
                        "nextSlabDescription":"silver",
                        "slabSNo":"1",
                        "slabExpiryDate":"2119-09-11 23:59:59",
                        "totalPoints":""
                     }
                  ]
               },
               "lifetime_purchases":0,
               "registered_on":"2012-09-11 11:11:15",
               "updated_on":"2019-12-09 14:59:49",
               "type":"LOYALTY",
               "source":"instore",
               "fraud_status":"NONE",
               "custom_fields":{ 
                  "field":[ 

                  ]
               },
               "extended_fields":{ 
                  "field":[ 
                     { 
                        "name":"gender",
                        "value":"Male"
                     },
                     { 
                        "name":"city",
                        "value":"Bangalore"
                     },
                     { 
                        "name":"dob",
                        "value":"1998-09-01"
                     }
                  ]
               },
               "subscriptions":{ 
                  "subscription":[ 
                     { 
                        "channel":"SMS",
                        "priority":"BULK",
                        "scope":"ALL",
                        "status":"1"
                     },
                     { 
                        "channel":"SMS",
                        "priority":"TRANS",
                        "scope":"ALL",
                        "status":"1"
                     },
                     { 
                        "channel":"EMAIL",
                        "priority":"BULK",
                        "scope":"ALL",
                        "status":"0"
                     },
                     { 
                        "channel":"EMAIL",
                        "priority":"TRANS",
                        "scope":"ALL",
                        "status":"1"
                     }
                  ]
               },
               "side_effects":{ 
                  "effect":[ 

                  ]
               },
               "item_status":{ 
                  "success":"true",
                  "code":"1000",
                  "message":"Customer successfully updated",
                  "warnings":{ 
                     "warning":[ 
                        "91017",
                        "1017"
                     ]
                  }
               }
            }
         ]
      }
   }
}
<?xml version="1.0" encoding="UTF-8"?>
<root>
   <response>
      <customers>
         <customer>
            <element>
               <current_slab>bronze</current_slab>
               <custom_fields>
                  <field />
               </custom_fields>
               <email>rita.john@example.com</email>
               <extended_fields>
                  <field>
                     <element>
                        <name>gender</name>
                        <value>Male</value>
                     </element>
                     <element>
                        <name>city</name>
                        <value>Bangalore</value>
                     </element>
                     <element>
                        <name>dob</name>
                        <value>1998-09-01</value>
                     </element>
                  </field>
               </extended_fields>
               <external_id>XYPZ006</external_id>
               <firstname>Rita</firstname>
               <fraud_status>NONE</fraud_status>
               <item_status>
                  <code>1000</code>
                  <message>Customer successfully updated</message>
                  <success>true</success>
                  <warnings>
                     <warning>
                        <element>91017</element>
                        <element>1017</element>
                     </warning>
                  </warnings>
               </item_status>
               <lastname>James</lastname>
               <lifetime_points>0</lifetime_points>
               <lifetime_purchases>0</lifetime_purchases>
               <loyalty_points>0</loyalty_points>
               <mobile>917713643123</mobile>
               <points_summaries>
                  <points_summary>
                     <element>
                        <adjusted>0</adjusted>
                        <cumulativePurchases>23400</cumulativePurchases>
                        <currentSlab>bronze</currentSlab>
                        <expired>20</expired>
                        <lifetimePoints>2400</lifetimePoints>
                        <loyaltyPoints>2280</loyaltyPoints>
                        <nextSlab>silver</nextSlab>
                        <nextSlabDescription>silver</nextSlabDescription>
                        <nextSlabSerialNumber>2</nextSlabSerialNumber>
                        <programId>1016</programId>
                        <redeemed>100</redeemed>
                        <returned>0</returned>
                        <slabExpiryDate>2112-09-11 23:59:59</slabExpiryDate>
                        <slabSNo>1</slabSNo>
                        <totalPoints />
                     </element>
                  </points_summary>
               </points_summaries>
               <registered_on>2012-09-11 11:11:15</registered_on>
               <side_effects>
                  <effect />
               </side_effects>
               <source>instore</source>
               <subscriptions>
                  <subscription>
                     <element>
                        <channel>SMS</channel>
                        <priority>BULK</priority>
                        <scope>ALL</scope>
                        <status>1</status>
                     </element>
                     <element>
                        <channel>SMS</channel>
                        <priority>TRANS</priority>
                        <scope>ALL</scope>
                        <status>1</status>
                     </element>
                     <element>
                        <channel>EMAIL</channel>
                        <priority>BULK</priority>
                        <scope>ALL</scope>
                        <status>0</status>
                     </element>
                     <element>
                        <channel>EMAIL</channel>
                        <priority>TRANS</priority>
                        <scope>ALL</scope>
                        <status>1</status>
                     </element>
                  </subscription>
               </subscriptions>
               <tier_expiry_date>2112-09-11 23:59:59</tier_expiry_date>
               <type>LOYALTY</type>
               <updated_on>2019-12-09 14:59:49</updated_on>
               <user_id>343445382</user_id>
            </element>
         </customer>
      </customers>
      <status>
         <code>200</code>
         <message>Success</message>
         <success>true</success>
         <success_count>1</success_count>
         <total>1</total>
      </status>
   </response>
</root>

Lets you update the details of an existing customer other than primary or secondary identifiers. If any of the identifiers you pass already exists for a different account, then the customer details will be merged automatically.

API Behavior:

Resource Information

URI customer/update
Authentication Yes
HTTP Method POST
Batch Support No

Request URL

https://{host}/v1.1/customer/update?format={xml/json}

Request Body Parameters

Parameter Datatype Description
Mobile/email/external_id/id* string Pass any one of the following identifiers of the customer whose details you want to update.
firstname string First name of the customer.
lastname string Last name of the customer.
registered_on date-time Date on which the customer is registered. Format: YYYY-MM-DD HH:MM:SS,
Example: 2016-09-11 11:11:11
registered_till string The TILL at which customer is registered.
associated_with string Till code that you want to associate with the customer.
type enum Pass LOYALTY to convert a non_loyalty customer to loyalty. You cannot change a loyalty customer non-loyalty (NON_LOYALTY).
custom_fields obj Provide the custom field values of the customer in name and value pairs. You can only pass custom fields that are configured for the org.
extended_fields obj Provide the extended field details of the customer in name and value pairs. You can only pass extended fields that are configured for the org.
subscriptions obj Provide the subscription details of the customer.
priority enum Type of message. Value: TRANS for personalized or transaction messages, BULK for promotional messages.
channel enum Current communication channel. Value: sms, email.
fraud_status obj Update the fraud status of the customer in status. Values: CONFIRMED, NONE.

Response Parameters

Parameter Datatype Description
user_id long Unique ID of the customer generated by the system.
total int Number of customers passed for registration.
success_count int Number of customers that registered successfully.
lifetime_points int Total loyalty points earned by the customer to date.
lifetime_purchases int Total purchases amount (loyalty or non-loyalty transactions) of the customer across all stores of the org.
loyalty_points int Current active loyalty points (neither redeemed nor expired) of the customers.
current_slab string Current loyalty tier of the customer.
tier_expiry_date date-time Expiry date of the current tier in YYYY-MM-DD HH:MM:SS format.
points_summaries obj Shows the details of the loyalty points.
programId long Unique ID of the loyalty program associated to the points summary.
redeemed int In total points earned from the program, the total number of points that are redeemed.
expired int In total points earned from the program, the total number of points that are expired.
returned int In total points earned from the program, the total number of points that are returned. Usually, for transaction returns.
adjusted int Points that are either credited to or debited from the customer account in adjustments. The value will be negative if debited points are more than credited, and positive if credited points are more than debited.
cumulativePurchases double Total purchases amount of the customer in the stores associated to the current loyalty program.
currentSlab string Current tier of the customer in the loyalty program.
nextSlab string Next loyalty tier of the customer.
nextSlabSerialNumber int Serial number of the next tier. Lowest tier will have 1, succeeding tier will have 2 and so on.
nextSlabDescription string Description of the next tier as saved in the loyalty program.
slabSNo int Serial number of the current tier of the customer. Lowest tier will have 1, succeeding tier will have 2 and so on.
slabExpiryDate date-time Expiry date of the current loyalty tier of the customer in YYYY-MM-DD HH:MM:SS.
registered_on date-time Date on which the customer is enrolled in the org’s loyalty.
updated_on date-time Recent date on which the customer details are updated.
type enum Loyalty type of the customer. LOYALTY if the customer is enrolled in the org’s loyalty program, NON_LOYALTY if customer has not enrolled in the loyalty program but registered mobile number or email id with the org.
custom_fields obj Custom field details of the customer - custom field name (name) and custom field value (value).
extended_fields obj Extended field details of the customer - extended field name (name) and extended field value (value).
subscriptions obj Mobile number and email ID subscription details of the customer.
channel enum Subscription channel. Value: SMS, EMAIL.
priority enum Type of subscription. Value: TRANS for transaction or personalized messages, BULK for campaign or promotion messages.
status enum 0 for unsubscribed, 1 for subscribed.
side_effects obj

Update Customer Identifiers

Sample Request

https://us.api.capillarytech.com/v1.1/customer/update_identity?format=xml

Sample POST Request

{
   "root": {
      "customer": [
      {
         "identifier": "mobile",
         "old_value": "44700900000",
         "new_value": "44700900090"
      }
      ]
   }
}
<?xml version="1.0" encoding="UTF-8" ?>
<root>
    <customer>
        <identifier>mobile</identifier>  <!-- Pass mobile/email/external_id that you want to update -->
        <new_value>44700900090</new_value> 
        <old_value>44700900000</old_value>
    </customer>
</root>

Sample Response

{
   "response": {
      "status": {
         "success": "true",
         "code": "200",
         "message": "SUCCESS"
      },
      "customers": {
         "customer": {
            "identifier": "mobile",  
            "old_value": "44700900000",
            "new_value": "44700900090",
            "updated": "true",
            "item_status": {
               "success": "true",
               "code": "1040",
               "message": "Customer Identity change request added successfully"
            }
         }
      }
   }
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
   <status>
      <success>true</success>
      <code>200</code>
      <message>SUCCESS</message>
   </status>
   <customers>
      <customer>
         <identifier>mobile</identifier>  <!--mobile/email/external_id--> 
         <old_value>44700900000</old_value>
         <new_value>44700900090</new_value>
         <updated>true</updated>
         <item_status>
            <success>true</success>
            <code>1040</code>
            <message>Customer Identity change request added successfully</message>
         </item_status>
      </customer>
   </customers>
</response>

Lets you submit request to update primary and secondary identifiers (mobile no./email id/external id) of a loyalty customer. Requests submitted through customer/update_identity will be in pending state by default. Capillary back-end team verifies the requests and process it accordingly.

Resource Information

URI customer/update_identity
Authentication Yes
HTTP Method POST
Batch Support No

Request URL

https://{host}/v1.1/customer/update_identity?format={xml/json}

Request Body Parameters

Parameter Datatype Description
identifier* enum Pass the identifier name that you want to update. Value: mobile, email, external_id.
old_value* string Provide the existing value the identifier that you want to update.
new_value* string Provide the new value of the identifier.

Response Parameters

Parameter Datatype Description
identifier* enum Name of the identifier.
old_value* string Earlier value of the identifier.
new_value* string New identifier value.
updated boolean Returns true if the the identifier is updated successfully.

Sample Request

https://us.api.capillarytech.tech.com/v1.1/customer/search?q=(slab:EQUALS:CLASSIC)

Sample Response

{
   "response":{
      "status":{
         "success":"true",
         "code":"200",
         "message":"SUCCESS"
      },
      "customer":{
         "count":"2",
         "start":"0",
         "rows":"10",
         "results":{
            "item":[
               {
                  "user_id":"102",
                  "org_id":"29",
                  "firstname":"Tom",
                  "lastname":"Sawyer",
                  "mobile":"44700900000",
                  "email":"tom.sawyer@example.com",
                  "external_id":"None",
                  "loyalty_points":"355",
                  "lifetime_points":"5400",
                  "lifetime_purchases":"10800",
                  "current_slab":"CLASSIC",
                  "registered_on":"2012-12-25 11:25:32",
                  "registered_by":"pe.london.bondstreet",
                  "last_trans_value":"1000",
                  "attributes":{
                     "attribute":{
                        "name":"customer_age",
                        "value":"26-35"
                     }
                  }
               },
               {
                  "user_id":"122",
                  "org_id":"29",
                  "firstname":"John",
                  "lastname":"Smith",
                  "mobile":"44700900888",
                  "email":"john.smith@example.com",
                  "external_id":"None",
                  "loyalty_points":"355",
                  "lifetime_points":"355",
                  "lifetime_purchases":"4598",
                  "current_slab":"CLASSIC",
                  "registered_on":"2012-12-25 11:25:32",
                  "registered_by":"px.london.bondstreet",
                  "last_trans_value":"1000",
                  "attributes":{
                     "attribute":[
                        {
                           "name":"occupation",
                           "value":"Student"
                        },
                        {
                           "name":"customer_age",
                           "value":"19-25"
                        }
                     ]
                  }
               }
            ]
         }
      }
   }
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
   <status>
      <success>true</success>
      <code>200</code>
      <message>SUCCESS</message>
   </status>
   <customer>
      <count>2</count>
      <start>0</start>
      <rows>10</rows>
      <results>
         <item>
            <user_id>102</user_id>
            <org_id>29</org_id>
            <firstname>Tom</firstname>
            <lastname>Sawyer</lastname>
            <mobile>44700900000</mobile>
            <email>tom.sawyer@example.com</email>
            <external_id>None</external_id>

            <loyalty_points>355</loyalty_points>
            <lifetime_points>5400</lifetime_points>
            <lifetime_purchases>10800</lifetime_purchases>
            <current_slab>CLASSIC</current_slab>
            <registered_on>2012-12-25 11:25:32</registered_on>
            <registered_by>pe.london.bondstreet</registered_by>
            <last_trans_value>1000</last_trans_value>
            <attributes>
               <attribute>
                  <name>customer_age</name>
                  <value>26-35</value>
               </attribute>
            </attributes>
         </item>
         <item>
            <user_id>122</user_id>
            <org_id>29</org_id>
            <firstname>John</firstname>
            <lastname>Smith</lastname>
            <mobile>44700900888</mobile>
            <email>john.smith@example.com</email>
            <external_id>None</external_id>
            <loyalty_points>355</loyalty_points>
            <lifetime_points>355</lifetime_points>
            <lifetime_purchases>4598</lifetime_purchases>
            <current_slab>CLASSIC</current_slab>
            <registered_on>2012-12-25 11:25:32</registered_on>
            <registered_by>pe.london.bondstreet</registered_by>
            <last_trans_value>1000</last_trans_value>
            <attributes>
               <attribute>
                  <name>occupation</name>
                  <value>Student</value>
               </attribute>
               <attribute>
                  <name>customer_age</name>
                  <value>19-25</value>
               </attribute>
            </attributes>
         </item>
      </results>
   </customer>
</response>


Lets you fetch customers based on partial or complete keywords passed. You can fetch customers by name, customer identifier, registered store id, registered date, loyalty points, lifetime points, lifetime purchases amount, current tier, transaction amount, and custom field values.

Resource Information

URI customer/search?q=({param}:{Query}:{value})&format={xml/json}
Authentication Yes
HTTP Method GET
Batch Support Yes

Request URL

https://{host}/v1.1/customer/search?q=({param}:{Operator}:{value})&format={xml/json}

Request Query Parameters

You need to understand Query Grammar to learn how to use input parameters for customer/search API. For more details, see the Query Grammar section.

Parameter Datatype Description
firstname string Retrieves the list of customers whose first name matches with the string passed.
Query: firstname:EXACT:{first name}
lastname string Retrieves the list of customers whose last name matches with the string passed.
Query: lastname:EXACT:{last Name}
org_id long Retrieves the list of entire customers of the respective organization.
Query: org_id:EQUALS:{org_id}
mobile string Retrieves customers whose registered mobile numbers matches with the string passed.
Query: mobile:EQUALS:{mobile_number}
email string Retrieves the list of registered customers whose email id matches with the string passed.
Query: email:EQUALS:{email_id}
external_id string Retrieves customers whose external id matches with the string passed.
Query: external_id:EQUALS:{external_id}
registered_date date Retrieves customers by registered date.
Query: registered_date:ON:{date in YYYY-MM-DD}.
loyalty_points int Retrieves the list of customers whose active loyalty points matches the specified query.
Query: loyalty_points:GREATER:{loyalty_points}
lifetime_points int Retrieves the list of customers whose lifetime points matches the specified query.
Query: lifetime_points:GREATER:{lifetime_points}
lifetime_purchases int Retrieves the list of customers whose lifetime purchases amount matches the specified query. Query: lifetime_purchases:GREATER:{lifetime_purchases}
slab string Retrieves the list of customers whose current loyalty tier matches the specified value.
Query: slab:EQUALS:{tier_name}
registered_store string Retrieves customers by registered store.
Query: registered_store:EQUALS:{store_id}
last_trans_value double Retrieves the list of customers whose transaction amount matches the specified query.
Query: transaction_value:GREATER:{transaction_amount}
Operator enum Predefined conditions based on which you want to fetch results. Values: STARTS, ENDS, EXACT, RANGE, LESS, GREATER, EQUALS, IN. For more details, see the following section, Search Query Grammar.

Search Query Grammar

The following is a formal definition of the Query Grammar

QUERY: (CONDITION) | (CONDITION & (CONDITION)*)

CONDITION: ATTRIBUTE:OPERATOR:VALUES

ATTRIBUTE: Set of inventory/customer attributes that are searchable.

Dynamic List * OPERATOR: STARTS, ENDS, EXACT, RANGE, LESS, GREATER, EQUALS, IN, ON * VALUES: ALPHANUMERIC | ALPHANUMERIC;ALPHANUMERIC(for RANGE, IN OPERATOR, separator is ’;’ )

Response Parameters

Parameter Datatype Description
count int Number of customer results retrieved.
item obj Details of each customer.
user_id long Unique ID of the customer generated by the system.
lifetime_points int Total loyalty points earned by the customer to date.
lifetime_purchases int Total purchases amount (loyalty or non-loyalty transactions) of the customer across all stores of the org.
loyalty_points int Current active loyalty points (neither redeemed nor expired) of the customers.
current_slab string Current loyalty tier of the customer.
registered_on date-time Date on which the customer is enrolled in the org’s loyalty.
registered_by string TILL or store code from which the customer is enrolled in the loyalty program.
last_trans_value double Bill amount of the recent transaction of the customer.
attributes obj Customer attribute details in name and value

Get Customer Details

Sample Request URL

https://us.api.capillarytech.com/v1.1/customer/get?mobile=919889999999&mlp=true

Sample Response

{
   "status": {
      "success": "true",
      "code": "200",
      "message": "Success",
      "total": "1",
      "success_count": "1"
   },
   "customers": {
      "customer": {
         "firstname": "Tom",
         "lastname": "Sawyer",
         "mobile": "91900000000",
         "email": "tom.sawyer@example.com",
         "external_id": "TS123",
         "lifetime_points": "2300",
         "lifetime_purchases": "25000",
         "loyalty_points": "500",
         "current_slab": "Silver",
         "registered_on": "2017-05-31 14:57:04",
         "updated_on": "2018-05-31 14:57:04",
         "type": "LOYALTY",
         "source": "instore",
         "identifiers": [],
         "gender": "Male",
         "registered_by": "Jim",
         "registered_store": {
            "code": "autotest2_one",
            "name": "autotest2_one"
         },
         "registered_till": {
            "code": "one.till01",
            "name": "one.till01"
         },
         "fraud_details": {
            "status": "NONE",
            "marked_by": [],
            "modified_on": []
         },
         "trackers": [],
         "current_nps_status": [],
         "custom_fields": {
            "field": {
               "name": "gender",
               "value": "value_308645"
            }
         },
         "extended_fields": {
            "field": []
         },
         "transactions": {
            "transaction": []
         },
         "coupons": [
            {
               "id": "44521519",
               "series_id": "19293",
               "code": "4OZ1UDDA",
               "description": "API Coupon 3",
               "created_date": "2018-05-31 14:57:06",
               "valid_till": "2018-06-30 23:59:59",
               "redeemed": "true"
            },
            {
               "id": "44521520",
               "series_id": "19290",
               "code": "ZBW1S4QT",
               "description": "API Series",
               "created_date": "2018-05-31 14:57:07",
               "valid_till": "2018-06-01 23:59:59",
               "redeemed": "false"
            }
         ],
         "notes": [],
         "item_status": {
            "success": "true",
            "code": "1000",
            "message": "Customer successfully retrieved",
            "warnings": []
         }
      }
   }
}

Sample Response snippet of gap_to_upgrade_for


# For upgrade based on tracker strategy

"gap_to_upgrade": {
  "upgrade_strategy": [
    {
      "upgrade_based_on": "TRACKER_VALUE_BASED",
      "upgrade_entity_identifers": {
        "tracker_name": "2 Years Upgrade Tracker",
        "tracker_type": "BILL_AMOUNT",
        "tracker_mode": "MOVING_WINDOW",
        "tracker_case_name": "730Days_Case",
        "tracker_case_period_type": "DAYS",
        "tracker_case_period_value": "730"
      },
      "upgrade_threshold": "25000",
      "customer_upgrade_entity_values": {
        "current_value": "9786",
        "gap_to_upgrade": "15214",
        "value_valid_upto": "2022-05-06"
      }
    }
  ]
}


Sample Response snippet of gap_to_renew_for


# For upgrade based on lifetime points

...
"gap_to_renew": {
  "tier_expiry_date": "2020-09-03",
  "renew_confirmed": "false",
  "renew_strategy": [
    {
      "renew_based_on": "VISITS",
      "renew_entity_identifiers": {},
      "renew_threshold": "56000",
      "customer_renew_entity_value": "1",
      "customer_gap_to_renew_value": "55999"
    },
    {
      "renew_based_on": "PURCHASE",
      "renew_entity_identifiers": {},
      "renew_threshold": "30000",
      "customer_renew_entity_value": "1200",
      "customer_gap_to_renew_value": "28800"
    },
    {
      "renew_based_on": "POINTS",
      "renew_entity_identifiers": {},
      "renew_threshold": "50000",
      "customer_renew_entity_value": "460",
      "customer_gap_to_renew_value": "49540"
    }
  ]
}


<?xml version="1.0" encoding="UTF-8"?>
<response>
   <status>
      <success>true</success>
      <code>200</code>
      <message>Success</message>
      <total>1</total>
      <success_count>1</success_count>
   </status>
   <customers>
      <customer>
         <firstname>Tom</firstname>
         <lastname>Sawyer</lastname>
         <mobile>91900000000</mobile>
         <email>tom.sawyer@example.com</email>
         <external_id>TS123</external_id>
         <lifetime_points>2300</lifetime_points>
         <lifetime_purchases>25000</lifetime_purchases>
         <loyalty_points>500</loyalty_points>
         <current_slab>Silver</current_slab>
         <registered_on>2017-05-31 14:57:04</registered_on>
         <updated_on>2018-05-31 14:57:04</updated_on>
         <type>LOYALTY</type>
         <source>instore</source>
         <identifiers />
         <gender>Male</gender>
         <registered_by>Jim</registered_by>
         <registered_store>
            <code>autotest2_one</code>
            <name>autotest2_one</name>
         </registered_store>
         <registered_till>
            <code>one.till01</code>
            <name>one.till01</name>
         </registered_till>
         <fraud_details>
            <status>NONE</status>
            <marked_by />
            <modified_on />
         </fraud_details>
         <trackers />
         <current_nps_status />
         <custom_fields>
            <field>
               <name>gender</name>
               <value>value_308645</value>
            </field>
         </custom_fields>
         <extended_fields>
            <field />
         </extended_fields>
         <transactions>
            <transaction />
         </transactions>
         <coupons>
            <coupon>
               <id>44521519</id>
               <series_id>19293</series_id>
               <code>4OZ1UDDA</code>
               <description>API Coupon 3</description>
               <created_date>2018-05-31 14:57:06</created_date>
               <valid_till>2018-06-30 23:59:59</valid_till>
               <redeemed>true</redeemed>
            </coupon>
            <coupon>
               <id>44521520</id>
               <series_id>19290</series_id>
               <code>ZBW1S4QT</code>
               <description>API Series</description>
               <created_date>2018-05-31 14:57:07</created_date>
               <valid_till>2018-06-01 23:59:59</valid_till>
               <redeemed>false</redeemed>
            </coupon>
         </coupons>
         <notes />
         <item_status>
            <success>true</success>
            <code>1000</code>
            <message>Customer successfully retrieved</message>
            <warnings />
         </item_status>
      </customer>
   </customers>
</response>

Retrieve details of a specific loyalty customer such as loyalty information, subscription status, 10 recent transactions, active coupons, recent store interactions, custom fields, extended fields, and customer’s unique id.

Resource Information

URI /get?{identifier_type}={value}&{query_params}
Authentication Yes
HTTP Methods GET
Batch Support Yes

Request URL

https://{host}/v1.1/customer/get?{identifierName}={identifierValue}&mlp=true&format={xml/json}

Additional Header

Header Description
language Specify the ISO language code to get customer level extended field details in your preferred language (other than English). For example, zh for Chinese, id for Indonesian, ar for Arabic.

Request Query Parameters

Parameter Datatype Description
identifierName enum Pass any one of the registered identifier names of the customer. Value: mobile, email, external_id, card_number, card_external_id.
identifierValue string Pass the respective identifier value.
For example, mobile=44700900000. To retrieve details of multiple customers at a time, pass each value separating with comma (,) For example, mobile=44700900000,44700900999,4470090345.
coupon_limit int Limits the number of coupon interactions (issued,redeemed and expired). Example: coupon_limit=5 retrieves five recent coupon interactions.
coupon_offset int Retrieves next set of coupons according to issual sequence. For example, if 10 coupons are issued to a customer till date, then coupon_offset=6, returns the 7th, 8th, 9th, and 10th coupon (ignoring the first 6 coupons).
coupon_order_by enum What basis you want the coupon history o order. Value: created_date (default), created_by, valid_till (to order by till name).
coupon_sort_order enum Value: asc, desc (default). Orders coupons in ascending or descending order based on the coupon_order_by value.
user_id=true - Returns the unique id of the customer (generated at our end when the customer is registered).
next_slab=true - Returns the details of the next loyalty tier of the customer such as
next_slab, next_slab_serial_number, next_slab_description, trackers value (for tracker based strategy), and current_nps_status.
slab_history=true - Returns the details of loyalty tier changes of the customer.
registered_store=true - Returns the store at which the customer is registered. This is returned by default.
registered_till=true - Returns the store-TILL at which the customer is registered. This is returned by default.
fraud_details=true - Returns the fraud details of a customer. This field is returned by default.
ndnc_status=true - Returns the status of the customer’s registered mobile number on NDNC/DND.
optin_status=true - Returns the services (SMS/email) to which the customer has opted in and opted out.
expiry_schedule=true - Returns the details of points expiry summary with number of points to expire, program ID, and date and time of expiry.
expired_points=true - Returns the details of expired points of the customer.
points_summary=true - Returns the history of points issued and redeemed.
promotion_points=true - Returns the history of promotional points issued and redeemed. It also shows the store that issued the points and expiry date for each set of points issued. You can get up to 1000 results (maximum limit).
membership_retention_criteria=true - Returns the criteria set for membership or tier retention (usually for membership based loyalty program).
tier_upgrade_criteria=true - Returns the tier upgrade criteria configured in tier_update_criteria object of response payload.
This is supported only if the tier upgrade strategy is based on Lifetime Points, Lifetime Purchases, or Current Points, but not on tracker based strategy. Also, you will not see upgrade criteria if the customer is in the highest tier.
mlp=true - Retrieves the loyalty information of the customer for each loyalty program including the gap to upgrade and gap to renew details. Different program details are applicable only for brands with multiple loyalty programs (MLP).
gap_to_upgrade_for int See the gap after a specific number of days from the current day. Gap is the value of the tier upgrade parameter (purchases/points/tracker) yet to allocate to upgrade the customer’s current tier. Pass 0 to get the gap as of the current day, 1 to get the gap as of the next day, 30 to get the gap as of the 30th day from the current day. The gap might change with days for tracker value based tier upgrade strategy. No negative values are supported.
gap_to_renew_for int See the gap after a specific number of days from the current day. The required value of purchases/visits/points/tracker to renew the tier (as per the configuration in tier downgrade strategy). Pass 0 to get the renewal value as of the current day, 1 to get renewal value as of the next day, 30 to get the renewal value as of the 30th day from the current day. No negative value is supported.
user_group=true - Retrieves the details of user group associated to the user (if available).
customer_image=true - Retrieves the customer’s profile image.
transactions=true - Retrieves transaction details of the customer.
subscriptions=true - Retrieves subscription details of the customer.
segments=true - Retrieves segment details of the customer if applicable. Segments are logical grouping of customers based on one or more parameters.
member_care_access=true - For admin users, it will show customers that are active within the vicinity of that user.
card_details=true - Retrieves the details of all cards of the customers.
tracker_info=true -
delayed_accrual=true -
coupon_active=true -
basic=true -
program_id int
coupon_offer int Default value - 0.
coupon_org_entity_type string
coupon_org_entity_value string
coupon_status string

Response Parameters

Parameter Datatype Description
user_id long Unique ID of the customer generated by the system.
lifetime_points int Total loyalty points earned by the customer to date.
lifetime_purchases int Total purchases amount (loyalty or non-loyalty transactions) of the customer across all stores of the org.
loyalty_points int Current active loyalty points (neither redeemed nor expired) of the customers.
current_slab string Current loyalty tier of the customer.
registered_on date-time Date on which the customer is enrolled in the org’s loyalty.
registered_by string TILL or store code from which the customer is enrolled in the loyalty program.
last_trans_value double Bill amount of the recent transaction of the customer.
attributes obj Customer attribute details in name and value

Get Customer Transactions

Sample Request

https://eu.api.capillarytech.com/v1.1/customer/transactions?format=json&mobile=44700900000&start_date=2020-04-03+23:45:45&end_date=2016-12-29+12:11:45

Sample Response

{
  "response": {
    "status": {
      "success": "true",
      "code": 200,
      "message": "Success"
    },
    "customer": {
      "firstname": "Tom",
      "lastname": "Sawyer",
      "user_id": "98662653",
      "mobile": "919740000000",
      "email": "tom.sawyer@example.com",
      "external_id": "anjvat123",
      "lifetime_points": 5730,
      "lifetime_purchases": 53609,
      "loyalty_points": 4776,
      "current_slab": "Albatross Elite",
      "registered_on": "2019-04-14 11:32:30",
      "updated_on": "2020-04-03 06:58:32",
      "type": "LOYALTY",
      "source": "instore",
      "count": 51,
      "start": "321260040",
      "delayed_points": "0",
      "delayed_returned_points": "0",
      "total_available_points": "0",
      "total_returned_points": "0",
      "rows": "10",
      "transactions": {
        "transaction": [
          {
            "id": "321260040",
            "number": "localcurrency0235",
            "type": "REGULAR",
            "return_type": "",
            "amount": "2000",
            "outlier_status": "NORMAL",
            "delivery_status": "DELIVERED",
            "notes": "Regular Bill with Payment Details",
            "billing_time": "2020-04-01 00:00:00",
            "auto_update_time": "2020-04-03 06:58:31",
            "gross_amount": "2000",
            "discount": "0",
            "store": "International Business Park",
            "store_code": "international_business_park",
            "returned_points_on_bill": "0.0",
            "currency": {
              "ratio": 1,
              "transaction_currency": {
                "supported_currency_id": 70275062,
                "name": "Indian Rupee ",
                "symbol": "₹"
              },
              "id": 70275062,
              "name": "Indian Rupee ",
              "symbol": "₹"
            },
            "points": {
              "issued": "200",
              "redeemed": "0",
              "returned": "0",
              "expired": "0",
              "returnedPointsOnBill": "0.0",
              "expiry_date": "2020-05-31 23:59:59",
              "program_id": "469"
            },
            "custom_fields": {
              "field": [
                {
                  "name": "",
                  "value": ""
                }
              ]
            },
            "extended_fields": {
              "field": []
            },
            "coupons": [],
            "basket_size": 0,
            "line_items": {
              "line_item": []
            }
          },
          {
            "id": "321156323",
            "number": "localcurrency020",
            "type": "REGULAR",
            "return_type": "",
            "amount": "2000",
            "outlier_status": "NORMAL",
            "delivery_status": "DELIVERED",
            "notes": "Regular Bill with Payment Details",
            "billing_time": "2020-04-01 00:00:00",
            "auto_update_time": "2020-04-02 08:37:02",
            "gross_amount": "2000",
            "discount": "0",
            "store": "International Business Park",
            "store_code": "international_business_park",
            "returned_points_on_bill": "0.0",
            "points": {
              "issued": "200",
              "redeemed": "0",
              "returned": "0",
              "expired": "0",
              "returnedPointsOnBill": "0.0",
              "expiry_date": "2020-05-31 23:59:59",
              "program_id": "469"
            },
            "custom_fields": {
              "field": [
                {
                  "name": "",
                  "value": ""
                }
              ]
            },
            "extended_fields": {
              "field": []
            },
            "coupons": [],
            "basket_size": 0,
            "line_items": {
              "line_item": []
            }
          }
        ]
      },
      "item_status": {
        "success": "true",
        "code": "1052",
        "message": "Transactions fetched successfully",
        "warnings": {
          "warning": []
        }
      }
    }
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status>
        <success>true</success>
        <code>200</code>
        <message>SUCCESS</message>
    </status>
    <customer>
        <mobile>44700900000</mobile>
        <email>tom.sawyer@example.com</email>
        <external_id>ts1234</external_id>
        <firstname>Tom</firstname>
        <lastname>Sawyer</lastname>
        <lifetime_points>13700</lifetime_points>
        <lifetime_purchases>138000</lifetime_purchases>
        <loyalty_points>12000</loyalty_points>
        <registered_on>2016-07-10 11:11:15</registered_on>
        <updated_on>2016-12-25 11:19:11</updated_on>
        <current_slab>gold</current_slab>
        <count>26</count>
        <start>23622808</start>
        <rows>10</rows>
        <transactions>
            <transaction>
                <id>23622808</id>
                <number>ANBDCGD</number>
                <type>REGULAR</type>
                <amount>3000</amount>
                <notes>Bill added by mobile</notes>
                <billing_time>2013-12-16 17:02:22</billing_time>
                <gross_amount>3000</gross_amount>
                <discount>10</discount>
                <store />
                <points>
                    <issued>30</issued>
                    <redeemed>20</redeemed>
                </points>
                <coupons />
                <basket_size>10</basket_size>
                <line_items>
                    <line_item />
                </line_items>
            </transaction>
        </transactions>
    </customer>
</response>

Retrieves transaction history of a customer which includes the following information. Transaction type, gross transaction amount, transaction date, points issued, points redeemed, coupons redeemed and so on.

By default, it shows up to 10 results and shows results based on the limit passed.

You can filter results using various parameters to analyze the data that you want to see and hide that you don’t want to see. For more details on supported filters, see the Request Parameters table below.

Resource Information

URI /transactions
Authentication Yes
HTTP Method GET
Batch Support Yes

Request URL

https://{host}/v1.1/customer/transactions?{identifier_name}={identifier_value}&{input_params}&format={xml/json}

For MLP

https://{host}/v1.1/customer/transactions?{identifierName}={identifierValue}&mlp=true&{input_params}&format={xml/json}

Request Query Parameters

Parameter Datatype Description
identifierName* enum Pass any of the customer identifier with the identifier value. Value: mobile, email, external_id id.
To retrieve transactions of multiple customers at a time, provide each identifier separating by a comma.
Example: mobile=44700900000,44700900999,4470090345.
identifierValue* string Provide the respective identifier value. For example, ?email=tom.sawyer@example.com.
entity_type enum Attribute by which you want to filter the transactions. Value: ZONE, CONCEPT, STORE, TILL, STR_SERVER (store server). For oAuth2, you need to pass this in headers. See the Introduction > Authentication section for more details.
entity_code string Code of the specified entity_type. For example, to get transactions of a specific zone (with zone code zone01), pass entity_type=zone&entity_code=zone01.
number string Fetch transaction details by transaction number.
transaction_id int Fetch details of a transaction by transaction ID (internally generated unique ID for a transaction).
store_id string Filter transactions associated to a specific store id.
store_code string Filter transactions associated to a specific store code.
start_id int Filters transactions with transaction IDs are greater than or equal to a specific value.
end_id int Filter transactions with transaction IDs less than or equal to a specific value.
start_date date-time Retrieves transactions made on or after a specific date (YYYY-MM-DD). To get transactions of a particular duration, use both start_date and end_date.
end_date date-time Retrieves transactions made on or before a specific date (YYYY-MM-DD). To get transactions of a particular duration, use both start_date and end_date.
Example: start_date=2013-12-21+23:45:45&end_date=2013-12-29+12:11:45
credit_notes boolean Retrieves the credit notes of the transactions. Value: true,false. Pass the parameter to retrieve credit notes along with the transaction details.
Credit Notes is a receipt given by a cashier to a customer for returned goods which can be used for future purchases.
custom_fields boolean Pass true to retrieve transaction level custom field details.
points_breakup boolean Pass true to retrieve the breakup of points earned for each transaction.
limit int Limit the number of results to be displayed (default value is 10). For example, limit=20 shows up to 20 transactions of the customer.
offset int Number of records to be ignored from the top. Offset is the position of the entity in the database record. The value is assigned based on the sequence of creation. For example, offset=10 ignores the first 10 transactions of the customer.
sort enum Arranges transactions in ascending or descending order of transaction date if the value istrans_date, transaction id if the value is trans_id. By default, results are shown in descending order.
order enum Arranges the transactions based on the value set in sort in an ascending (asc) or descending order (desc). By default, results are shown in the descending order of transaction date/id.

Get Customer Redemptions

Sample Request

https://us.api.capillarytech.com/v1.1/customer/redemptions?mobile=44700900000

Sample Response

{
  "response": {
    "status": {
      "success": "true",
      "code": "200",
      "message": "SUCCESS"
    },
    "customer": {
      "mobile": "44700900000",
      "email": "tom.sawyer@example.com",
      "external_id": "1234",
      "firstname": "Tom",
      "lastname": "Sawyer",
      "rows": "3",
      "coupons_count": "3",
      "points_count": "15",
      "coupons_start_id": "2",
      "points_start_id": "121613",
      "redemptions": {
        "coupons": {
          "coupon": {
            "id": "3",
            "code": "832-pghhi6u1",
            "series_id": "832",
            "description": "Sample description",
            "discount_code": "abc",
            "discount_type": "PERC",
            "transaction_number": "TestBill-1234",
            "redeemed_time": "2013-04-18 14:00:27",
            "redeemed_at": "Test store  store.server"
          }
        },
        "points": {
          "point": [
            {
              "id": 1,
              "program_id": 469,
              "points_redeemed": 20,
              "transaction_number": "txnre6",
              "validation_code": "SI8380",
              "redeemed_time": "2020-03-31 00:00:00",
              "redeemed_at": "bukl.till",
              "notes": "redeemed 20 points",
              "redeemed_store": {
                "code": "international_business_park",
                "name": "International Business Park"
              },
              "redeemed_till": {
                "code": "bukl.till",
                "name": "bukl.till"
              },
              "reversals": [
                {
                  "reversal_id": 1434301,
                  "points_reversed": 20,
                  "reversal_time": 2020-03-13 18:02:34,
                  "reversed_on_till_id": 75040399,
                  "reversal_breakup_by_program": [
                    {
                      "program_id": 469,
                      "points_reversed": 20,
                      "program_name": ""
                    }
                  ]
                }
              ],
              "redemption_breakup_by_program": [
                {
                  "program_id": 469,
                  "points_redeemed": 20,
                  "program_name": ""
                }
              ]
            },
            {
              "id": 121656,
              "program_id": 1234,
              "points_redeemed": 30,
              "transaction_number": "bill-121",
              "validation_code": "JZJ29D",
              "redeemed_time": "2011-03-17 16:05:22",
              "redeemed_at": "Test store  store.server",
              "notes": "200 points against bill-83",
              "redeemed_store": {
                "code": "international_business_park",
                "name": "International Business Park"
              },
              "redeemed_till": {
                "code": "bukl.till",
                "name": "bukl.till"
              }
            }
          ]
        }
      }
    }
  }
}
<root>
   <response>
      <customer>
         <coupons_count>3</coupons_count>
         <coupons_start_id>2</coupons_start_id>
         <email>tom.sawyer@example.com</email>
         <external_id>1234</external_id>
         <firstname>Tom</firstname>
         <lastname>Sawyer</lastname>
         <mobile>44700900000</mobile>
         <points_count>15</points_count>
         <points_start_id>121613</points_start_id>
         <redemptions>
            <coupons>
               <coupon>
                  <code>832-pghhi6u1</code>
                  <description>Sample description</description>
                  <discount_code>abc</discount_code>
                  <discount_type>PERC</discount_type>
                  <id>3</id>
                  <redeemed_at>Test store  store.server</redeemed_at>
                  <redeemed_time>2013-04-18 14:00:27</redeemed_time>
                  <series_id>832</series_id>
                  <transaction_number>TestBill-1234</transaction_number>
               </coupon>
            </coupons>
            <points>
               <point>
                  <element>
                     <id>1</id>
                     <notes>redeemed 20 points</notes>
                     <points_redeemed>20</points_redeemed>
                     <program_id>469</program_id>
                     <redeemed_at>bukl.till</redeemed_at>
                     <redeemed_store>
                        <code>international_business_park</code>
                        <name>International Business Park</name>
                     </redeemed_store>
                     <redeemed_till>
                        <code>bukl.till</code>
                        <name>bukl.till</name>
                     </redeemed_till>
                     <redeemed_time>2020-03-31 00:00:00</redeemed_time>
                     <redemption_breakup_by_program>
                        <element>
                           <points_redeemed>20</points_redeemed>
                           <program_id>469</program_id>
                           <program_name />
                        </element>
                     </redemption_breakup_by_program>
                     <reversals>
                        <element>
                           <points_reversed>20</points_reversed>
                           <reversal_breakup_by_program>
                              <element>
                                 <points_reversed>20</points_reversed>
                                 <program_id>469</program_id>
                                 <program_name />
                              </element>
                           </reversal_breakup_by_program>
                           <reversal_id>1434301</reversal_id>
                           <reversal_time>2020-03-13 18:02:34</reversal_time>
                           <reversed_on_till_id>75040399</reversed_on_till_id>
                        </element>
                     </reversals>
                     <transaction_number>txnre6</transaction_number>
                     <validation_code>SI8380</validation_code>
                  </element>
                  <element>
                     <id>121656</id>
                     <notes>200 points against bill-83</notes>
                     <points_redeemed>30</points_redeemed>
                     <program_id>1234</program_id>
                     <redeemed_at>Test store  store.server</redeemed_at>
                     <redeemed_store>
                        <code>international_business_park</code>
                        <name>International Business Park</name>
                     </redeemed_store>
                     <redeemed_till>
                        <code>bukl.till</code>
                        <name>bukl.till</name>
                     </redeemed_till>
                     <redeemed_time>2011-03-17 16:05:22</redeemed_time>
                     <transaction_number>bill-121</transaction_number>
                     <validation_code>JZJ29D</validation_code>
                  </element>
               </point>
            </points>
         </redemptions>
         <rows>3</rows>
      </customer>
      <status>
         <code>200</code>
         <message>SUCCESS</message>
         <success>true</success>
      </status>
   </response>
</root>


This API allows you to retrieve points and coupons redemption history of a customer. You can filter the results by type, duration, coupon ids start with, and coupon ids end with. Besides filters you can also sort the results by ascending or descending order by redemption id/time and limit number of results to retrieve.

Resource Information

URI /redemptions
Authentication Yes
HTTP Method GET
Batch Support Yes

Request URL

https://{host}/v1.1/customer/redemptions?{identifier}={value}&{query_params}

Request Query Parameters

Parameter Datatype Description
Identifier* enum Provide the identifier you want to use to identify customer. Value: mobile, email, external_id, id.
To retrieve redemption details of multiple customers at a time, provide the identifier of each customer separating by a comma.
Example: mobile=44700900000,44700900999,4470090345
type enum Filter the results either by POINTS redemption, COUPONS redemption, BOTH (default).
start_date date Get redemptions done on or after a specific date (YYYY-MM-DD). To get redemptions made in a specific duration, pass the date range in start_date and end_date.
end_date date Get redemptions made before a specific date (YYYY-MM-DD). To get redemptions made in a specific duration, pass the date range in start_date and end_date.
coupons_limit int Limit the number of coupon redemptions to be displayed. Example:coupons_limit=10 to show only 10 coupon redemption details. Use only when the type parameter is not passed.
points_limit int Limit the number of points redemption results to be displayed. Example:points_limit=10 to show only 10 points redemption details. Use only when the type parameter is not passed.
limit int Limit the number of redemption details (points and/or coupons). Use only when the type parameter is not passed. Default value is 10.
coupons_start_id long Filter the results by coupon redemption id starting with a specific number. Use only when the type parameter is not passed.
coupons_end_id long Filter the results by coupon redemption id ending with a specific number. Use only when the type parameter is not passed.
points_start_id long Filter the results by points redemption id starting with a specific number. Use only when the type parameter is not passed.
points_end_id long Filter the results by points redemption id ending with a specific number. Use only when the type parameter is not passed.
sort enum Sort the results either by redemption id (redemption_id) or redemption time(redeemed_time). By default, the results are sorted in the descending order of redeemed time.
order enum Order the results in ascending (asc) or descending order (desc). By default, the results are shown in the descending order of redeemed time.
mlp=true - Retrieves the details of points redeemed from each loyalty program of the org (only for orgs with multi-brand loyalty).
format enum Pass the desired representation of response content - format=xml, or format=json.
user_id=true - Returns the customer ID in response. By default, customer id is not retrieved.
mlp=true - Returns return additional points related block, will have to get the exact JSON block for this.
external_reference_number string
programId int

Response Parameters

Parameter Datatype Description
coupons_count int Number of coupon redemptions retrieved.
points_count int Number of points redemptions received.
coupons obj Details of coupon redemptions.
points obj Details of points redemption.
code string Unique code of the coupon.
series_id long Coupon series ID associated to the coupon.
description string Description of the coupon.
discount_code string Coupon code used to avail discount.
discount_type enum Type of discount. PERC for discount in percentage, FLAT for flat amount discount.
id long Redemption ID of that points or coupon.
transaction_number string Transaction number associated to the points or coupon redemption.
redeemed_time date-time Date and time of points or coupon redemption.
redeemed_at string Store or TILL code associated to points or coupon redemption.
program_id long Unique ID of the loyalty program in which points is redeemed.
points_redeemed int Number of points redeemed.
transaction_number string Transaction number associated to the points or coupon redemption.
redeemed_time date-time Date and time of points or coupon redemption.
redeemed_at string Store or TILL code associated to points or coupon redemption.
redemption_breakup_by_program obj Breakup of points redeemed with respect to the program.
reversals obj Details of points reversed if the transaction for which points are redeemed is returned.
reversal_id long Unique ID generated for the reversal of a specific set of redeemed points.
points_reversed int number of points reversed.
reversal_time date-time Date and time of points reversal in YYYY-MM-DD HH:MM:SS format.
reversed_on_till_id long Till ID associated to the points reversal.
reversal_breakup_by_program obj Breakup of points reversed and associated loyalty program.

Add Customer Notes

Sample Request

https://us.api.capillarytech.com/v1.1/customer/notes?format=json

Sample POST Request

{
  "root":{
    "customer":[
      {
        "user_id":"15",
        "mobile":"44700900999",
        "email":"catherine@example.com",
        "external_id":"ct123",
        "notes":{
          "note":[
            {
              "date":"2016-05-05 15:15:00",
              "description":"Likes Maggi"
            }
          ]
        }
      }
    ]
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <customer>
        <user_id>15</user_id>
        <mobile>44700900999</mobile>
        <email>catherine@example.com</email>
        <external_id>ct123</external_id>
        <notes>
            <note>

                <date>2016-05-05 15:15:00</date>
                <description>Likes Maggi</description>
            </note>
        </notes>
    </customer>
</root>                     

Sample Response

{
  "response": {
    "status": {
      "success": "true",
      "code": "200",
      "message": "Operation Successful"
    },
    "customer": {
      "user_id": "15098",
      "firstname": "Catherine",
      "lastname": "Thomas",
      "mobile": "44700900999",
      "email": "catherine@example.com",
      "external_id": "ct123",
      "notes": {
        "note": {
          "id":"1",
          "date": "2012-05-05 15:15:00",
          "description": "Likes Maggi"
        }
      },
      "item_status": {
        "success": true,
        "code": 1000,
        "message": "Customer note added/updated successfully",
        "warnings": {
            "warning": []
            }
      }
    }
  }
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status>
        <success>true</success>
        <code>200</code>
        <message>Operation Successful</message>
    </status>
    <customer>
        <user_id>15098</user_id>
        <firstname>catherine</firstname>
        <lastname>Thomas</lastname>
        <mobile>44700900999</mobile>
        <email>catherine@example.com</email>
        <external_id>ct123</external_id>
        <notes>
            <note>
               <id>1</id>
                <date>2012-05-05 15:15:00</date>
                <description>Likes Maggi</description>
            </note>
        </notes>
        <item_status>
            <success>true</success>
            <code>1000</code>
            <message>Customer note added successfully</message>
            <warnings/>
        </item_status>
    </customer>
</response>

This API allows you to capture additional information about the customer.

Resource Information

URI /notes
Authentication Yes
HTTP Method POST
Batch Support No

Request URL

https://{host}/v1.1/customer/notes?format=xml/json

Request Body Parameters

Parameter Datatype Description
Customer identifier* string Pass any of the unique identifiers of the customer for whom you want to add notes (mobile no/email id/external id/user_id)
date date Date that you associate to the notes. By default, current date will be considered.
description* string Details or message of the note in a plain text format.

Update Customer Notes

https://us.api.capillarytech.com/v1.1/customer/notes?format=json

Sample POST Request

{
  "root": {
    "customer": {
      "mobile": "44700900999",
      "email": "catherine@example.com",
      "associate_id": "50010823",
      "notes": {
        "note": [
          {
            "id": "8378",
            "description": "Likes jeans"
          },
          {
            "id": "8379",
            "description": "Likes new arrivals"
          }
        ]
      }
    }

<?xml version="1.0" encoding="UTF-8"?>
<root>
   <customer>
       <mobile>44700900999</mobile>
       <email>catherine@example.com</email>
       <associate_id>50010823</associate_id>
       <notes>
           <note>
               <id>8378</id>
               <description>Likes Jeans</description>
           </note>
           <note>
               <id>8379</id>
               <description>Likes new arrivals</description>
           </note>
       </notes>
   </customer>
</root>                     

Sample Response

{
  "response": {
    "status": {
      "success": "true",
      "code": "200",
      "message": "Success",
      "total": "1",
      "success_count": "1"
    },
    "customer": {
      "user_id": "29361138",
      "firstname": "Catherine",
      "lastname": "Thomas",
      "mobile": "44700900999",
      "email": "catherine@example.com",
      "external_id": "ext12",
      "notes": {
        "note": [
          {
            "id": "8378",
            "date": "2017-11-05 15:15:00",
            "description": "Likes jeans"
          },
          {
            "id": "8379",
            "date": "2017-10-05 15:15:00",
            "description": "Likes new arrivals"
          }
        ]
      },
      "item_status": {
        "success": "true",
        "code": "1000",
        "message": "Customer note updated successfully"
      }
    }
  }
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
   <status>
       <success>true</success>
       <code>200</code>
       <message>Success</message>
       <total>1</total>
       <success_count>1</success_count>
   </status>
   <customer>
       <user_id>29361138</user_id>
       <firstname>Catherine</firstname>
       <lastname>Thomas</lastname>
       <mobile>44700900999</mobile>
       <email>catherine@example.com</email>
       <external_id>ext12</external_id>
       <notes>
           <note>
               <id>8378</id>
               <description>Likes jeans</description>
           </note>
           <note>
               <id>8379</id>
               <description>Likes new arrivals</description>
           </note>
       </notes>
       <item_status>
           <success>true</success>
           <code>1000</code>
           <message>Customer note updated successfully</message>
           <warnings/>
       </item_status>
   </customer>
</response>

This API lets you update existing customer notes.

Resource Information

URI /notes
Authentication Yes
HTTP Method POST
Batch Support No

Request URL

https://{host}/v1.1/customer/notes?format={xml/json}

Request Body Parameters

Parameter Datatype Description
mobile/email/external_id/user_id** enum Unique identifier of the customer for which you want to update customer notes (mobile no/email id/external id/user_id).
description* string New notes that you want to update with (plain text).
id* int Unique id of the customer note that you want to update.

Get Customer Notes

Sample Request

https://us.api.capillarytech.com/v1.1/customer/notes?mobile=44700900999
{
  "response": {
    "status": {
      "success": "true",
      "code": "200",
      "message": "Operation Successful"
    },
    "customer": {
      "user_id": "15098",
      "firstname": "Catherine",
      "lastname": "Thomas",
      "mobile": "44700900999",
      "email": "catherine@example.com",
      "external_id": "ct123",
      "notes": {
        "note": [
          {
            "id":"1",
            "description": "Like to play cricket",
            "added_on": "2016-09-04 15:12:00"
          },
          {
            "id": "2",
            "description": "Subscribed for birthday wishes",
            "added_on": "2016-09-04 15:12:00"
          },
          {
            "id": "3",
            "description": "nothing more",
            "added_on": "2016-09-04 15:12:00"
          }
        ]
      },
      "item_status": {
        "success": "true",
        "code": "1000",
        "message": "Customer note retrieved successfully"
      }
    }
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status>
        <success>true</success>
        <code>200</code>
        <message>Operation Successful</message>
    </status>
    <customer>
        <user_id>15098</user_id>
        <!-- 
user_id tag will be returned only if query param user_id = true 
-->
        <firstname>Catherine</firstname>
        <lastname>Thomas</lastname>
        <mobile>44700900999</mobile>
        <email>catherine@example.com</email>
        <external_id>ct123</external_id>
        <notes>
            <note>
                <id>1</id>
                <description>Like to play cricket</description>
                <added_on>2016-09-04 15:12:00</added_on>
            </note>
            <note>
                <id>2</id>
                <description>Subscribed for birthday wishes</description>
                <added_on>2016-09-04 15:12:00</added_on>
            </note>
            <note>
                <id>3</id>
                <description>nothing more</description>
                <added_on>2016-09-04 15:12:00</added_on>
            </note>
        </notes>
        <item_status>
            <success>true</success>
            <code>1000</code>
            <message>Customer note retrieved successfully</message>
            <warnings/>
        </item_status>
    </customer>
</response>

Retrieves notes of a specific customer.

Resource Information

URI /notes
Authentication Yes
HTTP Method GET
Batch Support No

Request URL

https://{host}/v1.1/customer/notes?{identifier}={value}

Request Query Parameters

Parameter Datatype Description
identifier* enum Identifier you want to use to identify the customer. Value: mobile, email, external_id, id.
value* string Value of the specified identifier. For example, if identifier is mobile, value should be the customer’s mobile number.

Get Customer Coupons

Sample Request

https://us.api.capillarytech.com/v1.1/customer/coupons?format=json&mobile=44700900990

{
   "response":{
      "pagination":{
         "limit":"100",
         "offset":"0",
         "total":1
      },
      "status":{
         "success":"true",
         "code":"200",
         "message":"SUCCESS"
      },
      "customers":{
         "customer":{
            "firstname":"John",
            "lastname":"Doe",
            "email":"johndoe@example.com",
            "mobile":"44700900999",
            "external_id":"EXT001",
            "id":"1034",
            "coupons":{
               "coupon":{
                  "id":"2423525",
                  "redemption_count":"1",
                  "created_date":"2013-12-13T16:14:54+05:30",
                  "valid_till":"2016-12-21",
                  "code":"VOCU24902",
                  "transaction_number":"BILL-10304",
                  "redemptions":{
                     "redemption":{
                        "date":"2016-12-12 12:12:12",
                        "transaction_number":"BIL2042040",
                        "redeemed_at":{
                           "code":"storecode",
                           "name":"My store"
                        }
                     }
                  }
               }
            },
            "item_status":{
               "success":"true",
               "code":"1000",
               "message":"Issued coupons retrieved successfully"
            }
         }
      }
   }
}


<?xml version="1.0" encoding="UTF-8"?>
<root>
   <response>
      <customers>
         <customer>
            <coupons>
               <coupon>
                  <code>VOCU24902</code>
                  <created_date>2013-12-13T16:14:54+05:30</created_date>
                  <id>2423525</id>
                  <redemption_count>1</redemption_count>
                  <redemptions>
                     <redemption>
                        <date>2016-12-12 12:12:12</date>
                        <redeemed_at>
                           <code>storecode</code>
                           <name>My store</name>
                        </redeemed_at>
                        <transaction_number>BIL2042040</transaction_number>
                     </redemption>
                  </redemptions>
                  <transaction_number>BILL-10304</transaction_number>
                  <valid_till>2016-12-21</valid_till>
               </coupon>
            </coupons>
            <email>johndoe@example.com</email>
            <external_id>EXT001</external_id>
            <firstname>John</firstname>
            <id>1034</id>
            <item_status>
               <code>1000</code>
               <message>Issued coupons retrieved successfully</message>
               <success>true</success>
            </item_status>
            <lastname>Doe</lastname>
            <mobile>44700900999</mobile>
         </customer>
      </customers>
      <pagination>
         <limit>100</limit>
         <offset>0</offset>
         <total>1</total>
      </pagination>
      <status>
         <code>200</code>
         <message>SUCCESS</message>
         <success>true</success>
      </status>
   </response>
</root>



Retrieves the details of coupons (issued, redeemed, expired) of a specific customer.

Resource Information

URI /coupons
Authentication Yes
HTTP Method GET
Batch Support No

Request URL

https://{host}/v1.1/customer/coupons?{identifier}={value}&{input_params}

Request Query Parameters

Parameter Datatype Description
identifier* enum Identifier you want to use to identify the customer. Value: mobile, email, external_id, id.
value* string Value of the specified identifier. For example, if identifier is mobile, value should be the customer’s mobile number.
start_date date Get coupons issued or redeemed on or after a specific date (YYYY-MM-DD). To get coupon history of a specific duration, pass the date range in start_date and end_date.
end_date date Get coupons issued or redeemed before a specific date (YYYY-MM-DD). To get coupon history of a specific duration, pass the date range in start_date and end_date.
status enum Retrieve coupons by coupon status.
Values: unredeemed, redeemed, expired, active (based on coupon validity). active is based on the coupon expiry date and does not validate redemptions. Hence you will see all coupons whose expiry (valid_till) is a future date.
series_id int Retrieve details of a specific coupon series by series id.
store_id int Retrieves the details of active coupons of the customer that can be redeemed at a specific store
order_by enum Order the results by a specific entry. Value: created_date,amount,valid_till` (issued till).
sort_order enum Sort the results in ascending (asc) or descending (desc) order.
limit int Limit the number of results to be retrieved. For example: limit=10 to retrieve the history of ten recent coupons of the customer.

Create Ticket

Sample Request

https://us.api.capillarytech.com/v1.1/customer/tickets?format=json

Sample POST Request

{
  "root":{
    "customer":[
      {
        "email":"johndoe@example.com",
        "mobile":"44700900999",
        "external_id":"EXT001",
        "id":"1034",
        "ticket":[{
          "status":"OPEN",
          "priority":"HIGH",
          "department":"INTERNAL",
          "subject":"points issue",
          "message":"Unable to redeem points",
          "custom_fields":{
            "field":[
              {
                "name":"field1",
                "value":"value1"
              }
            ]
          }
        }
        ]
      }
    ]
  }
}

<root>
    <customer>
        <email>johndoe@example.com</email>
        <mobile>44700900999</mobile>
        <external_id>EXT001</external_id>
        <id>1034</id>
        <ticket>
            <status>OPEN</status>
            <priority>HIGH</priority>
            <department>INTERNAL</department>
            <subject>points issue</subject>
            <message>Unable to redeem points</message>
            <custom_fields>
                <field>
                    <name>field1</name>
                    <value>value1</value>
                </field>
            </custom_fields>
        </ticket>
    </customer>
</root>


Sample Response

{
  "response": {
    "status": {
      "success": "true",
      "code": "200",
      "message": "SUCCESS"
    },
    "customers": {
      "customer": {
        "email": "johndoe@example.com",
        "mobile": "44700900999",
        "external_id": "EXT001",
        "id": "1034",
        "ticket": {
          "code": "35t40ld04",
          "status": "OPEN",
          "priority": "HIGH",
          "department": "INTERNAL",
          "subject": "points issue",
          "message": "Unable to redeem points",
          "custom_fields": {
            "field": {
              "name": "field1",
              "value": "value1"
            }
          }
        },
        "item_status": {
          "success": "true",
          "code": "1300",
          "message": "Ticket added successfully"
        }
      }
    }
  }
}


<?xml version="1.0" encoding="UTF-8"?>
<response>
   <status>
      <success>true</success>
      <code>200</code>
      <message>SUCCESS</message>
   </status>
   <customers>
      <customer>
         <email>johndoe@example.com</email>
         <mobile>44700900999</mobile>
         <external_id>EXT001</external_id>
         <id>1034</id>
         <ticket>
            <code>35t40ld04</code>
            <status>OPEN</status>
            <priority>HIGH</priority>
            <department>INTERNAL</department>
            <subject>points issue</subject>
            <message>Unable to redeem points</message>
            <custom_fields>
               <field>
                  <name>field1</name>
                  <value>value1</value>
               </field>
            </custom_fields>
         </ticket>
         <item_status>
            <success>true</success>
            <code>1300</code>
            <message>Ticket added successfully</message>
         </item_status>
      </customer>
   </customers>
</response>


Lets you to create a new ticket for a customer.

Resource Information

URI /tickets
Authentication Yes
HTTP Method POST
Batch Support No

Request URL

`https://{host}/v1.1/customer/tickets

Request Body Parameters

Parameter Datatype Description
Customer identifier* string Pass any one identifiers of the customer - mobile, email, external_id, or id (user_id).
status enum Status of the ticket. Accepts only values configured for the org. Sample values: Open, Close, InProgress.
priority enum Priority of the ticket. Value: low, medium, high.
department string Set the department for which the ticket needs to be assigned
ticket_code string Pass the ticket id.
reported_from enum Source from which the ticket is created. Values: EMAIL, INTOUCH, CALLCENTER, CLIENT, MICROSITE, SOCIAL.
type enum Type of the ticket. Value: STORE, Customer.

Get Ticket Details

# Sample Request
https://us.api.capillarytech.com/v1.1/customer/tickets

Sample Response

{
  "response": {
    "status": {
      "success": "true",
      "code": "200",
      "message": "SUCCESS"
    },
    "customer": {
      "firstname": "John",
      "lastname": "Doe",
      "email": "johndoe@example.com",
      "mobile": "44700900999",
      "external_id": "EXT001",
      "id": "1034",
      "tickets": {
        "ticket": {
          "code": "35t40ld04",
          "status": "OPEN",
          "priority": "HIGH",
          "department": "INTERNAL",
          "subject": "points issue",
          "message": "Product received is damaged",
          "custom_fields": {
            "field": {
              "name": "field1",
              "value": "value1"
            }
          }
        }
      },
      "item_status": {
        "success": "true",
        "code": "1300",
        "message": "Ticket retrieved successfully"
      }
    }
  }
}


<?xml version="1.0" encoding="UTF-8"?>
<response>
   <status>
      <success>true</success>
      <code>200</code>
      <message>SUCCESS</message>
   </status>
   <customer>
      <firstname>John</firstname>
      <lastname>Doe</lastname>
      <email>johndoe@example.com</email>
      <mobile>44700900999</mobile>
      <external_id>EXT001</external_id>
      <id>1034</id>
      <tickets>
         <ticket>
            <code>35t40ld04</code>
            <status>OPEN</status>
            <priority>HIGH</priority>
            <department>INTERNAL</department>
            <subject>points issue</subject>
            <message>Product received is damaged</message>
            <custom_fields>
               <field>
                  <name>field1</name>
                  <value>value1</value>
               </field>
            </custom_fields>
         </ticket>
      </tickets>
      <item_status>
         <success>true</success>
         <code>1300</code>
         <message>Ticket retrieved successfully</message>
      </item_status>
   </customer>
</response>

This API allows you to fetch the details of tickets of a specific customer.

Resource Information

URI /tickets
Authentication Yes
HTTP Method GET
Batch Support Yes

Request URL

https://{host}/v1.1/customer/tickets?{identifier}={value}&{input_params}&format={xml/json}

Request Query Parameters

Parameter Datatype Description
Customer identifier* enum Pass any of the customer identifiers to retrieve ticket details. Values: mobile, email, external_id, id.
value string Pass the respective identifier value.
status enum Filter tickets by status. Pass only from statuses that are defined for your org.
priority enum Filter results by ticket priority.
Value: low, medium, high. Pass only priorities that are defined for your org.
department string Retrieve tickets assigned to a specific department. Pass only predefined departments of your org.
ticket_code string Retrieve details of a specific ticket
reported_from enum Retrieve tickets of a specific source.
Values: EMAIL, INTOUCH, CALLCENTER, CLIENT, MICROSITE, SOCIAL.
type enum Retrieve tickets by type.
Value: STORE, Customer.
start_date Retrieve tickets created on or after in a specific date (YYYY-MM-DD). To get tickets created in a specific date range, pass the duration in start_date and end_date.
end_date date Retrieve tickets created after a specific date (YYYY-MM-DD) - between start_date to end_date. To get tickets created in a specific date range, pass the duration in start_date and end_date.

Refer Customer

Sample Request

https://us.api.capillarytech.com/v1.1/customer/referrals

Sample POST Request

<?xml version="1.0" encoding="UTF-8"?>
<root>
   <customer>
      <!-- Any one identifier is required -->
      <email />
      <mobile>9174116390xx</mobile>
      <id />
      <external_id />
      <referrals>
         <!-- If no campaign id passed, default campaign is considered -->
         <campaign_token>12511</campaign_token>
         <referral_type>
            <type>EMAIL</type>
            <referral>
               <id>1</id>
               <name>Dexter Morgan</name>
               <identifier>dexter.morgan@mpd.com</identifier>
               <invited_on>20160912T15:
19:21+05:30</invited_on>
            </referral>
            <referral>
               <id>2</id>
               <name>Debra Morgan</name>
               <identifier>debra.morgan@elwaydetectives.com</identifier>
               <invited_on>20130912T15:
19:21+05:30</invited_on>
            </referral>
            <referral>
               <id>3</id>
               <name>Eddard ‘Ned’ Stark</name>
               <identifier>eddard.stark@winterfell.com</identifier>
               <invited_on>2016-09-12 T15:19:21+05:30</invited_on>
            </referral>
         </referral_type>
      </referrals>
   </customer>
</root>

{
  "root":{
    "customer":[
      {
        "mobile":"9174116390xx",
        "referrals":{
          "campaign_token":"12511",
          "referral_type":{
            "type":"EMAIL",
            "referral":[
              {
                "id":"1",
                "name":"Dexter Morgan",
                "identifier":"dexter.morgan@mpd.com",
                "invited_on":"20160912T15:19:21+05:30"
              },
              {
                "id":"2",
                "name":"Debra Morgan",
                "identifier":"debra.morgan@elwaydetectives.com",
                "invited_on":"20160912T15:19:21+05:30"
              },
              {
                "id":"3",
                "name":"Eddard ‘Ned’ Stark",
                "identifier":"eddard.stark@winterfell.com",
                "invited_on":"2016-09-12 T15:19:21+05:30"
              }
            ]
          }
        }
      }
    ]
  }
}

Sample Response

{
   "response":{
      "status":{
         "success":"true",
         "code":"200",
         "message":"success"
      },
      "customers":{
         "customer":{
            "email":"tom.sawyer@example.com",
            "mobile":"9197407983xx",
            "external_id":"VIMAL004",
            "id":"4596849",
            "firstname":"Vimal",
            "lastname":"Sudhan",
            "referrals":{
               "referral_type":[
                  {
                     "type":"EMAIL",
                     "referral":[
                        {
                           "id":"1",
                           "name":"Dexter Morgan",
                           "identifier":"dexter.morgan@mpd.com",
                           "invited_on":"2016-09-12T15:19:21+05:30",
                           "status":{
                              "success":"true",
                              "code":"100",
                              "message":"Invitee added successfully"
                           }
                        },
                        {
                           "id":"2",
                           "name":"Debra Morgan",
                           "identifier":"debra.morgan@elwaydetectives.com",
                           "invited_on":"2013-09-12T15:19:21+05:30",
                           "status":{
                              "success":"true",
                              "code":"100",
                              "message":"Invitee added successfully"
                           }
                        }
                     ]
                  },
                  {
                     "type":"MOBILE",
                     "referral":[
                        {
                           "id":"4",
                           "name":"Arya Stark",
                           "identifier":"919911223xx",
                           "invited_on":"2016-09-12T15:19:21+05:30",
                           "status":{
                              "success":"true",
                              "code":"100",
                              "message":"Invitee added successfully"
                           }
                        },
                        {
                           "id":"10",
                           "name":"Walt Jr",
                           "identifier":"919876543211",
                           "invited_on":" 2016-09-12T15:19:21+05:30",
                           "status":{
                              "success":"true",
                              "code":"100",
                              "message":"Invitee added successfully"
                           }
                        }
                     ]
                  }
               ]
            },
            "item_status":{
               "success":"true",
               "code":"1000",
               "message":"Referrals are invited Successfully"
            }
         }
      }
   }
}


<?xml version="1.0" encoding="UTF-8"?>
<root>
   <response>
      <customers>
         <customer>
            <email>tom.sawyer@example.com</email>
            <external_id>VIMAL004</external_id>
            <firstname>Vimal</firstname>
            <id>4596849</id>
            <item_status>
               <code>1000</code>
               <message>Referrals are invited Successfully</message>
               <success>true</success>
            </item_status>
            <lastname>Sudhan</lastname>
            <mobile>9197407983xx</mobile>
            <referrals>
               <referral_type>
                  <element>
                     <referral>
                        <element>
                           <id>1</id>
                           <identifier>dexter.morgan@mpd.com</identifier>
                           <invited_on>2016-09-12T15:19:21+05:30</invited_on>
                           <name>Dexter Morgan</name>
                           <status>
                              <code>100</code>
                              <message>Invitee added successfully</message>
                              <success>true</success>
                           </status>
                        </element>
                        <element>
                           <id>2</id>
                           <identifier>debra.morgan@elwaydetectives.com</identifier>
                           <invited_on>2013-09-12T15:19:21+05:30</invited_on>
                           <name>Debra Morgan</name>
                           <status>
                              <code>100</code>
                              <message>Invitee added successfully</message>
                              <success>true</success>
                           </status>
                        </element>
                     </referral>
                     <type>EMAIL</type>
                  </element>
                  <element>
                     <referral>
                        <element>
                           <id>4</id>
                           <identifier>919911223xx</identifier>
                           <invited_on>2016-09-12T15:19:21+05:30</invited_on>
                           <name>Arya Stark</name>
                           <status>
                              <code>100</code>
                              <message>Invitee added successfully</message>
                              <success>true</success>
                           </status>
                        </element>
                        <element>
                           <id>10</id>
                           <identifier>919876543211</identifier>
                           <invited_on> 2016-09-12T15:19:21+05:30</invited_on>
                           <name>Walt Jr</name>
                           <status>
                              <code>100</code>
                              <message>Invitee added successfully</message>
                              <success>true</success>
                           </status>
                        </element>
                     </referral>
                     <type>MOBILE</type>
                  </element>
               </referral_type>
            </referrals>
         </customer>
      </customers>
      <status>
         <code>200</code>
         <message>success</message>
         <success>true</success>
      </status>
   </response>
</root>

This API allows you to send the referral code of a specific campaign to a customer (auto generated referral code).

Naming Conventions

It is important to understand the following terminologies that you may come across while using the customer/APIs.

Resource Information

URI /referrals
Authentication Yes
HTTP Method POST
Batch Support Yes

Request URL

https://{host}/v1.1/customer/referrals?{identifier}={value}&{query-params}

Request Body Parameters

Parameter Type Description
Customer identifier* enum Pass any of the customer identifiers who needs to refer. Value: mobile, email, external_id, id.
campaign_token* string Unique token of the referral campaign.
type* enum Mode of communication of the referral. Values: SMS, EMAIL
id int Sequence id of the referee.
name string Name of the referee.
identifier string Identifier of the referee according to the type set. For example, if type:"EMAIL", identifier will be the email ID.
invited_on date-time Date and time of the invite.

Get Customer Referral Details

Sample Request

https://us.api.capillarytech.com/v1.1/customer/referrals&mobile=9197407983xx

Sample Response

<?xml version="1.0" encoding="UTF-8"?>
<root>
   <response>
      <customer>
         <email null="true" />
         <external_id>971544979350</external_id>
         <firstname>Ishant</firstname>
         <incentives />
         <invitees>
            <referral_type>
               <element>
                  <invitee>
                     <element>
                        <identifier>971564265901</identifier>
                        <invited_on>2020-01-29 12:25:46.0</invited_on>
                        <name>Siddhant</name>
                        <till>
                           <code>jotun.uae.admin.2</code>
                           <name>jotun.uae.admin.2</name>
                        </till>
                     </element>
                     <element>
                        <identifier>971564265901</identifier>
                        <invited_on>2020-01-29 13:37:36.0</invited_on>
                        <name>Siva</name>
                        <till>
                           <code>jotun.uae.admin.2</code>
                           <name>jotun.uae.admin.2</name>
                        </till>
                     </element>
                     <element>
                        <identifier>97150000099</identifier>
                        <invited_on>2020-01-29 13:55:32.0</invited_on>
                        <name>Harry</name>
                        <till>
                           <code>jotun.uae.admin.2</code>
                           <name>jotun.uae.admin.2</name>
                        </till>
                     </element>
                     <element>
                        <identifier>97150000099</identifier>
                        <invited_on>2020-01-30 14:56:12.0</invited_on>
                        <name>Jim</name>
                        <till>
                           <code>jotun.uae.admin.2</code>
                           <name>jotun.uae.admin.2</name>
                        </till>
                     </element>
                  </invitee>
                  <type>MOBILE</type>
               </element>
            </referral_type>
         </invitees>
         <item_status>
            <code>1000</code>
            <message>Referral statistics retrieved successfully</message>
            <success>true</success>
         </item_status>
         <lastname>Jindal</lastname>
         <mobile>971544979350</mobile>
         <referees>
            <referee>
               <element>
                  <added_on>2020-01-29 13:24:15</added_on>
                  <email null="true" />
                  <event_type>REGISTRATION</event_type>
                  <external_id null="true" />
                  <firstname null="true" />
                  <lastname null="true" />
                  <mobile null="true" />
               </element>
               <element>
                  <added_on>2020-01-29 13:31:53</added_on>
                  <email null="true" />
                  <event_type>REGISTRATION</event_type>
                  <external_id null="true" />
                  <firstname null="true" />
                  <lastname null="true" />
                  <mobile null="true" />
               </element>
               <element>
                  <added_on>2020-01-29 14:33:05</added_on>
                  <email null="true" />
                  <event_type>REGISTRATION</event_type>
                  <external_id null="true" />
                  <firstname null="true" />
                  <lastname null="true" />
                  <mobile null="true" />
               </element>
               <element>
                  <added_on>2020-01-29 15:32:37</added_on>
                  <email null="true" />
                  <event_type>REGISTRATION</event_type>
                  <external_id null="true" />
                  <firstname null="true" />
                  <lastname null="true" />
                  <mobile null="true" />
               </element>
            </referee>
         </referees>
         <referral_code>1mba0dlo5</referral_code>
      </customer>
      <status>
         <code>200</code>
         <message>SUCCESS</message>
         <success>true</success>
      </status>
   </response>
</root>
{
   "response":{
      "status":{
         "success":"true",
         "code":200,
         "message":"SUCCESS"
      },
      "customer":{
         "email":null,
         "mobile":"971544979350",
         "external_id":"971544979350",
         "firstname":"Ishant",
         "lastname":"Jindal",
         "referral_code":"1mba0dlo5",
         "invitees":{
            "referral_type":[
               {
                  "type":"MOBILE",
                  "invitee":[
                     {
                        "identifier":"971564265901",
                        "name":"Siddhant",
                        "invited_on":"2020-01-29 12:25:46.0",
                        "till":{
                           "code":"jotun.uae.admin.2",
                           "name":"jotun.uae.admin.2"
                        }
                     },
                     {
                        "identifier":"971564265901",
                        "name":"Siva",
                        "invited_on":"2020-01-29 13:37:36.0",
                        "till":{
                           "code":"jotun.uae.admin.2",
                           "name":"jotun.uae.admin.2"
                        }
                     },
                     {
                        "identifier":"97150000099",
                        "name":"Harry",
                        "invited_on":"2020-01-29 13:55:32.0",
                        "till":{
                           "code":"jotun.uae.admin.2",
                           "name":"jotun.uae.admin.2"
                        }
                     },
                     {
                        "identifier":"97150000099",
                        "name":"Jim",
                        "invited_on":"2020-01-30 14:56:12.0",
                        "till":{
                           "code":"jotun.uae.admin.2",
                           "name":"jotun.uae.admin.2"
                        }
                     }
                  ]
               }
            ]
         },
         "referees":{
            "referee":[
               {
                  "event_type":"REGISTRATION",
                  "firstname":null,
                  "lastname":null,
                  "mobile":null,
                  "email":null,
                  "external_id":null,
                  "added_on":"2020-01-29 13:24:15"
               },
               {
                  "event_type":"REGISTRATION",
                  "firstname":null,
                  "lastname":null,
                  "mobile":null,
                  "email":null,
                  "external_id":null,
                  "added_on":"2020-01-29 13:31:53"
               },
               {
                  "event_type":"REGISTRATION",
                  "firstname":null,
                  "lastname":null,
                  "mobile":null,
                  "email":null,
                  "external_id":null,
                  "added_on":"2020-01-29 14:33:05"
               },
               {
                  "event_type":"REGISTRATION",
                  "firstname":null,
                  "lastname":null,
                  "mobile":null,
                  "email":null,
                  "external_id":null,
                  "added_on":"2020-01-29 15:32:37"
               }
            ]
         },
         "incentives":[

         ],
         "item_status":{
            "success":"true",
            "code":1000,
            "message":"Referral statistics retrieved successfully"
         }
      }
   }
}

Retrieves the stats of the referrals along with the unique referral code of a specific customer.

Resource Information

URI /referrals
Authentication Yes
HTTP Method GET
Batch Support Yes

Request URL

https://{host}/v1.1/customer/referrals?{identifier}={value}&{query-params}&format={xml/json}

Request Query Parameters

Parameter Datatype Description
Customer identifier* enum Pass any of the customer identifiers to fetch referral details. Value: mobile, email, external_id, id.
value* string Pass the respective identifier value.
campaign_token string Pass the specific token id of the referral campaign that you want to fetch. If no campaign id is passed, the details of the customer’s referral history of the default campaign will be retrieved
start_date date Get customer referrals on or after a specific duration (YYYY-MM-DD). To get referrals of a specific duration, pass the date range in start_date and end_date.
end_date date Get customer referrals after a specific date (YYYY-MM-DD). To get referrals of a specific duration, pass the date range in start_date and end_date.
store_code string Retrieve referral stats of the specific store. Default value will be the current store. Set all to track details from all the stores
only_referral_code boolean Set true to retrieve the referral code of the respective referral campaigns (of the specific customer).

Update Customer Preferences

Sample Request

https://us.api.capillarytech.com/v1.1/customer/preferences

Sample POST Request

<root>
    <customer>
        <!-- any of these will work, mobile/email/external_id/user_id -->
        <mobile>44700900000</mobile>
        <email>tom.sawyer@example.com</email>
        <external_id>ts1234</external_id>
        <user_id>sa234</user_id>
        <local_id />
        <store>
            <code>store.code</code>
            <id>2234235</id>
        </store>
        <custom_fields>
            <field>
                <name>Favorite Brand</name>
                <value>[“puma”]</value>
            </field>
            <field>
                <name>Favorite Color</name>
                <value>Blue</value>
            </field>
        </custom_fields>
    </customer>
</root>

{
  "root": {
    "customer": [{
      "mobile": "44700900000",
      "email": "tom.sawyer@example.com",
      "external_id": "ts1234",
      "user_id": "sa234",
      "store": {
        "code": "store.code",
        "id": "2234235"
      },
      "custom_fields": {
        "field": [
          {
            "name": "Favorite Brand",
            "value": "[“puma”]"
          },
          {
            "name": "Favorite Color",
            "value": "Blue"
          }
        ]
      }
    }
  ]
  }
}

Sample Response

<response>
    <status>
        <success>true</success>
        <code>200</code>
        <message>SUCCESS</message>
    </status>
    <customers>
        <customer>
            <user_id>sa234</user_id>
            <mobile>44700900000</mobile>
            <email>tom.sawyer@example.com</email>
            <external_id>ts1234</external_id>
            <local_id />
            <custom_fields>
                <field>
                    <name>Favorite Brand</name>
                    <value>Puma</value>
                </field>
                <field>
                    <name>Favorite Color</name>
                    <value>Green</value>
                </field>
            </custom_fields>
            <store>
                <id>12762390</id>
                <code>storecode</code>
                <name>store Name</name>
                <status>SUCCESS</status>
            </store>
            <item_status>
                <success>true</success>
                <code>200</code>
                <message>Preferences Updated Successfully</message>
            </item_status>
        </customer>
    </customers>
</response>

{
  "response": {
    "status": {
      "success": "true",
      "code": "200",
      "message": "SUCCESS"
    },
    "customers": {
      "customer": {
        "user_id": "sa234",
        "mobile": "44700900000",
        "email": "tom.sawyer@example.com",
        "external_id": "ts1234",
        "custom_fields": {
          "field": [
            {
              "name": "Favorite Brand",
              "value": "Puma"
            },
            {
              "name": "Favorite Color",
              "value": "Green"
            }
          ]
        },
        "store": {
          "id": "12762390",
          "code": "storecode",
          "name": "store Name",
          "status": "SUCCESS"
        },
        "item_status": {
          "success": "true",
          "code": "200",
          "message": "Preferences Updated Successfully"
        }
      }
    }
  }
}

Preferences are custom fields created under the preferences category which helps in capturing specific interests of a customer. Example: favorite color, favorite brand. This API allows you to set or update preferences of a customer.

Resource Information

URI /preferences
Authentication Yes
HTTP Method POST
Batch Support Yes

Request URL

https://{host}/v1.1/customer/preferences?format={xml/json}

Request Body Parameters

Parameter Datatype Description
mobile/email/external_id/user_id* string Pass any of the identifiers of the customer whose preferences you want to update.
store obj
code string
id int Unique store id
custom_fields obj Update customer level custom field details as name and value pairs.

Fetch Customer Preferences

Sample Request

https://us.api.capillarytech.com/v1.1/customer/preferences?format=json&mobile=44700900000

Sample Response

<?xml version="1.0" encoding="UTF-8"?>
<response>
   <status>
      <success>true</success>
      <code>200</code>
      <message>SUCCESS</message>
   </status>
   <customers>
      <customer>
         <user_id>5532354</user_id>
         <!-- user_id will return according to
the extra query parameter “user_id”=true/false -->
         <mobile>44700900000</mobile>
         <email>tom.sawyer@example.com</email>
         <external_id>ts1234</external_id>
         <custom_fields>
            <field>
               <name>Favorite Color</name>
               <value>Green</value>
            </field>
            <field>
               <name>Favorite Brand</name>
               <value>Puma</value>
            </field>
            <field>
               <name>Likes</name>
               <value>Shoes</value>
            </field>
            <field>
               <name>PREFERRED_STORE</name>
               <value>Store name</value>
            </field>
         </custom_fields>
         <item_status>
            <success>true</success>
            <code>200</code>
            <message>Preferences retrieved successfully</message>
         </item_status>
      </customer>
   </customers>
</response>


{
  "response": {
    "status": {
      "success": "true",
      "code": "200",
      "message": "SUCCESS"
    },
    "customers": {
      "customer": {
        "user_id": "5532354",
        "mobile": "44700900000",
        "email": "tom.sawyer@example.com",
        "external_id": "ts1234",
        "custom_fields": {
          "field": [
            {
              "name": "Favorite Color",
              "value": "Green"
            },
            {
              "name": "Favorite Brand",
              "value": "Puma"
            },
            {
              "name": "Likes",
              "value": "Shoes"
            },
            {
              "name": "PREFERRED_STORE",
              "value": "Store Name"
            }
          ]
        },
        "item_status": {
          "success": "true",
          "code": "200",
          "message": "
Preferences retrieved successfully
"
        }
      }
    }
  }
}

Retrieves preferences of a specific customer.

Resource Information

URI /preferences
Authentication Yes
HTTP Method GET
Batch Support Yes

Request URL

https://{host}/v1.1/customer/preferences?{customer_identifier}={value}&format={xml/json}

Request Query Parameters

Parameter Datatype Description
Customer Identifier* enum Pass any of the customer identifiers to get preferences. Value: mobile, email, external_id, id.
value* string Pass the respective identifier values.

Get Customer Interactions

Sample Request

https://us.api.capillarytech.com/v1.1/customer/interaction?format=xml&mobile=44700900000

Sample Response



<?xml version="1.0" encoding="UTF-8"?>
<response>
   <status>
      <success>true</success>
      <response_code>200</response_code>
      <message>Success</message>
   </status>
   <customer>
      <id>24243</id>
      <mobile>44700900000</mobile>
      <email>tom.sawyer@example.com</email>
      <external_id>ts1234</external_id>
      <interactions>
         <network>
            <name>facebook</name>
            <interaction>
               <type>checkin</type>
               <count>1</count>
               <locs>
                  <loc>
                     <lat>22.23</lat>
                     <long>23.33</long>
                     <time>2012-3-12 11:33:23</time>
                  </loc>
               </locs>
            </interaction>
         </network>
         <network>
            <name>twitter</name>
            <interaction>
               <type>tweet</type>
               <count>10</count>
            </interaction>
            <interaction>
               <type>retweet</type>
               <count>5</count>
            </interaction>
         </network>
         <network>
            <name>capillary</name>
            <interaction>
               <type>email</type>
               <count>1</count>
               <messages>
                  <message>
                     <id>554</id>
                     <sender>abc@xyz.com</sender>
                     <receiver>def@xyz.com</receiver>
                     <subject>Sample subject</subject>
                     <sent_time>45837-06-15 02:56:40</sent_time>
                     <delivered_time />
                     <status>SENT</status>
                  </message>
               </messages>
            </interaction>
            <interaction>
               <type>sms</type>
               <count>1</count>
               <messages>
                  <message>
                     <id>555</id>
                     <sender>918867702348</sender>
                     <receiver>918867702349</receiver>
                     <subject>Example subject</subject>
                     <sent_time>45837-06-15 02:56:40</sent_time>
                  </message>
               </messages>
            </interaction>
            <interaction>
               <type>survey</type>
               <latest_nps_score>9</latest_nps_score>
               <latest_survey_name>Customer Satisfaction Survey 5</latest_survey_name>
               <latest_survey_interaction_time>2013-12-16 12:14:37</latest_survey_interaction_time>
               <surveys>
                  <survey>
                     <name>Customer Satisfaction Survey</name>
                     <nps_score>9</nps_score>
                     <sent_by>Nayan Kumar</sent_by>
                     <response_url />
                     <sent_time>2013-11-20 12:56:55</sent_time>
                     <completion_time>2013-11-14 13:23:05</completion_time>
                  </survey>
                  <survey>
                     <name>Customer Satisfaction Survey</name>
                     <nps_score>10</nps_score>
                     <sent_by>Shilpa</sent_by>
                     <response_url />
                     <sent_time>2013-12-11 11:43:55</sent_time>
                     <completion_time>2013-12-11 11:43:55</completion_time>
                  </survey>
                  <survey>
                     <name>Customer Feedback</name>
                     <nps_score>9</nps_score>
                     <sent_by>Shilpa</sent_by>
                     <response_url>https://survey-devint.capillary.in?sc=O5JHLN95&amp;sfc=14&amp;t=R0C9I313&amp;u=true</response_url>
                     <sent_time>2013-12-11 12:17:13</sent_time>
                     <completion_time>2013-12-11 12:17:13</completion_time>
                  </survey>
                  <survey>
                     <name>Customer Review</name>
                     <nps_score>8</nps_score>
                     <sent_by>Shilpa</sent_by>
                     <response_url>https://survey-devint.capillary.in?sc=O5JHLN95&amp;sfc=1&amp;t=7Q81C41Z&amp;u=true</response_url>
                     <sent_time>2013-12-13 15:22:48</sent_time>
                     <completion_time>2013-12-13 15:22:48</completion_time>
                  </survey>
                  <survey>
                     <name>Customer Satisfaction Survey 5</name>
                     <nps_score>9</nps_score>
                     <sent_by>Shilpa</sent_by>
                     <response_url>https://survey-devint.capillary.in?sc=O5JHLN95&amp;sfc=93&amp;t=3LWIXC9Y&amp;u=true</response_url>
                     <sent_time>2013-12-16 12:14:37</sent_time>
                     <completion_time>2013-12-16 12:14:37</completion_time>
                  </survey>
               </surveys>
               <count>5</count>
            </interaction>
         </network>
      </interactions>
   </customer>
</response>


{
  "response": {
    "status": {
      "success": "true",
      "response_code": "200",
      "message": "Success"
    },
    "customer": {
      "id": "24243",
      "mobile": "44700900000",
      "email": "tom.sawyer@example.com",
      "external_id": "ts1234",
      "interactions": {
        "network": [
          {
            "name": "facebook",
            "interaction": {
              "type": "checkin",
              "count": "1",
              "locs": {
                "loc": {
                  "lat": "22.23",
                  "long": "23.33",
                  "time": "2012-3-12 11:33:23"
                }
              }
            }
          },
          {
            "name": "twitter",
            "interaction": [
              {
                "type": "tweet",
                "count": "10"
              },
              {
                "type": "retweet",
                "count": "5"
              }
            ]
          },
          {
            "name": "capillary",
            "interaction": [
              {
                "type": "email",
                "count": "1",
                "messages": {
                  "message": {
                    "id": "554",
                    "sender": "abc@xyz.com",
                    "receiver": "
def@xyz.com
",
                    "subject": "Sample subject",
                    "sent_time": "45837-06-15 02:56:40",
                    "status": "SENT"
                  }
                }
              },
              {
                "type": "sms",
                "count": "1",
                "messages": {
                  "message": {
                    "id": "555",
                    "sender": "918867702348",
                    "receiver": "
918867702349
",
                    "subject": "Example subject",
                    "sent_time": "45837-06-15 02:56:40"
                  }
                }
              },
              {
                "type": "survey",
                "latest_nps_score": "9",
                "latest_survey_name": "Customer Satisfaction Survey 5",
                "latest_survey_interaction_time": "2013-12-16 12:14:37",
                "surveys": {
                  "survey": [
                    {
                      "name": "Customer Satisfaction Survey",
                      "nps_score": "9",
                      "sent_by": "Nayan Kumar",
                      "sent_time": "2013-11-20 12:56:55",
                      "completion_time": "2013-11-14 13:23:05"
                    },
                    {
                      "name": "Customer Satisfaction Survey",
                      "nps_score": "10",
                      "sent_by": "Shilpa ",
                      "sent_time": "2013-12-11 11:43:55",
                      "completion_time": "2013-12-11 11:43:55"
                    },
                    {
                      "name": "Customer Feedback",
                      "nps_score": "9",
                      "sent_by": "Shilpa ",
                      "response_url": "https://survey-devint.capillary.in?sc=O5JHLN95&sfc=14&t=R0C9I313&u=true",
                      "sent_time": "2013-12-11 12:17:13",
                      "completion_time": "2013-12-11 12:17:13"
                    },
                    {
                      "name": "Customer Review",
                      "nps_score": "8",
                      "sent_by": "Shilpa ",
                      "response_url": "https://survey-devint.capillary.in?sc=O5JHLN95&sfc=1&t=7Q81C41Z&u=true",
                      "sent_time": "2013-12-13 15:22:48",
                      "completion_time": "2013-12-13 15:22:48"
                    },
                    {
                      "name": "Customer Satisfaction Survey 5",
                      "nps_score": "9",
                      "sent_by": "Shilpa ",
                      "response_url": "https://survey-devint.capillary.in?sc=O5JHLN95&sfc=93&t=3LWIXC9Y&u=true",
                      "sent_time": "2013-12-16 12:14:37",
                      "completion_time": "2013-12-16 12:14:37"
                    }
                  ]
                },
                "count": "5"
              }
            ]
          }
        ]
      }
    }
  }
}

Lets you to fetch store interactions with a specific customer. This includes SMSs, emails, sent to the customer; missed calls received from the customer’s registered mobile number; and surveys submitted by the customer.

Resource Information

URI /interaction
Authentication Yes
HTTP Method GET
Batch Support Yes

Request URL

https://{host}/v1.1/customer/interaction?{customer_identifier}={value}&{params}&format={xml/json}

Request Query Parameters

Parameter Datatype Description
Customer Identifier* enum Pass any of the identifiers of the customer to retrieve interactions. Value: mobile, email, external_id, id.
value* string Pass the respective identifier value.
network enum Filter results by communication network. Values: facebook, twitter, foursquare, capillary.
type enum Filter results by interaction type. Values: email (for transaction email), emailbulk (for bulk email), checkin (applicable only for foursquare/facebook), like, comment (for facebook); mention, retweet, tweet (only for Twitter network); feedback (only for Capillary).
start_date date Specify the duration for which you want to see the customer interactions in start_date and end_date.
end_date date Specify the duration for which you want to see the customer interactions in start_date and end_date.

Update Subscription Details

Sample Request


https://us.api.capillarytech.com/v1.1/customer/subscriptions?format=json

Sample POST Request


<root>
    <subscription>
        <email>tom.sawyer@example.com</email>
        <priority>bulk</priority>
        <scope>all</scope>
        <!-- Multiple scope as csv is supported -->
        <channel>email</channel>
        <is_subscribed>0</is_subscribed>
    </subscription>
    <subscription>
        <email>tom.sawyer@example.com</email>
        <priority>bulk</priority>
        <scope>all</scope>
        <channel>sms</channel>
        <is_subscribed>0</is_subscribed>
    </subscription>
</root>

{
  "root": {
    "subscription": [
      {
        "email": "tom.sawyer@example.com",
        "priority": "bulk",
        "scope": "all",
        "channel": "email",
        "is_subscribed": "0"
      },
      {
        "email": "tom.sawyer@example.com",
        "priority": "bulk",
        "scope": "all",
        "channel": "sms",
        "is_subscribed": "0"
      }
    ]
  }
}

Sample Response

<response>
    <status>
        <success>true</success>
        <code>200</code>
        <message>SUCCESS</message>
    </status>
    <subscriptions>
        <subscription>
            <user_id>608</user_id>
            <email>tom.sawyer@example.com</email>
            <!-- Will have the same identifier passed in the request -->
            <channel>EMAIL</channel>
            <priority>BULK</priority>
            <scope>ALL</scope>
            <is_subscribed>0</is_subscribed>
            <item_status>
                <success>true</success>
                <code>1000</code>
                <message>Subscription successfully updated</message>
            </item_status>
        </subscription>
        <subscription>
            <user_id>608</user_id>
            <email>tom.sawyer@example.com</email>
            <channel>SMS</channel>
            <priority>BULK</priority>
            <scope>ALL</scope>
            <is_subscribed>0</is_subscribed>
            <item_status>
                <success>true</success>
                <code>1000</code>
                <message>Subscription successfully updated</message>
            </item_status>
        </subscription>
    </subscriptions>
</response>

{
  "response": {
    "status": {
      "success": "true",
      "code": "200",
      "message": "SUCCESS"
    },
    "subscriptions": {
      "subscription": [
        {
          "user_id": "608",
          "email": "tom.sawyer@example.com",
          "channel": "EMAIL",
          "priority": "BULK",
          "scope": "ALL",
          "is_subscribed": "0",
          "item_status": {
            "success": "true",
            "code": "1000",
            "message": "Subscription successfully updated"
          }
        },
        {
          "user_id": "608",
          "email": "tom.sawyer@example.com",
          "channel": "SMS",
          "priority": "TRANS",
          "scope": "ALL",
          "is_subscribed": "0",
          "item_status": {
            "success": "true",
            "code": "1000",
            "message": "Subscription successfully updated"
          }
        }
      ]
    }
  }
}

This API allows you to update sms/email subscription statuses of a customer.

Resource Information

URI /subscriptions
Authentication Yes
HTTP Method POST
Batch Support Yes

Request URL

https://{host}/1.1/customer/subscriptions?format={xml/json}

Request Body Parameters

Parameter Datatype Description
mobile/email/external_id/id* string Provide any of the customer identifiers to update subscription details.
priority* enum Specify the service that you want to update. Value: TRANS for personalized messages, and BULK for campaign or promotional messages.
scope enum Set scope to ‘all’ always.
channel* enum Pass the communication channel that you want to update. Value: sms, email.
is_subscribed* enum Specify 0 to unsubscribe, 1 to subscribe.

Get Product Recommendations

Retrieves product recommendations of a specific customer.

Sample Request

https://eu.api.capillarytech.com/v1.1/customer/recommendations?mobile=447700900000

Sample Response




Resource Information

URI /recommendations?{query_params}
Authentication Yes
HTTP Method Get
Batch Support Yes

Request URL

https://{host}/v1.1/customer/recommendations?identifier={identifierValue}&user_id={true}&limit={value}&product_limit={value}&format={xml/json}

Request Query Parameters

Parameter Datatype Description
mobile/email/external_id/id* string Pass any of the identifiers of the customer to fetch recommendations.
user_id boolean Pass true to retrieve unique customer ID in response. Default value is false.
limit int Limit the number of results to retrieve. For example, limit=4 fetches only four recommendations. Default value is 10.
product_limit int

Get Subscription Details

Sample Request

https://nightly.capillary.in/v1.1/customer/subscriptions?mobile=447700900000,919999000012

Sample Response



<?xml version="1.0" encoding="UTF-8"?>
<root>
   <response>
      <status>
         <code>200</code>
         <message>Success</message>
         <success>true</success>
      </status>
      <subscriptions>
         <subscription>
            <element>
               <channel>
                  <element>
                     <name>SMS</name>
                     <priority>
                        <element>
                           <name>TRANS</name>
                           <subscribed>ALL</subscribed>
                           <unsubscribed />
                           <user_preference>SUBSCRIBED</user_preference>
                        </element>
                        <element>
                           <name>BULK</name>
                           <subscribed />
                           <unsubscribed>ALL</unsubscribed>
                           <user_preference>UNSUBSCRIBED</user_preference>
                        </element>
                     </priority>
                  </element>
                  <element>
                     <name>POSTMAIL</name>
                     <priority>
                        <element>
                           <name>TRANS</name>
                           <subscribed>ALL</subscribed>
                           <unsubscribed />
                           <user_preference>NOT_SET</user_preference>
                        </element>
                        <element>
                           <name>BULK</name>
                           <subscribed>ALL</subscribed>
                           <unsubscribed />
                           <user_preference>NOT_SET</user_preference>
                        </element>
                     </priority>
                  </element>
                  <element>
                     <name>EMAIL</name>
                     <priority>
                        <element>
                           <name>TRANS</name>
                           <subscribed>ALL</subscribed>
                           <unsubscribed />
                           <user_preference>SUBSCRIBED</user_preference>
                        </element>
                        <element>
                           <name>BULK</name>
                           <subscribed />
                           <unsubscribed>ALL</unsubscribed>
                           <user_preference>UNSUBSCRIBED</user_preference>
                        </element>
                     </priority>
                  </element>
               </channel>
               <email>tom.sawyer@example.com</email>
               <external_id>XYPZ001</external_id>
               <item_status>
                  <code>1000</code>
                  <message>Subscription successfully retrieved</message>
                  <success>true</success>
               </item_status>
               <mobile>447700900000</mobile>
               <orgUnitSubscriptions />
               <user_id>29372667</user_id>
            </element>
            <element>
               <channel>
                  <element>
                     <name>SMS</name>
                     <priority>
                        <element>
                           <name>TRANS</name>
                           <subscribed>ALL</subscribed>
                           <unsubscribed />
                           <user_preference>NOT_SET</user_preference>
                        </element>
                        <element>
                           <name>BULK</name>
                           <subscribed>ALL</subscribed>
                           <unsubscribed />
                           <user_preference>NOT_SET</user_preference>
                        </element>
                     </priority>
                  </element>
                  <element>
                     <name>POSTMAIL</name>
                     <priority>
                        <element>
                           <name>TRANS</name>
                           <subscribed>ALL</subscribed>
                           <unsubscribed />
                           <user_preference>NOT_SET</user_preference>
                        </element>
                        <element>
                           <name>BULK</name>
                           <subscribed>ALL</subscribed>
                           <unsubscribed />
                           <user_preference>NOT_SET</user_preference>
                        </element>
                     </priority>
                  </element>
                  <element>
                     <name>EMAIL</name>
                     <priority>
                        <element>
                           <name>TRANS</name>
                           <subscribed>ALL</subscribed>
                           <unsubscribed />
                           <user_preference>NOT_SET</user_preference>
                        </element>
                        <element>
                           <name>BULK</name>
                           <subscribed>ALL</subscribed>
                           <unsubscribed />
                           <user_preference>NOT_SET</user_preference>
                        </element>
                     </priority>
                  </element>
               </channel>
               <item_status>
                  <code>1000</code>
                  <message>Subscription successfully retrieved</message>
                  <success>true</success>
               </item_status>
               <mobile>919999000012</mobile>
               <orgUnitSubscriptions />
               <user_id>343040815</user_id>
            </element>
         </subscription>
      </subscriptions>
   </response>
</root>



{
    "response": {
        "status": {
            "success": "true",
            "code": 200,
            "message": "Success"
        },
        "subscriptions": {
            "subscription": [
                {
                    "user_id": "29372667",
                    "mobile": "447700900000",
                    "email": "tom.sawyer@example.com",
                    "external_id": "XYPZ001",
                    "channel": [
                        {
                            "name": "SMS",
                            "priority": [
                                {
                                    "name": "TRANS",
                                    "subscribed": "ALL",
                                    "unsubscribed": "",
                                    "user_preference": "SUBSCRIBED"
                                },
                                {
                                    "name": "BULK",
                                    "subscribed": "",
                                    "unsubscribed": "ALL",
                                    "user_preference": "UNSUBSCRIBED"
                                }
                            ]
                        },
                        {
                            "name": "POSTMAIL",
                            "priority": [
                                {
                                    "name": "TRANS",
                                    "subscribed": "ALL",
                                    "unsubscribed": "",
                                    "user_preference": "NOT_SET"
                                },
                                {
                                    "name": "BULK",
                                    "subscribed": "ALL",
                                    "unsubscribed": "",
                                    "user_preference": "NOT_SET"
                                }
                            ]
                        },
                        {
                            "name": "EMAIL",
                            "priority": [
                                {
                                    "name": "TRANS",
                                    "subscribed": "ALL",
                                    "unsubscribed": "",
                                    "user_preference": "SUBSCRIBED"
                                },
                                {
                                    "name": "BULK",
                                    "subscribed": "",
                                    "unsubscribed": "ALL",
                                    "user_preference": "UNSUBSCRIBED"
                                }
                            ]
                        }
                    ],
                    "orgUnitSubscriptions": [],
                    "item_status": {
                        "code": "1000",
                        "message": "Subscription successfully retrieved",
                        "success": "true"
                    }
                },
                {
                    "user_id": "343040815",
                    "mobile": "919999000012",
                    "channel": [
                        {
                            "name": "SMS",
                            "priority": [
                                {
                                    "name": "TRANS",
                                    "subscribed": "ALL",
                                    "unsubscribed": "",
                                    "user_preference": "NOT_SET"
                                },
                                {
                                    "name": "BULK",
                                    "subscribed": "ALL",
                                    "unsubscribed": "",
                                    "user_preference": "NOT_SET"
                                }
                            ]
                        },
                        {
                            "name": "POSTMAIL",
                            "priority": [
                                {
                                    "name": "TRANS",
                                    "subscribed": "ALL",
                                    "unsubscribed": "",
                                    "user_preference": "NOT_SET"
                                },
                                {
                                    "name": "BULK",
                                    "subscribed": "ALL",
                                    "unsubscribed": "",
                                    "user_preference": "NOT_SET"
                                }
                            ]
                        },
                        {
                            "name": "EMAIL",
                            "priority": [
                                {
                                    "name": "TRANS",
                                    "subscribed": "ALL",
                                    "unsubscribed": "",
                                    "user_preference": "NOT_SET"
                                },
                                {
                                    "name": "BULK",
                                    "subscribed": "ALL",
                                    "unsubscribed": "",
                                    "user_preference": "NOT_SET"
                                }
                            ]
                        }
                    ],
                    "orgUnitSubscriptions": [],
                    "item_status": {
                        "code": "1000",
                        "message": "Subscription successfully retrieved",
                        "success": "true"
                    }
                }
            ]
        }
    }
}

Retrieves sms and email subscription details of a customer. You can filter the results by priority and communication channel. To retrieve subscription details of multiple customers, pass each customer identifier separating by comma.

Resource Information

URI /subscriptions
Authentication Yes
HTTP Method GET
Batch Support Yes

Request URL

https://{host}/v1.1/customer/subscriptions?{customer_identifier}={value1,value2}format={xml/json}

Request Query Parameters

Parameter Datatype Description
Customer Identifier* enum Pass any of the customer identifiers to retrieve subscription details.
value* string Pass the respective identifier values of all customers that you want to retrieve subscription details separating each value with comma. For example, mobile=918036151000,919999000012
channel enum Filter the results by communication channel. Value: SMS, EMAIL, WECHAT, SOCIAL, REMINDER_TEXT, RE_ISSUAL_TEXT, CLIENT.
priority enum Filter the results by message type. Value: TRANS, BULK.
scope enum Pass scope=ALL. It retrieves the details of all subscription modules. For example, points, coupons, general etc.

Response Codes

Success Codes

Code Description
1000 Customer registered successfully.
Customer retrieved successfully.
Subscription updated successfully.
Subscription retrieved successfully
Customer updated successfully.
Coupons retrieved successfully.
Customer notes added/updated successfully
Customer notes retrieved successfully
Customer preferences retrieved successfully.
Customer preferences updated successfully.
1000 Referral statistics retrieved successfully
Referrals are invited successfully
1040 Customer id change request has submitted successfully
1061 Customer recommendations fetched successfully
1052 Transactions fetched successfully
1300 Ticket retrieved successfully
Ticket added successfully

Error Codes

Code Description
500 All requests failed due to errors.
400 Input is invalid. Please check request parameters or input xml/json; No identifier provided to get loyalty users.
618 Not allowed - customer is marked as fraud.
816 Customer not found for organization.
1001 Unable to register. Invalid mobile number
1002 Unable to register. Invalid email id
1003 Unable to register. Invalid external id
1004 Failed to populate store
1006 Unable to register. Mobile number is required
1007 Unable to register customer. No valid primary identifier mobile number, email ID, or external ID passed.
1008/ 1038 Unable to register with external id
1009 Unable to add registered customer to MLM
1010 Unable to update loyalty points of the customer
1011 Cannot find customer for provided identifier
1012 Cannot find customer with the provided mobile number/external ID/e-mail ID.
1013 Customer is not registered for the loyalty Program.
1014 Customer is registered already
1015 No identifier provided to get loyalty users
1016 Unable to register. Email provided already exists for some other user
1017 Provided Custom Field is invalid
1018 Unable to update custom field
1019 Mobile number or external id is required along with the email Id to register
1020 The customer is not registered for loyalty program
1021 Invalid validation code
1023 Unable to register customer to loyalty program
1024 Unable to update customer profile
1025 Mandatory fields are not matching for customer identity update
1026 Count of optional fields match is less than required
1027 Field name provided for verification is invalid
1028 No customer notes are available
1029 Unable to retrieve customer preferences
1030 Unable to update customer preferences
1031 No preferences set for this customer
1032 A customer already exists with the same mobile number
1033 A customer already exists with the same external id
1034 Unable to register. Registration date is not within the allowed past or future date limit.
1035 Unable to update few customer preferences
1036 One or more notes could not be added/updated for customer.
1037 Unable to add/update customer notes
1039 Unable to register. Email ID is required.
1041 Customer id change request failed
1042 Invalid mobile no/email id/external id
1043 Unable to register. Customer’s external id is required.
1044 You do not have sufficient permission to view the customer details
1045 No valid identifier (mobile/email) passed for non-loyalty customer.
1046 Conversion of loyalty customer to non-loyalty is not allowed
1047 Customer’s primary identifier not matching with other identifiers
1048 Customer’s email id is required to convert to loyalty customer
1049 Customer’s external id is required to convert to loyalty customer
1051 No transactions or recommendations found for the customer
1053 Preferred store specified is not found.
1060 Batch limit exceeded
1062 Invalid Test & Control Status
1086 Points processing failed
1087 Points processing failed
1088 Unable to issue points. Please report to capillary support
1089 Points processing failed
1090 Points processing failed
1091 Points processing failed
1092 Points processing failed
1093 Points processing failed
1094 Points processing failed
1095 Points processing failed
1096 Points processing failed
1097 Points processing failed
1098 Points processing failed
1099 Points processing failed
1101 Invalid channel type
1102 Invalid priority type
1103 Invalid scope
1104 Invalid identifier or no identifier passed
1105 Multiple scopes are not allowed
1106 Invalid subscription status passed
1107 Invalid campaign id passed
1108 Invalid outbox id passed
1109 Unable to add, update or fetch subscription details.
1150 Invalid store ID passed.
1110 Unable to update subscription details
1222 Internal error occurred with the referral system
1202 Invalid campaign token
1203 Invalid campaign configured
1204 The customer may not be eligible for the referral program.
1205 Unable to find the referrer in the specific campaign
1206 Failed to add referral. Referral type is not supported.
1222 Internal error occurred with the referral system
1301 A ticket already exists with the same subject
1302 Ticket registration failed
1303 Ticket subject should not be empty
10001 Failed to add customer.
10002 Failed to update customer details.
91001 Failed to get point details.
91002 Failed to get subscription details.
91003 Validation failed.
91004 Failed to get segmentation details.
91005 {x} is Primary Key, {y} cannot be updated.
91006 {x} update is not allowed.
91007 {x} is already occupied by some other user, ignoring it.
91009 Retrieved survivor account for the requested merge victim.
91010 Downgrade strategy is not configured.
91011 Customer is already in the lowest slab.
91012 Customer is already in the highest slab.
91013 Call to Points Engine for tier upgrade criteria has failed {x}.
91014 Call to Points Engine for tier renewal criteria has failed {x}.
91015 Failed to update extended fields; or field length too long -{x}.
91016 WECHAT profile is not available for the customer.
91017 WEB_ENGAGE profile is not available for the customer.
91018 Unable to load WeChat notifications.
91019 Unable to load Web Engage notifications.
91020 Invalid TILL passed for registration.
91021 Invalid attribution TILL passed.
91022 Failed to update subscription for {x} channel and priority {y}

Transaction

A transaction represents a purchase or return event. Based on the customers’ loyalty status, transactions are categorized into three types.

Transactions are again classified into the following types:

The transaction entity contains all the necessary APIs to manage transactions and retrieve transaction details. The transaction entity stores regular/return transactions, points/coupons redeemed against transactions, retro transactions (converting not interested transactions to loyalty), extended fields, and custom fields.

Prerequisites

Before using transaction APIs, understand the transaction configurations of your organization. You can see the transaction related settings on InTouch > Settings > Systems & Deployment > InTouch PoS Configuration > Billing.

Add Transaction

Sample Request

https://us.api.capillarytech.com/v1.1/transaction/add?format=json

Sample POST Request

{
    "root": {
        "transaction": [{
            "bill_client_id": "",
            "type": "regular",
            "number": "BILL99",
            "amount": "5000",
            "currency_code": "INR",
            "notes": "2 line items",
            "billing_time": "2018-04-01",
            "gross_amount": "1000",
            "referral_code": "txnrflSDX123",
            "delivery_status": "DELIVERED",
            "shipping_source_till_code": "",
            "outlier_status": "NORMAL",
            "credit_notes": "",
            "discount": "10",
            "customer": {
                "mobile": "919999000000",
                "email": "",
                "external_id": "",
                "card_details": {
                    "card_number": ""
                },
                "firstname": "Tom",
                "lastname": "Sawyer",
                "referral_code": "CUSTSDX123"
            },
            "redemptions": {
                "points_redemptions": {
                    "id": [
                        "987654"
                    ]
                }
            },
            "coupon_redemptions": [],
            "extended_fields": {
                "field": [{
                        "name": "CentralGST",
                        "value": "8.5"
                    },
                    {
                        "name": "cashier_id",
                        "value": "12345678"
                    }
                ]
            },
            "payment_details": {
                "payment": [{
                        "mode": "CASH",
                        "value": "100"
                    },
                    {
                        "mode": [
                            "CREDIT",
                            "CHECKAPI"
                        ],
                        "value": [
                            "4000",
                            "500"
                        ],
                        "attributes": {
                            "attribute": [{
                                    "name": "BankNameAPI",
                                    "value": "value_602656"
                                },
                                {
                                    "name": "branch_nameAPI",
                                    "value": "value_602656"
                                }
                            ]
                        },
                        "notes": "notes_602656"
                    }
                ]
            },
            "custom_fields": {
                "field": [{
                    "name": "Bank",
                    "value": "SBI"
                }]
            },
            "line_items": {
                "line_item": [{
                        "serial": "1",
                        "amount": "500",
                        "description": "soap",
                        "item_code": "skuattr9",
                        "base_item_code": "",
                        "discount_value": 234,
                        "extended_fields": {
                            "field": [{
                                    "name": "booking_type",
                                    "value": "Online"
                                },
                                {
                                    "name": "MetalRate",
                                    "value": "120.55"
                                }
                            ]
                        },
                        "variant": "",
                        "addon_items": {
                            "addon_item": [{
                                    "item_code": "Addon-033",
                                    "quantity": "1",
                                    "description": ""
                                },
                                {
                                    "item_code": "Addon-033",
                                    "quantity": "1",
                                    "description": ""
                                }
                            ]
                        },
                        "combo_items": {
                            "combo_item": [{
                                    "item_code": "combo-033",
                                    "quantity": "1",
                                    "description": ""
                                },
                                {
                                    "item_code": "combo-033",
                                    "quantity": "1",
                                    "description": ""
                                }
                            ]
                        },
                        "split_items": {
                            "split_item": [{
                                    "item_code": "Cheese dip",
                                    "quantity": "1",
                                    "description": "Cheese dip"
                                },
                                {
                                    "item_code": "Cheese dip",
                                    "quantity": "1",
                                    "description": "Cheese dip"
                                }
                            ]
                        },
                        "qty": "50",
                        "rate": "10",
                        "value": "500",
                        "attributes": {
                            "attribute": {
                                "name": "brand",
                                "value": "Levis"
                            }
                        }
                    },
                    {
                        "serial": "1",
                        "transaction_number": "Trans99",
                        "amount": "500",
                        "description": "soap",
                        "item_code": "skuattr9",
                        "variant": "variant-33",
                        "notes": "",
                        "addon_items": {
                            "addon_item": [{
                                    "item_code": "Addon-043",
                                    "quantity": "1",
                                    "rate": "10",
                                    "value": "500",
                                    "description": ""
                                },
                                {
                                    "item_code": "Addon-043",
                                    "quantity": "1",
                                    "rate": "10",
                                    "value": "500",
                                    "description": ""
                                }
                            ]
                        },
                        "combo_items": {
                            "combo_item": [{
                                    "item_code": "combo-033",
                                    "quantity": "1",
                                    "description": ""
                                },
                                {
                                    "item_code": "combo-033",
                                    "quantity": "1",
                                    "description": ""
                                }
                            ]
                        },
                        "split_items": {
                            "split_item": [{
                                    "item_code": "Cheese dip",
                                    "quantity": "1",
                                    "rate": "10",
                                    "value": "500",
                                    "description": "Cheese dip"
                                },
                                {
                                    "item_code": "Cheese dip",
                                    "quantity": "1",
                                    "rate": "10",
                                    "value": "500",
                                    "description": "Cheese dip"
                                }
                            ]
                        },
                        "qty": "50",
                        "rate": "10",
                        "value": "500",
                        "attributes": {
                            "attribute": {
                                "name": "brand",
                                "value": "Levis"
                            }
                        }
                    }
                ]
            },
            "associate_details": {
                "code": "hiraxdhara",
                "name": "Chin"
            }
        }]
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<root>
   <root>
      <transaction>
         <element>
            <amount>5000</amount>
            <associate_details>
               <code>hiraxdhara</code>
               <name>Chin</name>
            </associate_details>
            <bill_client_id />
            <billing_time>2018-04-01</billing_time>
            <coupon_redemptions />
            <credit_notes />
            <currency_code>INR</currency_code>
            <custom_fields>
               <field>
                  <element>
                     <name>Bank</name>
                     <value>SBI</value>
                  </element>
               </field>
            </custom_fields>
            <customer>
               <card_details>
                  <card_number />
               </card_details>
               <email />
               <external_id />
               <firstname>Tom</firstname>
               <lastname>Sawyer</lastname>
               <mobile>919999000000</mobile>
               <referral_code>CUSTSDX123</referral_code>
            </customer>
            <delivery_status>DELIVERED</delivery_status>
            <discount>10</discount>
            <extended_fields>
               <field>
                  <element>
                     <name>CentralGST</name>
                     <value>8.5</value>
                  </element>
                  <element>
                     <name>cashier_id</name>
                     <value>12345678</value>
                  </element>
               </field>
            </extended_fields>
            <gross_amount>1000</gross_amount>
            <line_items>
               <line_item>
                  <element>
                     <addon_items>
                        <addon_item>
                           <element>
                              <description />
                              <item_code>Addon-033</item_code>
                              <quantity>1</quantity>
                           </element>
                           <element>
                              <description />
                              <item_code>Addon-033</item_code>
                              <quantity>1</quantity>
                           </element>
                        </addon_item>
                     </addon_items>
                     <amount>500</amount>
                     <attributes>
                        <attribute>
                           <name>brand</name>
                           <value>Levis</value>
                        </attribute>
                     </attributes>
                     <base_item_code />
                     <combo_items>
                        <combo_item>
                           <element>
                              <description />
                              <item_code>combo-033</item_code>
                              <quantity>1</quantity>
                           </element>
                           <element>
                              <description />
                              <item_code>combo-033</item_code>
                              <quantity>1</quantity>
                           </element>
                        </combo_item>
                     </combo_items>
                     <description>soap</description>
                     <discount_value>234</discount_value>
                     <extended_fields>
                        <field>
                           <element>
                              <name>booking_type</name>
                              <value>Online</value>
                           </element>
                           <element>
                              <name>MetalRate</name>
                              <value>120.55</value>
                           </element>
                        </field>
                     </extended_fields>
                     <item_code>skuattr9</item_code>
                     <qty>50</qty>
                     <rate>10</rate>
                     <serial>1</serial>
                     <split_items>
                        <split_item>
                           <element>
                              <description>Cheese dip</description>
                              <item_code>Cheese dip</item_code>
                              <quantity>1</quantity>
                           </element>
                           <element>
                              <description>Cheese dip</description>
                              <item_code>Cheese dip</item_code>
                              <quantity>1</quantity>
                           </element>
                        </split_item>
                     </split_items>
                     <value>500</value>
                     <variant />
                  </element>
                  <element>
                     <addon_items>
                        <addon_item>
                           <element>
                              <description />
                              <item_code>Addon-043</item_code>
                              <quantity>1</quantity>
                              <rate>10</rate>
                              <value>500</value>
                           </element>
                           <element>
                              <description />
                              <item_code>Addon-043</item_code>
                              <quantity>1</quantity>
                              <rate>10</rate>
                              <value>500</value>
                           </element>
                        </addon_item>
                     </addon_items>
                     <amount>500</amount>
                     <attributes>
                        <attribute>
                           <name>brand</name>
                           <value>Levis</value>
                        </attribute>
                     </attributes>
                     <combo_items>
                        <combo_item>
                           <element>
                              <description />
                              <item_code>combo-033</item_code>
                              <quantity>1</quantity>
                           </element>
                           <element>
                              <description />
                              <item_code>combo-033</item_code>
                              <quantity>1</quantity>
                           </element>
                        </combo_item>
                     </combo_items>
                     <description>soap</description>
                     <item_code>skuattr9</item_code>
                     <notes />
                     <qty>50</qty>
                     <rate>10</rate>
                     <serial>1</serial>
                     <split_items>
                        <split_item>
                           <element>
                              <description>Cheese dip</description>
                              <item_code>Cheese dip</item_code>
                              <quantity>1</quantity>
                              <rate>10</rate>
                              <value>500</value>
                           </element>
                           <element>
                              <description>Cheese dip</description>
                              <item_code>Cheese dip</item_code>
                              <quantity>1</quantity>
                              <rate>10</rate>
                              <value>500</value>
                           </element>
                        </split_item>
                     </split_items>
                     <transaction_number>Trans99</transaction_number>
                     <value>500</value>
                     <variant>variant-33</variant>
                  </element>
               </line_item>
            </line_items>
            <notes>2 line items</notes>
            <number>BILL99</number>
            <outlier_status>NORMAL</outlier_status>
            <payment_details>
               <payment>
                  <element>
                     <mode>CASH</mode>
                     <value>100</value>
                  </element>
                  <element>
                     <attributes>
                        <attribute>
                           <element>
                              <name>BankNameAPI</name>
                              <value>value_602656</value>
                           </element>
                           <element>
                              <name>branch_nameAPI</name>
                              <value>value_602656</value>
                           </element>
                        </attribute>
                     </attributes>
                     <mode>
                        <element>CREDIT</element>
                        <element>CHECKAPI</element>
                     </mode>
                     <notes>notes_602656</notes>
                     <value>
                        <element>4000</element>
                        <element>500</element>
                     </value>
                  </element>
               </payment>
            </payment_details>
            <redemptions>
               <points_redemptions>
                  <id>
                     <element>987654</element>
                  </id>
               </points_redemptions>
            </redemptions>
            <referral_code>txnrflSDX123</referral_code>
            <shipping_source_till_code />
            <type>regular</type>
         </element>
      </transaction>
   </root>
</root>

Sample Response

{
  "response": {
    "status": {
      "success": "true",
      "code": 200,
      "message": "Success"
    },
    "transactions": {
      "transaction": [
        {
          "id": 37813251,
          "shipping_source_till_code": "",
          "number": "BILL99",
          "bill_client_id": "",
          "type": "REGULAR",
          "delivery_status": "DELIVERED",
          "parent_bill_number": "",
          "outlier_status": "NORMAL",
          "customer": {
            "user_id": "342963216",
            "mobile": "919999000001",
            "firstname": "Tom",
            "lastname": "Sawyer",
            "email": "",
            "external_id": "",
            "lifetime_points": "106",
            "loyalty_points": "106",
            "current_slab": "bronze",
            "tier_expiry_date": "2119-09-20 23:59:59",
            "points_summaries": {
              "points_summary": [
                {
                  "programId": "1016",
                  "redeemed": "0",
                  "expired": "0",
                  "returned": "0",
                  "adjusted": "0",
                  "lifetimePoints": "106",
                  "loyaltyPoints": "106",
                  "cumulativePurchases": "18000",
                  "currentSlab": "bronze",
                  "nextSlab": "silver",
                  "nextSlabSerialNumber": "2",
                  "nextSlabDescription": "silver",
                  "slabSNo": "1",
                  "slabExpiryDate": "2119-09-20 23:59:59",
                  "totalPoints": ""
                }
              ]
            },
            "lifetime_purchases": "18000",
            "type": "LOYALTY",
            "source": "instore"
          },
          "side_effects": {
            "effect": [
              {
                "id": 33291227,
                "coupon_type": "PE",
                "coupon_code": "IYVS2E6V",
                "valid_till": "2020-06-27 23:59:59",
                "description": "Mobile Push offer 1",
                "discount_code": "MobilePush",
                "type": "coupon"
              }
            ]
          },
          "source": "ECOMM",
          "item_status": {
            "success": "true",
            "code": 600,
            "message": "Transaction added successfully"
          }
        }
      ]
    }
  }
}
<?xml version="1.0" encoding="UTF-8" ?>
<response>
  <status>
    <success>true</success>
    <code>200</code>
    <message>Success</message>
  </status>
  <transactions>
    <transaction>
      <id>37813251</id>
      <shipping_source_till_code></shipping_source_till_code>
      <number>BILL99</number>
      <bill_client_id></bill_client_id>
      <type>REGULAR</type>
      <delivery_status>DELIVERED</delivery_status>
      <parent_bill_number></parent_bill_number>
      <outlier_status>NORMAL</outlier_status>
      <customer>
        <user_id>342963216</user_id>
        <mobile>919999000001</mobile>
        <firstname>Tom</firstname>
        <lastname>Sawyer</lastname>
        <email></email>
        <external_id></external_id>
        <lifetime_points>106</lifetime_points>
        <loyalty_points>106</loyalty_points>
        <current_slab>bronze</current_slab>
        <tier_expiry_date>2119-09-20 23:59:59</tier_expiry_date>
        <points_summaries>
          <points_summary>
            <programId>1016</programId>
            <redeemed>0</redeemed>
            <expired>0</expired>
            <returned>0</returned>
            <adjusted>0</adjusted>
            <lifetimePoints>106</lifetimePoints>
            <loyaltyPoints>106</loyaltyPoints>
            <cumulativePurchases>18000</cumulativePurchases>
            <currentSlab>bronze</currentSlab>
            <nextSlab>silver</nextSlab>
            <nextSlabSerialNumber>2</nextSlabSerialNumber>
            <nextSlabDescription>silver</nextSlabDescription>
            <slabSNo>1</slabSNo>
            <slabExpiryDate>2119-09-20 23:59:59</slabExpiryDate>
            <totalPoints></totalPoints>
          </points_summary>
        </points_summaries>
        <lifetime_purchases>18000</lifetime_purchases>
        <type>LOYALTY</type>
        <source>instore</source>
      </customer>
      <side_effects>
        <effect>
          <id>33291227</id>
          <coupon_type>PE</coupon_type>
          <coupon_code>IYVS2E6V</coupon_code>
          <valid_till>2020-06-27 23:59:59</valid_till>
          <description>Mobile Push offer 1</description>
          <discount_code>MobilePush</discount_code>
          <type>coupon</type>
        </effect>
      </side_effects>
      <source>ECOMM</source>
      <item_status>
        <success>true</success>
        <code>600</code>
        <message>Transaction added successfully</message>
      </item_status>
    </transaction>
  </transactions>
</response>

Lets you add transactions of loyalty, non-loyalty, or not-interested customers. You can add batch transactions by passing each transaction details in a separate transaction attribute.

Currently, there is no validation that bill amount should match with sum of line items as the data is accepted as it is from POS or integration

Following are the key functionalities of the transaction/add API.

Variant Product: A same product having different variations in terms of common properties such as size, and color.

Product Bundle: A group of items that are sold as a single pack. This can include Combo items (Example: pack of 2, combo offers), Split items (Example: a necklace having gold rate, store rate, making charge, wastage charge and so on) and add-on items (Example: Pizza with extra cheese, and personalized toppings)

You can update custom field details and extended field details for either regular or return transactions. To retrieve these details, use customer/get, customer/transaction APIs.

Resource Information

URI /add
Rate Limited? Yes (1000 per hour)
HTTP Methods POST
Batch Support Yes

Request URL

https://{host}/v1.1/transaction/add?format={xml/json}

Request Body Parameters

Parameter Datatype Description
bill_client_id string Unique id of the bill as per the client (org) end.
type* enum Type of transaction. regular for loyalty transaction, not_interested for non-loyalty or not-interested transactions.
number* string Unique transaction number. The uniqueness depends on the configuration CONF_LOYALTY_BILL_NUMBER_UNIQUE_IN_DAYS set on InTouch Settings > System & Deployment > InTouch POS Configuration > Billing.
amount* double Net transaction amount of the original bill.
currency_code string ISO currency code of the transaction. For example, INR for Indian Rupee, SGD for Singapore Dollar, EUR for Euro, IQD for Iraqi Dinar.
notes string Additional information about the transaction.
qty* int Quantity of the current line-item.
rate float Price of each line-item.
value float Gross transaction amount (transaction amount excluding discount).
amount* double Net transaction amount of the bill after discount.
billing_time* date-time Date and time of the transaction. By default, the current system date and time will be considered.
gross_amount double Transaction amount excluding discount.
discount double Discount availed for the transaction (discount amount).
outlier_status enum Pass the outlier status of the transaction at transaction level, and outlier status of the line-item at line-item level. Values: INTERNAL, NORMAL, INVALID, OUTLIER, FAILED, DELETED, RETRO, FRAUD, TEST, OTHER.
source enum Source from which the transaction is made. Values: INSTORE( for InStore), WECHAT (WeChat), MARTJACK(AnywhereCommerce), WEB_ENGAGE (Web-engage integration), ECOMMERCE (ECOMMERCE), JD (JD), TAOBAO (Taobao), TMALL (TMall), FACEBOOK (Facebook), WEBSITE (other website), OTHERS (any other source).
not_interested_reason string Reason why the customer is not interested to register. Applicable only for not-interested transactions.
pointsRedemptions array Unique points redemption id(s) that you want to apply for the transaction. For example, [727272, 237878]. `
couponRedemptions array Unique coupon redemption id(s) that you want to apply for the transaction. For example, [727298, 237856].
referral_code string Referral code for a new customer (if applicable) to register in the org’s loyalty program. You can also have transaction level referrl code.
customer obj Pass customer information. Applicable for non-loyalty and not-interested transactions.
mobile/email/external_id/card_number string Pass any of the registered identifiers of the customer. Required for regular transactions.
firstname string First name of the customer.
lastname string Last name of the customer.
extended_fields obj Valid transaction level extended field details in name and value pairs. You can also pass line-item level extended field details in line_item object.
payment_details obj Payment details for the transaction.
attributes obj Attributes of the current line-item in name and value pairs.
mode string Mode of payment. This has to be the mode configured for your org.
value float Amount paid through the current mode.
attributes obj Payment mode attributes in name and value pairs.
custom_fields obj Transaction level custom field details. Pass line-item level custom field details in line_item object.
line_items obj Details of transaction line-items.
serial long Serial number of the current line-item.
transaction_number string Transaction line-item number.
description string Description of the line-item.
item_code string Unique line-item code.
variant string Variant code of the item. Applicable for variant product.
addon_items obj Details of add-on items. For example, pizza with extra cheese, and personalized toppings.
combo_items obj Details of combo or bundle items. For example, buy 1 shirt get one free, shirt+pant, pack of 5 soaps.
split_items obj Details of split items. For example, a necklace having gold rate, store rate, making charge, and wastage charges.
item_code string Unique code of the add-on, split, or combo item. For example, combo-22, pizza01_addon.
quantity double Quantity of the current add-on, split, or combo item.
associate_details obj Details of store associate or cashier who did the transaction.
code string Unique code of the store associate.
name string Name of the store associate.

Response Parameters

Parameter Datatype Description
id long Unique transaction ID generated internally.
customer obj Details of the customer associated to the transaction. Not applicable for NOT_INTERESTED transactions.
lifetime_points int Total loyalty points earned by the customer to date.
lifetime_purchases int Total purchases amount (loyalty or non-loyalty transactions) of the customer across all stores of the org.
loyalty_points int Current active loyalty points (neither redeemed nor expired) of the customer.
type enum Type of transaction. Value: regular for loyalty transaction, not_interested for non-loyalty or not-interested transactions.
source enum Source from which the transaction is made. Values: INSTORE( for InStore), WECHAT (WeChat), MARTJACK(AnywhereCommerce), WEB_ENGAGE (Web-engage integration), ECOMMERCE (ECOMMERCE), JD (JD), TAOBAO (Taobao), TMALL (TMall), FACEBOOK (Facebook), WEBSITE (other website), OTHERS (any other source).
current_slab string Current loyalty tier of the customer.
tier_expiry_date date-time Expiry date of the current tier in YYYY-MM-DD HH:MM:SS format.
points_summaries obj Shows the details of the loyalty points.
programId long Unique ID of the loyalty program associated to the points summary.
redeemed int In total points earned from the program, the total number of points that are redeemed.
expired int In total points earned from the program, the total number of points that are expired.
returned int In total points earned from the program, the total number of points that are returned. Usually, for transaction returns.
adjusted int Points that are either credited to or debited from the customer account in adjustments. The value will be negative if debited points are more than credited, and positive if credited points are more than debited.
cumulativePurchases double Total purchases amount of the customer in the stores associated to the current loyalty program.
currentSlab string Current tier of the customer in the loyalty program.
nextSlab string Next loyalty tier of the customer.
nextSlabSerialNumber int Serial number of the next tier. Lowest tier will have 1, succeeding tier will have 2 and so on.
nextSlabDescription string Description of the next tier as saved in the loyalty program.
slabSNo int Serial number of the current tier of the customer. Lowest tier will have 1, succeeding tier will have 2 and so on.
slabExpiryDate date-time Expiry date of the current loyalty tier of the customer in YYYY-MM-DD HH:MM:SS.
registered_on date-time Date on which the customer is enrolled in the org’s loyalty.
updated_on date-time Recent date on which the customer details are updated.
type enum Loyalty type of the customer. LOYALTY if the customer is enrolled in the org’s loyalty program, NON_LOYALTY if customer has not enrolled in the loyalty program but registered mobile number or email id with the org.
custom_fields obj Transaction or line-item level custom field details - field name (name) and field value (value).
extended_fields obj Transaction or line-item level extended field details - extended field name (name) and extended field value (value).

Add Transaction with Local Currency

Sample Request

https://us.api.capillarytech.com/v1.1/transaction/add_with_local_currency

Sample POST Request


<root>
   <transaction>
      <comment />
      <customer>
         <mobile>91000000099</mobile>
         <email>john@example.com</email>
         <firstname>autofn_7353409276</firstname>
      </customer>
      <billing_time>2016-01-21</billing_time>
      <type>regular</type>
      <gross_amount>1000</gross_amount>
      <number>numbr735ccdcdb34</number>
      <bill_client_id>1121</bill_client_id>
      <discount>0</discount>
      <amount>2000</amount>
      <credit_note>
         <comment />
         <amount>1800</amount>
         <notes>Reason for credit</notes>
         <number>numbr9959104543</number>
      </credit_note>
      <notes>Regular Bill with Payment Details</notes>
   </transaction>
</root>
{
  "root": {
    "transaction": [{
      "customer": {
        "mobile": "91000000099",
        "email": "john@example.com",
        "firstname": "autofn_7353409276"
      },
      "billing_time": "2016-01-21",
      "type": "regular",
      "gross_amount": "1000",
      "number": "numbr735ccdcdb34",
      "bill_client_id": "1121",
      "discount": "0",
      "amount": "2000",
      "credit_note": {
        "amount": "1800",
        "notes": "Reason for credit",
        "number": "numbr9959104543"
      },
      "notes": "Regular Bill with Payment Details"
    }]
  }
}

Sample Response


<response>
    <status>
        <success>true</success>
        <code>200</code>
        <message>Success</message>
    </status>
    <transactions>
        <transaction>
            <id>34058904</id>
            <number>numbr735ccdcdb34</number>
            <bill_client_id>1121</bill_client_id>
            <type>REGULAR</type>
            <delivery_status>DELIVERED</delivery_status>
            <customer>
                <user_id>282100245</user_id>
                <mobile>91000000099</mobile>
                <firstname>Tom</firstname>
                <lastname/>
                <email>john@example.com</email>
                <external_id/>
                <lifetime_points>0</lifetime_points>
                <loyalty_points>0</loyalty_points>
                <current_slab/>
                <tier_expiry_date/>
                <lifetime_purchases>2000</lifetime_purchases>
                <type>LOYALTY</type>
                <source>instore</source>
            </customer>
            <side_effects>
                <effect/>
            </side_effects>
            <source>instore</source>
            <item_status>
                <code>600</code>
                <success>true</success>
                <message>Transaction added successfully</message>
            </item_status>
        </transaction>
    </transactions>
</response>
{
  "response": {
    "status": {
      "success": "true",
      "code": "200",
      "message": "Success"
    },
    "transactions": {
      "transaction": {
        "id": "34058904",
        "number": "numbr735ccdcdb34",
        "bill_client_id": "1121",
        "type": "REGULAR",
        "delivery_status": "DELIVERED",
        "customer": {
          "user_id": "282100245",
          "mobile": "91000000099",
          "firstname": "Tom",
          "email": "john@example.com",
          "lifetime_points": "0",
          "loyalty_points": "0",
          "lifetime_purchases": "2000",
          "type": "LOYALTY",
          "source": "instore"
        },
        "side_effects": {

        },
        "source": "instore",
        "item_status": {
          "code": "600",
          "success": "true",
          "message": "Transaction added successfully"
        }
      }
    }
  }
}

Lets you add transactions with a different currency using the currency conversion ratio. The following are the prerequisites or checklists for the API.

The issual of points/coupon or redemption is calculated automatically as per the destination currency.

Resource Information

URI /add_with_local_currency
HTTP Methods POST
API Version v1.1
Batch Support Yes

Request URL

https://{host}/v1.1/transaction/add_with_local_currency?format={xml/json}

Request Body Parameters

Parameter Datatype Description
type* enum Type of transaction. regular for loyalty transaction, not_interested for non-loyalty or not-interested transactions.
number* string Unique transaction number. The uniqueness depends on the configuration CONF_LOYALTY_BILL_NUMBER_UNIQUE_IN_DAYS set on InTouch Settings > System & Deployment > InTouch POS Configuration > Billing.
amount* double Net transaction amount.
notes string Additional information about the transaction.
qty double Quantity of the current line-item.
rate float Price of each line-item.
value float Gross transaction amount (transaction amount excluding discount).
amount double Net transaction amount - the actual transaction amount after discount.
billing_time* date-time Date and time of the transaction. By default, the current system date and time will be considered.
gross_amount double Transaction amount excluding discount.
discount double Discount availed for the transaction (discount amount).
outlier_status enum Pass the outlier status of the transaction at transaction level, and outlier status of the line-item at line-item level. Values: INTERNAL, NORMAL, INVALID, OUTLIER, FAILED, DELETED, RETRO, FRAUD, TEST, OTHER.
source enum Source from which the transaction is made. Values: INSTORE( for InStore), WECHAT (WeChat), MARTJACK(AnywhereCommerce), WEB_ENGAGE (Web-engage integration), ECOMMERCE(“ECOMMERCE”), JD (JD), TAOBAO (Taobao), TMALL (TMall), FACEBOOK (Facebook), WEBSITE (other website), OTHERS (any other source).
not_interested_reason string Reason why the customer is not interested to register. Applicable only for not-interested transactions.
customer obj Pass customer information. Applicable for non-loyalty and not-interested transactions.
mobile/email/external_id string Pass any of the registered identifiers of the customer. Required for regular transactions.
firstname string First name of the customer.
lastname string Last name of the customer.
extended_fields obj Valid transaction level extended field details in name and value pairs. You can also pass line-item level extended field details in line_item object.

Response Parameters

Parameter Datatype Description
id long Unique transaction ID generated internally.
customer obj Details of the customer associated to the transaction. Not applicable for NOT_INTERESTED transactions.
lifetime_points int Total loyalty points earned by the customer to date.
lifetime_purchases int Total purchases amount (loyalty or non-loyalty transactions) of the customer across all stores of the org.
loyalty_points int Current active loyalty points (neither redeemed nor expired) of the customer.
type enum Type of transaction. Value: regular for loyalty transaction, not_interested for non-loyalty or not-interested transactions.
source enum Source from which the transaction is made. Values: INSTORE( for InStore), WECHAT (WeChat), MARTJACK(AnywhereCommerce), WEB_ENGAGE (Web-engage integration), ECOMMERCE (ECOMMERCE), JD (JD), TAOBAO (Taobao), TMALL (TMall), FACEBOOK (Facebook), WEBSITE (other website), OTHERS (any other source).
current_slab string Current loyalty tier of the customer.
tier_expiry_date date-time Expiry date of the current tier in YYYY-MM-DD HH:MM:SS format.
points_summaries obj Shows the details of the loyalty points.
programId long Unique ID of the loyalty program associated to the points summary.
redeemed int In total points earned from the program, the total number of points that are redeemed.
expired int In total points earned from the program, the total number of points that are expired.
returned int In total points earned from the program, the total number of points that are returned. Usually, for transaction returns.
adjusted int Points that are either credited to or debited from the customer account in adjustments. The value will be negative if debited points are more than credited, and positive if credited points are more than debited.
cumulativePurchases double Total purchases amount of the customer in the stores associated to the current loyalty program.
currentSlab string Current tier of the customer in the loyalty program.
nextSlab string Next loyalty tier of the customer.
nextSlabSerialNumber int Serial number of the next tier. Lowest tier will have 1, succeeding tier will have 2 and so on.
nextSlabDescription string Description of the next tier as saved in the loyalty program.
slabSNo int Serial number of the current tier of the customer. Lowest tier will have 1, succeeding tier will have 2 and so on.
slabExpiryDate date-time Expiry date of the current loyalty tier of the customer in YYYY-MM-DD HH:MM:SS.
registered_on date-time Date on which the customer is enrolled in the org’s loyalty.
updated_on date-time Recent date on which the customer details are updated.
type enum Loyalty type of the customer. LOYALTY if the customer is enrolled in the org’s loyalty program, NON_LOYALTY if customer has not enrolled in the loyalty program but registered mobile number or email id with the org.
custom_fields obj Transaction or line-item level custom field details - field name (name) and field value (value).
extended_fields obj Transaction or line-item level extended field details - extended field name (name) and extended field value (value).

Return Transaction

Sample Request

https://us.api.capillarytech.com/v1.1/transaction/add?format=json

Sample POST Request (Return)

{
  "root": {
    "transaction": {
      "type": "return",
      "country": "true",
      "number": "BILL98",
      "not_interested_reason": "Example reason",
      "return_type": "AMOUNT",
      "parent_bill_number": "RE123",
      "purchase_time": "2018-04-01",
      "amount": "500",
      "billing_time": "2018-05-31",
      "customer": {
        "mobile": "919999000000",
        "email": "",
        "external_id": "",
        "firstname": "Tom",
        "lastname": "Sawyer"
      },
      "line_items": {
        "line_item": {
          "serial": "1",
          "amount": "500",
          "description": "soap",
          "item_code": "item-001",
          "qty": "50",
          "rate": "10",
          "value": "500",
          "attributes": {
            "attribute": {
              "name": "brand",
              "value": "Levis"
            }
          }
        }
      },
      "custom_fields_data": {
        "custom_data_item": {
          "field_name": "paymentmode",
          "field_value": "CASH"
        }
      },
      "associate_details": {}
    }
  }
}
<?xml version="1.0" encoding="UTF-8" ?>
<root>
  <transaction>
    <type>return</type>
    <country>true</country>
    <number>BILL98</number>
    <not_interested_reason>Example reason</not_interested_reason>
    <return_type>AMOUNT</return_type>
    <parent_bill_number>RE123</parent_bill_number>
    <purchase_time>2018-04-01</purchase_time>
    <amount>500</amount>
    <billing_time>2018-05-31</billing_time>
    <customer>
      <mobile>919999000000</mobile>
      <email></email>
      <external_id></external_id>
      <firstname>Tom</firstname>
      <lastname>Sawyer</lastname>
    </customer>
    <line_items>
      <line_item>
        <serial>1</serial>
        <amount>500</amount>
        <description>soap</description>
        <item_code>item-001</item_code>
        <qty>50</qty>
        <rate>10</rate>
        <value>500</value>
        <attributes>
          <attribute>
            <name>brand</name>
            <value>Levis</value>
          </attribute>
        </attributes>
      </line_item>
    </line_items>
    <custom_fields_data>
      <custom_data_item>
        <field_name>paymentmode</field_name>
        <field_value>CASH</field_value>
      </custom_data_item>
    </custom_fields_data>
    <associate_details/>
  </transaction>
</root>

Sample POST Request (Mixed Transaction)

{
 "root":{
   "transaction":[
     {
       "type":"mixed",
       "number":"Exch-1112",
       "amount":"500",
       "notes":"1 line items",
       "billing_time":"2018-09-26 20:10:00",
       "gross_amount":"500",
       "discount":"0",
       "customer":{
         "mobile":"9540000000",
         "email":"",
         "external_id":"",
         "firstname":"",
         "lastname":""
       },
       "payment_details":{
         "payment": [{
                       "mode": "CASH",
                       "value": "200"
                   },
                   {
                       "mode": "Card",
                       "value": "200",
                       "attributes": {
                           "attribute": [{
                                   "name": "card_type",
                                   "value": "Debit Card"
                               },
                               {
                                   "name": "bankName",
                                   "value": "BCA"
                               },
                               {
                                   "name": "CardIssuerCode",
                                   "value": "value345"
                               }
                           ]
                       },
                       "notes": "notes_602656"
                   }
               ]

       },
       "custom_fields":{
         "field":[

         ]
       },
       "line_items":{
         "line_item":[

       {
        "type":"regular",                            
             "serial":"1",
             "amount":"300",
             "description":"Testdesc04",
             "item_code":"code04",
             "variant":"",
            "qty":"1",
             "rate":"300",
             "value":"300"
       },
       {
        "type":"return",
            "return_type":"LINE_ITEM",
            "transaction_number":"RC-15",
            "transaction_date":"2018-09-25 10:10:10",
             "serial":"1",
             "amount":"50",
             "description":"Testdesc02",
             "item_code":"code02",
             "variant":"",
            "qty":"1",
             "rate":"50",
             "value":"50"
       }

         ]

       }
     }
   ]
 }
}
<?xml version="1.0" encoding="UTF-8"?>
<root>
   <root>
      <transaction>
         <element>
            <amount>500</amount>
            <billing_time>2018-09-26 20:10:00</billing_time>
            <custom_fields>
               <field />
            </custom_fields>
            <customer>
               <email />
               <external_id />
               <firstname />
               <lastname />
               <mobile>9540000000</mobile>
            </customer>
            <discount>0</discount>
            <gross_amount>500</gross_amount>
            <line_items>
               <line_item>
                  <element>
                     <amount>300</amount>
                     <description>Testdesc04</description>
                     <item_code>code04</item_code>
                     <qty>1</qty>
                     <rate>300</rate>
                     <serial>1</serial>
                     <type>regular</type>
                     <value>300</value>
                     <variant />
                  </element>
                  <element>
                     <amount>50</amount>
                     <description>Testdesc02</description>
                     <item_code>code02</item_code>
                     <qty>1</qty>
                     <rate>50</rate>
                     <return_type>LINE_ITEM</return_type>
                     <serial>1</serial>
                     <transaction_date>2018-09-25 10:10:10</transaction_date>
                     <transaction_number>RC-15</transaction_number>
                     <type>return</type>
                     <value>50</value>
                     <variant />
                  </element>
               </line_item>
            </line_items>
            <notes>1 line items</notes>
            <number>Exch-1112</number>
            <payment_details>
               <payment>
                  <element>
                     <mode>CASH</mode>
                     <value>200</value>
                  </element>
                  <element>
                     <attributes>
                        <attribute>
                           <element>
                              <name>card_type</name>
                              <value>Debit Card</value>
                           </element>
                           <element>
                              <name>bankName</name>
                              <value>BCA</value>
                           </element>
                           <element>
                              <name>CardIssuerCode</name>
                              <value>value345</value>
                           </element>
                        </attribute>
                     </attributes>
                     <mode>Card</mode>
                     <notes>notes_602656</notes>
                     <value>200</value>
                  </element>
               </payment>
            </payment_details>
            <type>mixed</type>
         </element>
      </transaction>
   </root>
</root>

Sample Response

<?xml version="1.0" encoding="UTF-8" ?>
<response>
  <status>
    <success>true</success>
    <code>200</code>
    <message>Success</message>
  </status>
  <transactions>
    <transaction>
      <id>191565</id>
      <shipping_source_till_code></shipping_source_till_code>
      <number>BILL99</number>
      <bill_client_id></bill_client_id>
      <type>RETURN</type>
      <delivery_status>DELIVERED</delivery_status>
      <parent_bill_number>BILL99</parent_bill_number>
      <outlier_status>NORMAL</outlier_status>
      <customer>
        <user_id>342963216</user_id>
        <mobile>919999000001</mobile>
        <firstname>Tom</firstname>
        <lastname>Sawyer</lastname>
        <email></email>
        <external_id></external_id>
        <lifetime_points>106</lifetime_points>
        <loyalty_points>106</loyalty_points>
        <current_slab>bronze</current_slab>
        <tier_expiry_date>2119-09-20 23:59:59</tier_expiry_date>
        <points_summaries>
          <points_summary>
            <programId>1016</programId>
            <redeemed>0</redeemed>
            <expired>0</expired>
            <returned>0</returned>
            <adjusted>0</adjusted>
            <lifetimePoints>106</lifetimePoints>
            <loyaltyPoints>106</loyaltyPoints>
            <cumulativePurchases>17500</cumulativePurchases>
            <currentSlab>bronze</currentSlab>
            <nextSlab>silver</nextSlab>
            <nextSlabSerialNumber>2</nextSlabSerialNumber>
            <nextSlabDescription>silver</nextSlabDescription>
            <slabSNo>1</slabSNo>
            <slabExpiryDate>2119-09-20 23:59:59</slabExpiryDate>
            <totalPoints></totalPoints>
          </points_summary>
        </points_summaries>
        <lifetime_purchases>17500</lifetime_purchases>
        <type>LOYALTY</type>
        <source>instore</source>
      </customer>
      <side_effects>
        <effect/>
      </side_effects>
      <points_deducted>0</points_deducted>
      <points_balance>106</points_balance>
      <source></source>
      <item_status>
        <success>true</success>
        <code>600</code>
        <message>Transaction added successfully,Mobile update is not allowed</message>
      </item_status>
    </transaction>
  </transactions>
</response>
{
  "response": {
    "status": {
      "success": "true",
      "code": 200,
      "message": "Success"
    },
    "transactions": {
      "transaction": [
        {
          "id": 191565,
          "shipping_source_till_code": "",
          "number": "BILL99",
          "bill_client_id": "",
          "type": "RETURN",
          "delivery_status": "DELIVERED",
          "parent_bill_number": "BILL99",
          "outlier_status": "NORMAL",
          "customer": {
            "user_id": "342963216",
            "mobile": "919999000001",
            "firstname": "Tom",
            "lastname": "Sawyer",
            "email": "",
            "external_id": "",
            "lifetime_points": "106",
            "loyalty_points": "106",
            "current_slab": "bronze",
            "tier_expiry_date": "2119-09-20 23:59:59",
            "points_summaries": {
              "points_summary": [
                {
                  "programId": "1016",
                  "redeemed": "0",
                  "expired": "0",
                  "returned": "0",
                  "adjusted": "0",
                  "lifetimePoints": "106",
                  "loyaltyPoints": "106",
                  "cumulativePurchases": "17500",
                  "currentSlab": "bronze",
                  "nextSlab": "silver",
                  "nextSlabSerialNumber": "2",
                  "nextSlabDescription": "silver",
                  "slabSNo": "1",
                  "slabExpiryDate": "2119-09-20 23:59:59",
                  "totalPoints": ""
                }
              ]
            },
            "lifetime_purchases": "17500",
            "type": "LOYALTY",
            "source": "instore"
          },
          "side_effects": {
            "effect": []
          },
          "points_deducted": 0,
          "points_balance": 106,
          "source": "",
          "item_status": {
            "success": "true",
            "code": 600,
            "message": "Transaction added successfully"
          }
        }
      ]
    }
  }
}

Lets you submit a return transaction of any transaction type.

The following are different return types supported for a transaction.

Before using this API, you need to know the configurations set of the Return Transactions page of InTouch Settings > Systems & Deployment > InTouch POS Configuration.

Request URL

https://{host}/v1.1/transaction/add?format={xml/json}

Request Body Parameters

Parameter Datatype Description
type* enum Type of transaction. RETURN for loyalty transaction return, NOT_INTERESTED_RETURN for not-interested return, MIXED for exchange (involves both return and purchase).
You will also need to pass type for MIXED transaction both at bill level (MIXED) and line-item level (regular for new transaction item and return for return item).
return_type enum Type of return. Value: AMOUNT to return transaction or line-items for money, LINE_ITEM to return one or more line-items of the transaction, FULL to return complete transaction.
number* string Actual transaction number of the return bill.
parent_bill_number string Return transaction number.
billing_time* date-time Date and time of the return transaction in YYYY-MM-DD HH:MM:SS format.
purchase_time* date Actual transaction date of the returning bill inYYYY-MM-DD format.
notes string Additional information about the transaction.
amount* double Sum of regular line items of the current transaction after discount.
qty* int Quantity of the current line-item.
rate float Price of each line-item.
value float Gross transaction amount (transaction amount excluding discount).
amount* double Net return transaction amount.
source enum Source from which the transaction is made. Values: INSTORE( for InStore), WECHAT (WeChat), MARTJACK(AnywhereCommerce), WEB_ENGAGE (Web-engage integration), ECOMMERCE(“ECOMMERCE”), JD (JD), TAOBAO (Taobao), TMALL (TMall), FACEBOOK (Facebook), WEBSITE (other website), OTHERS (any other source).
customer obj Customer details associated to the transaction. Not applicable for not-interested transactions.
mobile/email/external_id string Pass any of the registered identifiers of the customer. Required for regular transaction returns.
firstname string First name of the customer.
lastname string Last name of the customer.
extended_fields obj Valid transaction level extended field details in name and value pairs. You can also pass line-item level extended field details in line_item object.
custom_fields obj Transaction level custom field details. Pass line-item level custom field details in line_item object.
line_items obj Details of transaction line-items.
serial long Serial number of the line-item.
description string Description of the line-item.
item_code string Unique line-item code.
variant string Variant code of the item. Applicable for variant product.
addon_items obj Details of add-on items. For example, pizza with extra cheese, and personalized toppings.
combo_items obj Details of combo or bundle items. For example, buy 1 shirt get one free, shirt+pant, pack of 5 soaps.
split_items obj Details of split items. For example, a necklace having gold rate, store rate, making charge, and wastage charges.
item_code string Unique code of the add-on, split, or combo item. For example, combo-22, pizza01_addon.
quantity double Quantity of the current add-on, split, or combo item.
associate_details obj Details of store associate or cashier who did the transaction.
code string Unique code of the store associate.
name string Name of the store associate.

Response Parameters

Parameter Datatype Description
id long Unique transaction ID generated internally for return.
customer obj Details of the customer associated to the transaction. Not applicable for NOT_INTERESTED transactions.
lifetime_points int Total loyalty points earned by the customer to date.
lifetime_purchases int Total purchases amount (loyalty or non-loyalty transactions) of the customer across all stores of the org.
loyalty_points int Current active loyalty points (neither redeemed nor expired) of the customer.
type enum Type of transaction. Value: return for loyalty transaction, not_interested_return for non-loyalty or not-interested transactions.
source enum Source from which the transaction is made. Values: INSTORE( for InStore), WECHAT (WeChat), MARTJACK(AnywhereCommerce), WEB_ENGAGE (Web-engage integration), ECOMMERCE (ECOMMERCE), JD (JD), TAOBAO (Taobao), TMALL (TMall), FACEBOOK (Facebook), WEBSITE (other website), OTHERS (any other source).
current_slab string Current loyalty tier of the customer.
tier_expiry_date date-time Expiry date of the current tier in YYYY-MM-DD HH:MM:SS format.
points_summaries obj Shows the details of the loyalty points.
programId long Unique ID of the loyalty program associated to the points summary.
redeemed int In total points earned from the program, the total number of points that are redeemed.
expired int In total points earned from the program, the total number of points that are expired.
returned int In total points earned from the program, the total number of points that are returned. Usually, for transaction returns.
adjusted int Points that are either credited to or debited from the customer account in adjustments. The value will be negative if debited points are more than credited, and positive if credited points are more than debited.
cumulativePurchases double Total purchases amount of the customer in the stores associated to the current loyalty program.
currentSlab string Current tier of the customer in the loyalty program.
nextSlab string Next loyalty tier of the customer.
nextSlabSerialNumber int Serial number of the next tier. Lowest tier will have 1, succeeding tier will have 2 and so on.
nextSlabDescription string Description of the next tier as saved in the loyalty program.
slabSNo int Serial number of the current tier of the customer. Lowest tier will have 1, succeeding tier will have 2 and so on.
slabExpiryDate date-time Expiry date of the current loyalty tier of the customer in YYYY-MM-DD HH:MM:SS.
registered_on date-time Date on which the customer is enrolled in the org’s loyalty.
updated_on date-time Recent date on which the customer details are updated.
type enum Loyalty type of the customer. LOYALTY if the customer is enrolled in the org’s loyalty program, NON_LOYALTY if customer has not enrolled in the loyalty program but registered mobile number or email id with the org.
custom_fields obj Transaction or line-item level custom field details - field name (name) and field value (value).
extended_fields obj Transaction or line-item level extended field details - extended field name (name) and extended field value (value).

Cancel a Transaction Line-Item

Sample Request

https://us.api.capillarytech.com/v1.1/transaction/add?format=json

Sample POST Request

{
   "transaction": {
      "comment": "cancel line_item",
      "customer": {
         "mobile": "919111111111",
         "lastname": "Sawyer",
         "external_id": "ts8674477501",
         "email": "tom.sawyer@example.com",
         "firstname": "Tom"
      },
      "line_items": {
         "line_item": {
            "description": "Ordered a different item",
            "rate": "50",
            "value": "50",
            "qty": "1",
            "amount": "50",
            "item_code": "number0-1",
            "cashier_id": [],
            "discount_value": "0",
            "return_type": "cancelled",
            "type": "return",
            "serial": "0"
         }
      },
      "notes": "one line item cancel",
      "billing_time": "2018-02-14",
      "number": "numbr8674477501",
      "return_type": "cancelled",
      "type": "return"
   }
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
   <transaction>
      <comment>cancel line_item</comment>
      <customer>
         <mobile>919111111111</mobile>
         <lastname>Sawyer</lastname>
         <external_id>ts8674477501</external_id>
         <email>tom.sawyer@example.com</email>
         <firstname>Tom</firstname>
      </customer>
      <line_items>
         <line_item>
            <description>Ordered a different item</description>
            <rate>50</rate>
            <value>50</value>
            <qty>1</qty>
            <amount>50</amount>
            <item_code>number0-1</item_code>
            <cashier_id />
            <discount_value>0</discount_value>
            <return_type>cancelled</return_type>
            <type>return</type>
            <serial>0</serial>
         </line_item>
      </line_items>
      <notes>one line item cancel</notes>
      <billing_time>2018-02-14</billing_time>
      <number>numbr8674477501</number>
      <return_type>cancelled</return_type>
      <type>return</type>
   </transaction>
</root>

Sample Response

<response>
    <status>
        <success>true</success>
        <code>200</code>
        <message>Success</message>
    </status>
    <transactions>
        <transaction>
            <id>176536</id>
            <number>numbr8674477502</number>
            <bill_client_id/>
            <type>RETURN</type>
            <delivery_status>DELIVERED</delivery_status>
            <outlier_status>NORMAL</outlier_status>
            <customer>
                <user_id>32411221</user_id>
                <mobile>919111111111</mobile>
                <firstname>Tom</firstname>
                <lastname>Sawyer</lastname>
                <email>tom.sawyer@example.com</email>
                <external_id>ext_id8674477501</external_id>
                <lifetime_points>0</lifetime_points>
                <loyalty_points>0</loyalty_points>
                <current_slab/>
                <tier_expiry_date/>
                <lifetime_purchases>0</lifetime_purchases>
                <type>LOYALTY</type>
                <source>instore</source>
            </customer>
            <side_effects>
                <effect/>
            </side_effects>
            <points_deducted>0</points_deducted>
            <points_balance>0</points_balance>
            <source/>
            <item_status>
                <code>600</code>
                <success>true</success>
                <message>Transaction added successfully</message>
            </item_status>
        </transaction>
    </transactions>
</response>
{
   "status": {
      "success": "true",
      "code": "200",
      "message": "Success"
   },
   "transactions": {
      "transaction": {
         "id": "176536",
         "number": "numbr8674477502",
         "bill_client_id": [],
         "type": "RETURN",
         "delivery_status": "DELIVERED",
         "outlier_status": "NORMAL",
         "customer": {
            "user_id": "32411221",
            "mobile": "919111111111",
            "firstname": "Tom",
            "lastname": "Sawyer",
            "email": "tom.sawyer@example.com",
            "external_id": "ts123",
            "lifetime_points": "0",
            "loyalty_points": "0",
            "current_slab": [],
            "tier_expiry_date": [],
            "lifetime_purchases": "0",
            "type": "LOYALTY",
            "source": "instore"
         },
         "side_effects": {
            "effect": []
         },
         "points_deducted": "0",
         "points_balance": "0",
         "source": [],
         "item_status": {
            "code": "600",
            "success": "true",
            "message": "Transaction added successfully"
         }
      }
   }
}

Lets you cancel a line-item of a transaction. For example, it can be used for e-commerce platforms where the brand allows a customer to cancel an item (of a transaction) before it is shipped/delivered.

Resource Information

URI /add
HTTP Methods POST
API Version v1.1
Batch Support Yes

Request URL

https://{host}/v1.1/transaction/add?format=json

Request Body Parameters

Parameter Datatype Description
Customer identifier enum Pass any of the identifiers of customers for loyalty or non-loyalty returns. Value: mobile, email, external_id, id.
purchase_time* date-time Date and time of the actual purchase of the return items.
number* string The actual transaction number of the returned item.
type* enum Specify type as RETURN for regular transaction returns, NOT_INTERESTED_RETURN for not-interested transaction returns.
return_type* enum Specify FULL to return the entire transaction, LINE_ITEM to return a particular line-item of the transaction, AMOUNT to return the transaction amount instead of replacement.

Update Transaction Details

Sample Request

https://api.capillary.co.in/v1.1/transaction/update?format=xml

Sample POST Request

{
  "root": {
    "transaction": [
      {
        "id": "123234",
        "number": "BILL-001",
        "type": "REGULAR",
        "notes": "",
        "customer": {
          "id": "34897",
          "mobile": "44700900999",
          "email": "earnshaw.catherine@example.com",
          "external_id": "ec1234"
        },
        "extended_fields": {
                "field": [{
                        "name": "CentralGST",
                        "value": "8.5"
                    },
                    {
                        "name": "cashier_id",
                        "value": "12345678"
                    }

                ]
            },
        "custom_fields": {
          "field": [
            {
              "name": "Earnshaw Catherine",
              "value": "value2"
            },
            {
              "name": "Favorite Color",
              "value": "Green"
            }
          ]
        }
      },
      {
        "id": "123234",
        "number": "BILL-001",
        "type": "REGULAR",
        "customer": {
          "id": "34897",
          "mobile": "44700900000",
          "email": "tom.sawyer@example.com",
          "external_id": "ts1234"
        }

      }
    ]
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <transaction>
        <id>123234</id>
        <!--
         identifies specific transaction without conflict (first priority to identify transaction

         -->
        <number>BILL-001</number>
        <!--
         may have conflict as one customer can have multiple transaction having same bill number, will be updated latest transaction in such cases (first transaction in desc order of billing time)

         -->
        <type>REGULAR</type>
        <!-- this can be REGULAR or NOT_INTERESTED -->
        <customer>
            <id>34897</id>
            <mobile>44700900999</mobile>
            <email>earnshaw.catherine@example.com</email>
            <external_id>ec1234</external_id>
        </customer>
        <extended_fields>
               <field>
                  <element>
                     <name>CentralGST</name>
                     <value>8.5</value>
                  </element>
                  <element>
                     <name>cashier_id</name>
                     <value>12345678</value>
                  </element>
               </field>
            </extended_fields>
        <custom_fields>
            <field>
                <name>Earnshaw Catherine</name>
                <value>value2</value>
            </field>
            <field>
                <name>field2</name>
                <value>value2</value>
            </field>
        </custom_fields>
    </transaction>
    <transaction>
        <id>123234</id>
        <number>BILL-001</number>
        <type>REGULAR</type>
        <!-- this can be REGULAR or NOT_INTERESTED -->
        <customer>
            <id>34897</id>
            <mobile>44700900000</mobile>
            <email>tom.sawyer@example.com</email>
            <external_id>ts1234</external_id>
        </customer>
        <custom_fields>
            <field>
                <name>Tom Sawyer</name>
                <value>value2</value>
            </field>
        </custom_fields>
    </transaction>
</root>

Lets you convert a not_interested transaction to a regular transaction ((Retro Transaction). You can also update both transaction and line-item level custom field and extended field details of a transaction.

Resource Information

URI /update
HTTP Methods POST
API Version v1.1
Batch Support Yes

Request URL

https://{host}/v1.1/transaction/update?format={xml/json}

Request Body Parameters

Parameter Datatype Description
id** int Unique id of the transaction that you want to update.
number** string Transaction number that you need to update.
mobile/external_id/email/id* string Pass any one of the identifiers of the customer associated to the transaction.
update_till string Till code associated to the transaction update.
notes string Reason for the transaction update for reference.
extended_fields obj Update extended field details of the transaction.
custom_fields obj Update custom field details of the transaction.

Response Parameters

Parameter Datatype Description
extended_fields obj Extended field details of the transaction that are updated.
custom_fields obj Custom field details of the transaction that are updated.
id long Unique ID of the transaction generated by the system.
number string Bill or transaction number.
type enum Current transaction type.
customer obj Customer details associated to the transaction.

Retro Transaction

Sample Request

https://api.capillary.co.in/v1.1/transaction/update?format=json

Sample POST Request

{
  "root": {
    "transaction": [{
      "customer": {
        "mobile": "44700900999",
        "external_id": "ext_id9931156917",
        "email": "catherine@example.com"
      },
      "new_type": "REGULAR",
      "notes": "Retro Transaction",
      "id": "6464658",
      "old_type": "NOT_INTERESTED"
    }]
  }
}
<root>
    <transaction>
        <customer>
            <mobile>44700900999</mobile>
            <external_id>ext_id9931156917</external_id>
            <email>catherine@example.com</email>
        </customer>
        <new_type>REGULAR</new_type>
        <notes>Retro Transaction</notes>
        <id>6464658</id>
        <old_type>NOT_INTERESTED</old_type>
    </transaction>
</root>

Sample Response

{
  "response": {
    "status": {
      "success": "true",
      "code": "200",
      "message": "SUCCESS"
    },
    "transactions": {
      "transaction": {
        "id": "34007568",
        "number": "retronumbr9931156917",
        "type": "REGULAR",
        "customer": {
          "user_id": "282024042",
          "mobile": "44700900999",
          "email": "catherine@example.com",
          "external_id": "ext_id9931156917",
          "loyalty_points": "75",
          "lifetime_points": "75",
          "lifetime_purchases": "1500",
          "current_slab": "Platinum",
          "tier_expiry_date": "2117-01-03 23:59:59",
          "type": "loyalty"
        },
        "billing_time": "2018-04-01 00:00:00",
        "delivery_status": "DELIVERED",
        "source": "instore",
        "item_status": {
          "success": "true",
          "code": "1630",
          "message": "Transaction retrospectively marked REGULAR, Transaction added successfully"
        },
        "side_effects": {
          "effect": {
            "type": "points",
            "awarded_points": "75",
            "total_points": "75"
          }
        },
        "old_id": "6464658",
        "old_type": "NOT_INTERESTED"
      }
    }
  }
}

<response>
    <status>
        <success>true</success>
        <code>200</code>
        <message>SUCCESS</message>
    </status>
    <transactions>
        <transaction>
            <id>34007568</id>
            <number>retronumbr9931156917</number>
            <type>REGULAR</type>
            <customer>
                <user_id>282024042</user_id>
                <mobile>44700900999</mobile>
                <email>catherine@example.com</email>
                <external_id>ext_id9931156917</external_id>
                <loyalty_points>75</loyalty_points>
                <lifetime_points>75</lifetime_points>
                <lifetime_purchases>1500</lifetime_purchases>
                <current_slab>Platinum</current_slab>
                <tier_expiry_date>2117-01-03 23:59:59</tier_expiry_date>
                <type>loyalty</type>
            </customer>
            <delivery_status>DELIVERED</delivery_status>
            <source>instore</source>
            <item_status>
                <success>true</success>
                <code>1630</code>
                <message>Transaction retrospectively marked REGULAR, Transaction added successfully</message>
            </item_status>
            <side_effects>
                <effect>
                    <type>points</type>
                    <awarded_points>75</awarded_points>
                    <total_points>75</total_points>
                </effect>
            </side_effects>
            <old_id>6464658</old_id>
            <old_type>NOT_INTERESTED</old_type>
        </transaction>
    </transactions>
    <side_effects/>
</response>

Retro transaction means you can convert a not-interested transaction to a loyalty transaction (by tagging a not-interested transaction to the respective customer once registered).

To avail Retro Transaction, you need to enable CONF_RETRO_TRANSACTION_ENABLE on InTouch > Settings > Systems & Deployment > InTouch PoS Configuration > Billing page.

On the Billing page, you will also see a configuration to set the maximum duration allowed convert a not-interested transaction regular.

Additional Header Required for Retro Transaction

‘X-CAP-CLIENT-SIGNATURE’

To recognize which source has made the retro call, you need to pass the name of the source. It is recommended to use a single name for a source so that it would be easy to track retro transactions of each source.

Example ’“X-CAP-CLIENT-SIGNATURE”:“INTOUCH_BLR”’

Resource Information

URI /update
HTTP Methods POST
API Version v1.1
Batch Support Yes

Request URL

https://{host}/v1.1/transaction/update?format={xml/json}

Request Body Parameters

Parameter Datatype Description
mobile/external_id/email/id* string Pass any one of the customer identifiers.
new_type* enum Specify REGULAR to convert to regular transaction.
notes string Provide any additional information about the conversion for reference.
id* int Unique ID of the transaction that you want to convert.
old_type* enum Earlier type of transaction. Usually, it will be NOT_INTERESTED.

Response Parameters

Parameter Datatype Description
id long Unique transaction ID generated internally for return.
customer obj Details of the customer associated to the transaction. Not applicable for NOT_INTERESTED transactions.
lifetime_points int Total loyalty points earned by the customer to date.
lifetime_purchases int Total purchases amount (loyalty or non-loyalty transactions) of the customer across all stores of the org.
loyalty_points int Current active loyalty points (neither redeemed nor expired) of the customer.
type enum Type of transaction. Value: return for loyalty transaction, not_interested_return for non-loyalty or not-interested transactions.
source enum Source from which the transaction is made. Values: INSTORE( for InStore), WECHAT (WeChat), MARTJACK(AnywhereCommerce), WEB_ENGAGE (Web-engage integration), ECOMMERCE (ECOMMERCE), JD (JD), TAOBAO (Taobao), TMALL (TMall), FACEBOOK (Facebook), WEBSITE (other website), OTHERS (any other source).
current_slab string Current loyalty tier of the customer.
tier_expiry_date date-time Expiry date of the current tier in YYYY-MM-DD HH:MM:SS format.
points_summaries obj Shows the details of the loyalty points.
programId long Unique ID of the loyalty program associated to the points summary.
redeemed int In total points earned from the program, the total number of points that are redeemed.
expired int In total points earned from the program, the total number of points that are expired.
returned int In total points earned from the program, the total number of points that are returned. Usually, for transaction returns.
adjusted int Points that are either credited to or debited from the customer account in adjustments. The value will be negative if debited points are more than credited, and positive if credited points are more than debited.
cumulativePurchases double Total purchases amount of the customer in the stores associated to the current loyalty program.
currentSlab string Current tier of the customer in the loyalty program.
nextSlab string Next loyalty tier of the customer.
nextSlabSerialNumber int Serial number of the next tier. Lowest tier will have 1, succeeding tier will have 2 and so on.
nextSlabDescription string Description of the next tier as saved in the loyalty program.
slabSNo int Serial number of the current tier of the customer. Lowest tier will have 1, succeeding tier will have 2 and so on.
slabExpiryDate date-time Expiry date of the current loyalty tier of the customer in YYYY-MM-DD HH:MM:SS.
billing_time date-time Actual date and time of the transaction.
type enum Loyalty type of the customer. LOYALTY if the customer is enrolled in the org’s loyalty program, NON_LOYALTY if customer has not enrolled in the loyalty program but registered mobile number or email id with the org.
old_id long Previous ID of the transaction.
old_type enum Previous transaction type - usually NOT_INTERESTED for retro transaction.

Get Transaction Details

Sample Request

https://us.api.capillarytech.com/v1.1/transaction/get?number=BILL7&format=json

Sample Response

{
   "response":{
      "status":{
         "success":"true",
         "code":200,
         "message":"Success"
      },
      "transactions":{
         "count":1,
         "transaction":[
            {
               "customer":{
                  "mobile":"918036151289",
                  "first_name":"Tom",
                  "last_name":"Sawyer",
                  "email":"tom.sawyer@example.com",
                  "external_id":"XYPZ001",
                  "source":"instore"
               },
               "billing_till":{
                  "code":"mobilepush.1",
                  "name":"mobilepush.1"
               },
               "billing_store":{
                  "code":"storecode",
                  "name":"webstore1"
               },
               "id":"293790472",
               "number":"004_QAT4967003427638098544",
               "type":"REGULAR",
               "outlier_status":"NORMAL",
               "store":"qat_dohafestivalcityqatar.1",
               "delivery_status":"DELIVERED",
               "source":"instore",
               "custom_fields":{
                  "field":[
                     {
                        "name":"tax_amount",
                        "value":"0"
                     },
                     {
                        "name":"discount_transaction",
                        "value":"0"
                     },
                     {
                        "name":"sales_localcurrency",
                        "value":"171"
                     }
                  ]
               },
               "extended_fields":{
                  "field":[
                     {
                        "name":"tax_amount",
                        "value":"0"
                     },
                     {
                        "name":"cashier_id",
                        "value":"Leah"
                     }
                  ]
               },
               "local_currency":{
                  "id":"69433407",
                  "ratio":"1.009",
                  "base_currency":{
                     "id":"227",
                     "name":"United Arab Emirates Dirham",
                     "symbol":"د.إ"
                  },
                  "transaction_currency":{
                     "id":"164",
                     "name":"Qatari riyal",
                     "symbol":"﷼"
                  },
                  "amount":"171.0",
                  "value":"172.47",
                  "discount":"0.0",
                  "gross_amount":"171.0"
               },
               "amount":"172.47",
               "billing_time":"2020-03-27 13:30:58",
               "auto_update_time":"2020-03-28 07:01:59",
               "gross_amount":"",
               "discount":"",
               "notes":"POS, Leah, 14, MNS, 4.1.0.0,687849,QATAR",
               "line_items":{
                  "line_item":[
                     {
                        "type":"REGULAR",
                        "outlier_status":"NORMAL",
                        "serial":"11",
                        "item_code":"20119183",
                        "description":"MOZZARELLA GIRASOLI",
                        "qty":"1",
                        "rate":"31.27",
                        "value":"31.27",
                        "discount":"0",
                        "img_url":"",
                        "amount":"31.27",
                        "returnable_days":"-1",
                        "extended_fields":{
                           "field":[
                              {
                                 "name":"tax_code",
                                 "value":"TAXABLE"
                              },
                              {
                                 "name":"vat_amount",
                                 "value":"0"
                              }
                           ]
                        },
                        "local_currency":{
                           "id":"228779692",
                           "ratio":"1.009",
                           "base_currency":{
                              "id":"227",
                              "name":"United Arab Emirates Dirham",
                              "symbol":"د.إ"
                           },
                           "transaction_currency":{
                              "id":"164",
                              "name":"Qatari riyal",
                              "symbol":"﷼"
                           },
                           "amount":"31.267",
                           "value":"31.267",
                           "rate":"31.267",
                           "discount":"0.0"
                        },
                        "combo_items":{
                           "combo_item":[

                           ]
                        },
                        "addon_items":{
                           "addon_item":[

                           ]
                        },
                        "split_items":{
                           "split_item":[

                           ]
                        },
                        "attributes":{
                           "attribute":[
                              {
                                 "name":"item_group",
                                 "value":"A12010101"
                              }
                           ]
                        }
                     },
                     {
                        "type":"REGULAR",
                        "outlier_status":"NORMAL",
                        "serial":"10",
                        "item_code":"60272845",
                        "description":"8 CHOC HAZLE CHUNK COOKIE",
                        "qty":"1",
                        "rate":"20.17",
                        "value":"20.17",
                        "discount":"0",
                        "img_url":"",
                        "amount":"20.17",
                        "returnable_days":"-1",
                        "extended_fields":{
                           "field":[
                              {
                                 "name":"tax_code",
                                 "value":"TAXABLE"
                              },
                              {
                                 "name":"vat_amount",
                                 "value":"0"
                              }
                           ]
                        },
                        "local_currency":{
                           "id":"228779693",
                           "ratio":"1.009",
                           "base_currency":{
                              "id":"227",
                              "name":"United Arab Emirates Dirham",
                              "symbol":"د.إ"
                           },
                           "transaction_currency":{
                              "id":"164",
                              "name":"Qatari riyal",
                              "symbol":"﷼"
                           },
                           "amount":"20.172",
                           "value":"20.172",
                           "rate":"20.172",
                           "discount":"0.0"
                        },
                        "combo_items":{
                           "combo_item":[

                           ]
                        },
                        "addon_items":{
                           "addon_item":[

                           ]
                        },
                        "split_items":{
                           "split_item":[

                           ]
                        },
                        "attributes":{
                           "attribute":[
                              {
                                 "name":"item_group",
                                 "value":"A11020301"
                              }
                           ]
                        }
                     },
                     {
                        "type":"REGULAR",
                        "outlier_status":"NORMAL",
                        "serial":"1",
                        "item_code":"21033569",
                        "description":"SUPERSOFT THICK",
                        "qty":"1",
                        "rate":"15.13",
                        "value":"15.13",
                        "discount":"0",
                        "img_url":"",
                        "amount":"15.13",
                        "returnable_days":"-1",
                        "extended_fields":{
                           "field":[
                              {
                                 "name":"tax_code",
                                 "value":"TAXABLE"
                              },
                              {
                                 "name":"vat_amount",
                                 "value":"0"
                              }
                           ]
                        },
                        "local_currency":{
                           "id":"228779702",
                           "ratio":"1.009",
                           "base_currency":{
                              "id":"227",
                              "name":"United Arab Emirates Dirham",
                              "symbol":"د.إ"
                           },
                           "transaction_currency":{
                              "id":"164",
                              "name":"Qatari riyal",
                              "symbol":"﷼"
                           },
                           "amount":"15.129",
                           "value":"15.129",
                           "rate":"15.129",
                           "discount":"0.0"
                        },
                        "combo_items":{
                           "combo_item":[

                           ]
                        },
                        "addon_items":{
                           "addon_item":[

                           ]
                        },
                        "split_items":{
                           "split_item":[

                           ]
                        },
                        "attributes":{
                           "attribute":[
                              {
                                 "name":"item_group",
                                 "value":"A11020201"
                              }
                           ]
                        }
                     }
                  ]
               },
               "item_status":{
                  "success":"true",
                  "code":600,
                  "message":"Transaction retrieved successfully"
               }
            }
         ]
      }
   }
}
<?xml version="1.0" encoding="UTF-8"?>
<root>
   <response>
      <status>
         <code>200</code>
         <message>Success</message>
         <success>true</success>
      </status>
      <transactions>
         <count>1</count>
         <transaction>
            <element>
               <amount>172.47</amount>
               <auto_update_time>2020-03-28 07:01:59</auto_update_time>
               <billing_store>
                  <code>storecode</code>
                  <name>webstore1</name>
               </billing_store>
               <billing_till>
                  <code>mobilepush.1</code>
                  <name>mobilepush.1</name>
               </billing_till>
               <billing_time>2020-03-27 13:30:58</billing_time>
               <custom_fields>
                  <field>
                     <element>
                        <name>tax_amount</name>
                        <value>0</value>
                     </element>
                     <element>
                        <name>discount_transaction</name>
                        <value>0</value>
                     </element>
                     <element>
                        <name>sales_localcurrency</name>
                        <value>171</value>
                     </element>
                  </field>
               </custom_fields>
               <customer>
                  <email>tom.sawyer@example.com</email>
                  <external_id>XYPZ001</external_id>
                  <first_name>Tom</first_name>
                  <last_name>Sawyer</last_name>
                  <mobile>918036151289</mobile>
                  <source>instore</source>
               </customer>
               <delivery_status>DELIVERED</delivery_status>
               <discount />
               <extended_fields>
                  <field>
                     <element>
                        <name>tax_amount</name>
                        <value>0</value>
                     </element>
                     <element>
                        <name>cashier_id</name>
                        <value>Leah</value>
                     </element>
                  </field>
               </extended_fields>
               <gross_amount />
               <id>293790472</id>
               <item_status>
                  <code>600</code>
                  <message>Transaction retrieved successfully</message>
                  <success>true</success>
               </item_status>
               <line_items>
                  <line_item>
                     <element>
                        <addon_items>
                           <addon_item />
                        </addon_items>
                        <amount>31.27</amount>
                        <attributes>
                           <attribute>
                              <element>
                                 <name>item_group</name>
                                 <value>A12010101</value>
                              </element>
                           </attribute>
                        </attributes>
                        <combo_items>
                           <combo_item />
                        </combo_items>
                        <description>MOZZARELLA GIRASOLI</description>
                        <discount>0</discount>
                        <extended_fields>
                           <field>
                              <element>
                                 <name>tax_code</name>
                                 <value>TAXABLE</value>
                              </element>
                              <element>
                                 <name>vat_amount</name>
                                 <value>0</value>
                              </element>
                           </field>
                        </extended_fields>
                        <img_url />
                        <item_code>20119183</item_code>
                        <local_currency>
                           <amount>31.267</amount>
                           <base_currency>
                              <id>227</id>
                              <name>United Arab Emirates Dirham</name>
                              <symbol>د.إ</symbol>
                           </base_currency>
                           <discount>0.0</discount>
                           <id>228779692</id>
                           <rate>31.267</rate>
                           <ratio>1.009</ratio>
                           <transaction_currency>
                              <id>164</id>
                              <name>Qatari riyal</name>
                              <symbol></symbol>
                           </transaction_currency>
                           <value>31.267</value>
                        </local_currency>
                        <outlier_status>NORMAL</outlier_status>
                        <qty>1</qty>
                        <rate>31.27</rate>
                        <returnable_days>-1</returnable_days>
                        <serial>11</serial>
                        <split_items>
                           <split_item />
                        </split_items>
                        <type>REGULAR</type>
                        <value>31.27</value>
                     </element>
                     <element>
                        <addon_items>
                           <addon_item />
                        </addon_items>
                        <amount>20.17</amount>
                        <attributes>
                           <attribute>
                              <element>
                                 <name>item_group</name>
                                 <value>A11020301</value>
                              </element>
                           </attribute>
                        </attributes>
                        <combo_items>
                           <combo_item />
                        </combo_items>
                        <description>8 CHOC HAZLE CHUNK COOKIE</description>
                        <discount>0</discount>
                        <extended_fields>
                           <field>
                              <element>
                                 <name>tax_code</name>
                                 <value>TAXABLE</value>
                              </element>
                              <element>
                                 <name>vat_amount</name>
                                 <value>0</value>
                              </element>
                           </field>
                        </extended_fields>
                        <img_url />
                        <item_code>60272845</item_code>
                        <local_currency>
                           <amount>20.172</amount>
                           <base_currency>
                              <id>227</id>
                              <name>United Arab Emirates Dirham</name>
                              <symbol>د.إ</symbol>
                           </base_currency>
                           <discount>0.0</discount>
                           <id>228779693</id>
                           <rate>20.172</rate>
                           <ratio>1.009</ratio>
                           <transaction_currency>
                              <id>164</id>
                              <name>Qatari riyal</name>
                              <symbol></symbol>
                           </transaction_currency>
                           <value>20.172</value>
                        </local_currency>
                        <outlier_status>NORMAL</outlier_status>
                        <qty>1</qty>
                        <rate>20.17</rate>
                        <returnable_days>-1</returnable_days>
                        <serial>10</serial>
                        <split_items>
                           <split_item />
                        </split_items>
                        <type>REGULAR</type>
                        <value>20.17</value>
                     </element>
                     <element>
                        <addon_items>
                           <addon_item />
                        </addon_items>
                        <amount>15.13</amount>
                        <attributes>
                           <attribute>
                              <element>
                                 <name>item_group</name>
                                 <value>A11020201</value>
                              </element>
                           </attribute>
                        </attributes>
                        <combo_items>
                           <combo_item />
                        </combo_items>
                        <description>SUPERSOFT THICK</description>
                        <discount>0</discount>
                        <extended_fields>
                           <field>
                              <element>
                                 <name>tax_code</name>
                                 <value>TAXABLE</value>
                              </element>
                              <element>
                                 <name>vat_amount</name>
                                 <value>0</value>
                              </element>
                           </field>
                        </extended_fields>
                        <img_url />
                        <item_code>21033569</item_code>
                        <local_currency>
                           <amount>15.129</amount>
                           <base_currency>
                              <id>227</id>
                              <name>United Arab Emirates Dirham</name>
                              <symbol>د.إ</symbol>
                           </base_currency>
                           <discount>0.0</discount>
                           <id>228779702</id>
                           <rate>15.129</rate>
                           <ratio>1.009</ratio>
                           <transaction_currency>
                              <id>164</id>
                              <name>Qatari riyal</name>
                              <symbol></symbol>
                           </transaction_currency>
                           <value>15.129</value>
                        </local_currency>
                        <outlier_status>NORMAL</outlier_status>
                        <qty>1</qty>
                        <rate>15.13</rate>
                        <returnable_days>-1</returnable_days>
                        <serial>1</serial>
                        <split_items>
                           <split_item />
                        </split_items>
                        <type>REGULAR</type>
                        <value>15.13</value>
                     </element>
                  </line_item>
               </line_items>
               <local_currency>
                  <amount>171.0</amount>
                  <base_currency>
                     <id>227</id>
                     <name>United Arab Emirates Dirham</name>
                     <symbol>د.إ</symbol>
                  </base_currency>
                  <discount>0.0</discount>
                  <gross_amount>171.0</gross_amount>
                  <id>69433407</id>
                  <ratio>1.009</ratio>
                  <transaction_currency>
                     <id>164</id>
                     <name>Qatari riyal</name>
                     <symbol></symbol>
                  </transaction_currency>
                  <value>172.47</value>
               </local_currency>
               <notes>POS, Leah, 14, MNS, 4.1.0.0,687849,QATAR</notes>
               <number>004_QAT4967003427638098544</number>
               <outlier_status>NORMAL</outlier_status>
               <source>instore</source>
               <store>qat_dohafestivalcityqatar.1</store>
               <type>REGULAR</type>
            </element>
         </transaction>
      </transactions>
   </response>
</root>

This API allows you to fetch the details of a specific transaction based on the transaction id.

Resource Information

URI /get
HTTP Methods GET
Authentication Yes
Batch Support Yes

Additional Header

Header Description
language Specify the ISO language code to get transaction level extended field details in your preferred language (other than English). For example, zh for Chinese, id for Indonesian, ar for Arabic.

Request URL

https://{host}/v1.1/transaction/get?{requestParams}&format={xml/json}

Request Query Parameters

Parameter Datatype Description
id* long Unique ID of the transaction to fetch.
number* string Unique transaction number that you want to fetch.
store_code* string Fetch the transactions of a specific store. Pass the store code.
till_code* string Fetch the transactions of a specific TILL. Pass the respective TILL code.
amount double Filter transactions of a specific amount.
date date Filter transactions of a specific date. Pass the date in YYYY-MM-DD format.
type enum Filter transactions of a specific type. Values: REGULAR, NOT_INTERESTED, RETURN, NOT_INTERESTED_RETURN, MIXED, NI_MIXED, ALL (to retrieve any transaction type, for mixed or NI mixed, it retrieves both transaction and return details). By default it shows the details of regular transaction.
tenders boolean Pass true to retrieve transaction details.
credit_notes boolean Pass true to retrieve credit notes.
user_id boolean Pass true to retrieve unique ID of the customer in response.

Response Parameters

Parameter Datatype Description
id long Unique transaction ID generated internally.
customer obj Details of the customer associated to the transaction. Not applicable for NOT_INTERESTED transactions.
lifetime_points int Total loyalty points earned by the customer to date.
lifetime_purchases int Total purchases amount (loyalty or non-loyalty transactions) of the customer across all stores of the org.
loyalty_points int Current active loyalty points (neither redeemed nor expired) of the customer.
type enum Type of transaction. Value: regular for loyalty transaction, not_interested for non-loyalty or not-interested transactions.
source enum Source from which the transaction is made. Values: INSTORE( for InStore), WECHAT (WeChat), MARTJACK(AnywhereCommerce), WEB_ENGAGE (Web-engage integration), ECOMMERCE (ECOMMERCE), JD (JD), TAOBAO (Taobao), TMALL (TMall), FACEBOOK (Facebook), WEBSITE (other website), OTHERS (any other source).
current_slab string Current loyalty tier of the customer.
tier_expiry_date date-time Expiry date of the current tier in YYYY-MM-DD HH:MM:SS format.
points_summaries obj Shows the details of the loyalty points.
programId long Unique ID of the loyalty program associated to the points summary.
redeemed int In total points earned from the program, the total number of points that are redeemed.
expired int In total points earned from the program, the total number of points that are expired.
returned int In total points earned from the program, the total number of points that are returned. Usually, for transaction returns.
adjusted int Points that are either credited to or debited from the customer account in adjustments. The value will be negative if debited points are more than credited, and positive if credited points are more than debited.
cumulativePurchases double Total purchases amount of the customer in the stores associated to the current loyalty program.
currentSlab string Current tier of the customer in the loyalty program.
nextSlab string Next loyalty tier of the customer.
nextSlabSerialNumber int Serial number of the next tier. Lowest tier will have 1, succeeding tier will have 2 and so on.
nextSlabDescription string Description of the next tier as saved in the loyalty program.
slabSNo int Serial number of the current tier of the customer. Lowest tier will have 1, succeeding tier will have 2 and so on.
slabExpiryDate date-time Expiry date of the current loyalty tier of the customer in YYYY-MM-DD HH:MM:SS.
registered_on date-time Date on which the customer is enrolled in the org’s loyalty.
updated_on date-time Recent date on which the customer details are updated.
type enum Loyalty type of the customer. LOYALTY if the customer is enrolled in the org’s loyalty program, NON_LOYALTY if customer has not enrolled in the loyalty program but registered mobile number or email id with the org.
custom_fields obj Transaction or line-item level custom field details - field name (name) and field value (value).
extended_fields obj Transaction or line-item level extended field details - extended field name (name) and extended field value (value).
billing_till obj TILL associated to the transaction - TILLname and TILL code.
billing_store obj Store associated to the transaction - storename and store code.
extended_fields obj Valid transaction level extended field details in name and value pairs. You can also pass line-item level extended field details in line_item object.
payment_details obj Payment details for the transaction.
attributes obj Attributes of the current line-item in name and value pairs.
mode string Mode of payment. This has to be the mode configured for your org.
value float Amount paid through the current mode.
attributes obj Payment mode attributes in name and value pairs.
custom_fields obj Transaction level custom field details. Pass line-item level custom field details in line_item object.
line_items obj Details of transaction line-items.
serial long Serial number of the current line-item.
description string Description of the line-item.
item_code string Unique line-item code.
variant string Variant code of the item. Applicable for variant product.
addon_items obj Details of add-on items. For example, pizza with extra cheese, and personalized toppings.
combo_items obj Details of combo or bundle items. For example, buy 1 shirt get one free, shirt+pant, pack of 5 soaps.
split_items obj Details of split items. For example, a necklace having gold rate, store rate, making charge, and wastage charges.
item_code string Unique code of the add-on, split, or combo item. For example, combo-22, pizza01_addon.
quantity double Quantity of the current add-on, split, or combo item.
local_currency obj Currency of the store associated to the transaction.
id long Unique ID of the currency converter.
ratio double Currency conversion ratio (local currency/base currency)
base_currency obj Details of the org’s base currency.
id long Unique ID of the base currency.
name string Name of the base currency.
symbol string Symbol of the base currency.
transaction_currency obj Details of transacted currency. This is usually local currency.
id long Unique ID of the transacted currency.
name string Name of the transacted currency.
symbol string Symbol of the transacted currency.

Response Codes

Success Codes

Code Description
600 Transaction added successfully.
Transaction retrieved successfully.
Transaction updated successfully.
1630 Transaction marked as regular through Retro conversion. Transaction added successfully.

Error Codes

Code Description
500 Unable to retrieve transaction.
517 Rate limit exceeded for that specific user.
601 Transaction failed. Transaction amount, quantity, rate, or discount is invalid.
602 Transaction number is invalid.
603 Points are already used (Deprecated).
604 Transaction number already exists.
605 Invalid transaction type. Only regular, return and not-interested transaction types are supported.
606 Customer identifier is not passed. Please enter customer’s mobile or email or external id to process.
607 No transaction id passed. Please pass the transaction id to process.
608 Unable to add transaction.
609 Update failed. Please verify all the fields.
610 Unable to register. Please verify all the fields.
611 Customer not found.
614 Transaction is already cancelled.
615 Transaction details are not passed.
616 Item code already exists.
617 Invalid attribute for the item.
618 Customer is marked as fraud.
619 Transaction id is not provided.
620 Transaction id is invalid.
621 Transaction date is invalid. Transaction date should be within the accepted past or future date range limit.
622 Unable to add line-item.
623 Unable to trigger other related events for the transaction.
624 Unable to process return-transaction. You can make a return only after adding a transaction.
625 Transaction number does not exist.
626 Unable to return transaction. The quantity of returned items are more than purchased items.
627 Quantity cannot be negative.
628 Invalid return transaction type.
629 The return quantity of the item is more than available quantity.
630 The return amount is more than the transaction/line-item amount.
631 Transaction amount cannot be negative.
632 Cannot return the transaction with return type LINE_ITEM because the type AMOUNT has already been used for returning the same transaction.
633 The entire transaction is already returned.
634 This transaction is already returned.
635 Cannot return the transaction with the return type AMOUNT because the type LINE_ITEM has been used for returning the same transaction.
636 The transaction is already returned with the return type as LINE_ITEM. You can process return for other items only with return type LINE_ITEM.
637 Unable to revert points issued to the customer (for return transaction). Please try again later.
638 Unable to return transaction. The transaction is already returned with type LINE_ITEM. Hence, you cannot use the type AMOUNT for the same transaction.
639 Unable to return full transaction. A part of the transaction or complete transaction is already returned.
640 Points or coupons are not redeemed for this transaction.
641 No customer found.
642 Redemption failed. An error occurred in points/coupon redemption.
643 Invalid transaction. The transaction date exceeds the accepted future date limit.
644 Invalid transaction. The transaction date cannot be less than the accepted past date limit.
645 Transaction addition failed for not interested.
646 Customer registration failed. The email id is invalid.
647 Customer registration failed. Email id is already assigned to another customer.
648 Customer registration failed. Mobile number is already assigned to another customer.
649 Customer registration failed. Mobile number is invalid.
650 Customer registration failed. Mobile number is not accepted as a unique identifier.
651 Customer registration failed. Mobile number is required for registration.
652 Customer registration failed. Mobile number/email id/external id is invalid.
653 Customer registration failed. External id is already assigned to another customer.
654 Customer registration failed. External id is not accepted as a unique identifier.
655 Customer registration failed. Customer is not registered in loyalty program.
656 No customer found.
657 Customer registration failed. Registration in EUP failed.
658 Customer registration failed. Only email id is not sufficient for registration.
659 Customer registration failed. Please enter email id to register.
660 Customer registration failed. Registration date exceeds the accepted past or future date limit.
661 Amount of the line-item amount cannot be negative.
662 Value of a line cannot be negative.
663 Rate of a line-item cannot be negative
664 Discount of a line-item cannot be negative.
665 Gross amount of the transaction cannot be negative.
666 Discount cannot be negative.
667 Unable to find the transaction ID for this customer.
668 Unable to find the transaction number for this customer.
669 Unable to update custom field.
670 Transaction id/number is not provided.
671 Invalid Store or TILL code.
Invalid category code.
672 Batch limit exceeded.
673 Returning of transactions is not allowed.
674 Returning of line item is not allowed.
675 Returning of transaction amount is not allowed.
676 Returning of a complete transaction amount is not allowed.
677 Unable to process. Please enter a transaction number for returning a transaction.
678 Amount of returned item is more than purchased item.
679 Line-item(s) to be returned is not specified.
680 No transactions of the specific customer were found.
681 Transactions are blocked for this customer.
682 Currency conversion is disabled for the org.
683 Failed to call new bill event EMF.
684 Failed EMF new bill DVS event.
685 Field length too long.
686 Unable to add transaction.
687 Points activities are queued and will be updated later.
Item code {x} merge is not supported.
688 No matching line-item found for return.
Transaction number not found.
689 Points processing failed
690 Points processing failed
691 Points processing failed
692 Points processing failed
693 Points processing failed
694 Points processing failed
695 Invalid configuration. Please report to the Capillary Support.
696 Points processing failed
697 Points processing failed
698 Points processing failed.
699 Invalid configuration. Please report to the Capillary Support.
710 Return bill event failed from EMF.
820 Current operation is not allowed. The customer is marked as fraud.
1101 Invalid loyalty program ID passed.
1102 Invalid currency conversion ratio passed.
1103 Invalid shipping store code passed.
1623 Transaction type is invalid.
1624 Insufficient parameters passed to fetch transaction.
1625 Target type is not specified.
1626 The requested transaction type cannot be changed.
1627 The transaction is already marked as retro.
1628 Transaction id is invalid
1629 Client signature is required to perform this action
1631 Retro transaction is not enabled for your organization
1632 Registration date is too older than the transaction date. See the retro configuration set for your organization
1633 The duration between registration and transaction mapping exceeds the limit set
1634 Return type is invalid
1635 Please pass line-items that need to be returned
1636 Transaction status is invalid
9601 Failed to add line-item.
9602 Failed to add credit notes.
9603 Failed to add payment more details (tender).
9604 Failed to add custom fields
9605 Base currency is not set for the org.
9606 Currency not passed for the transaction.
9607 Payment mode (tender) not found.
9608 Line-item with the item code {x} passed is marked as outlier.
9609 Invalid payment attribute passed.
9610 New bill event failed. Points are not awarded.
9611 Transaction is marked as outlier.
9612 Unable to save credit notes.
9613 Invalid payment attribute.
9614 Multiple loyalty bills found to be returned.
9615 Validity (in days) for return policy is not defined.
9616 Single loyalty bill found. Allowing regular return.

Points

Points represent loyalty points of an organization that are issued to the loyalty customers through different sources such as Loyalty Manager, Data Import (import profiles) and Member Care (GoodWill points). Customers can redeem their points against transactions.

The APIs of points entity are interdependent. For example, to redeem points, first you need to check whether a customer can redeem those points (isredeemable), validate customer’s registered mobile number by issuing validation code, and then redeem points using the validation code received by the customer.

The points entity allows you to perform the following tasks:

Check If Points are Redeemable

Sample Request

http://us.intouch.capillarytech.com/v1.1/points/isredeemable?program_id=504&points=100&issue_otp=true&mobile=44700900999&format=json

Sample Response

{
  "response": {
    "status": {
      "success": "true",
      "code": "200",
      "message": "SUCCESS"
    },
    "responses": {
      "points": {
        "mobile": "44700900999",
        "points_redeemed": "100",
        "redeemed_value": "100",
        "balance": "257",
        "item_status": {
          "success": "true",
          "code": "800",
          "message": "Points Redeemed"
        },
        "response": {
          "status": {
            "success": "true",
            "code": "200",
            "message": "SUCCESS"
          },
          "points": {
            "redeemable": {
              "mobile": "44700900999",
              "points": "100",
              "is_redeemable": "true",
              "points_redeem_value": 536,
              "points_redeem_local_value": 5239.79,
              "points_currency_ratio": "1",
              "item_status": {
                "success": "true",
                "code": "800",
                "message": "Points can be redeemed"
              }
            }
          }
        }
      }
    }
  }
}
<response>  
<status>    
<success>true</success>    
<code>200</code>    
<message>SUCCESS</message>  
</status>  
<responses>    
<points>      
<mobile>44700900999</mobile>
<email></email>
<external_id></external_id>
<points_redeemed>100</points_redeemed>      
<redeemed_value>100</redeemed_value>
<balance>257</balance>
<item_status>        
<success>true</success>        
<code>800</code>        
<message>Points Redeemed</message>      
</item_status>    <response>  
<status>    
<success>true</success>    
<code>200</code>    
<message>SUCCESS</message>  
</status>  
<points>    
<redeemable>      
<mobile>44700900999</mobile>      
<points>100</points>
<is_redeemable>true</is_redeemable> 
<points_currency_ratio>0</points_currency_ratio>
<item_status>        
<success>true</success>        
<code>800</code>        
<message>Points can be redeemed</message>      
</item_status>    
</redeemable>  
</points>
</response>
</points>  
</responses>
</response>

Customers can redeem their active points according to the redemption criteria set for the organization (Loyalty Program). For example, I could set redemption criteria as allow redemption only in multiples of 10 and a maximum of 200 points per time.

This API lets you verify whether a specific number of points can be redeemed by a customer. With this API, you can now issue validation code to the customer automatically upon successful validation. This will reduce an additional step of calling points/validationcode API to issue validation code.

Resource Information

URI points/isredeemable?{query_params}
Rate Limited? Yes
Authentication Yes
HTTP Method GET
Batch Support No

Request URL

To validate points and issue code if the validation is successful https://{host}/v1.1/points/isredeemable?points={points to redeem}&issue_otp=true&{identifier_name}={identifier_value}&format={xml/json}

To just validate points https://{host}/v1.1/points/isredeemable?points={points to redeem}&validation_code={OTP}&{mobile/email}={value}&format={xml/json}

Request Query Parameters

Parameter Datatype Description
mobile/email/external_id/card_number/card_external_id* enum Pass any of the registered identifier type.
program_id long Unique ID of the loyalty program from which points need to redeem.
group_redemption boolean Pass true for group redemption - points earned in one program need to redeem in a different program of the org.
points* int Number of points to redeem.
issue_otp boolean Pass true to issue OTP if the validation is successful.
validation_code string OTP issued to the customer’s mobile number.
skip_validation boolean Pass true if you want to skip validation.
validation_type enum Preferred mode of validation. Value: MISSED_CALL, SMS, INVALID. Use invalid if you want to skip_validation.
user_group2_primary_user_id** long Unique user ID of the primary member of the group associated with the points to redeem.
user_group2_id** int Unique ID of the group associated with the points to redeem.
user_group2_external_id** string Unique external ID of the group associated with the points to redeem.
use_default_user_group2** boolean Pass true to associate the default group with the points to redeem.
use_default_user_group2** boolean Pass true to associate the default group with the points to redeem.
currency_input boolean

Response Parameters

Parameter Datatype Description
points_redeemed int Number of points to redeem.
redeemed_value double Value of the points to redeem.
balance int Remaining points in the customer’s account after redemption.
points int Number of points to redeem.
is_redeemable boolean Whether the points can be redeemed.
points_redeem_value int Value of points in base currency.
points_redeem_local_value double Value of points in local currency.
points_currency_ratio double

Issue Validation Code (to Redeeming Points)

Sample Request

http://us.intouch.capillarytech.com/v1.1/points/validationcode?mobile=447700900000&points=50&format=json

Sample Response

{
  "response": {
    "status": {
      "success": "true",
      "code": "200",
      "message": "Operation Successful"
    },
    "validation_code": {
      "code": {
        "user_id": "55456",
        "mobile": "44700900999",
        "points": "50",
        "item_status": {
          "success": "true",
          "code": "200",
          "message": "Validation Code Issued by SMS/Email"
        }
      }
    }
  }
}
<response>  
<status>    
<success>true</success>    
<code>200</code>    
<message>Operation Successful</message>  
</status>  
<validation_code>    
<code>      
<user_id>55456</user_id>
<mobile>44700900999</mobile>      
<points>50</points>   
<item_status>        
<success>true</success>        
<code>200</code>        
<message>
Validation Code Issued by SMS/Email
</message>      
</item_status>    
</code>  
</validation_code>
</response>

Before making points/redeem API call, you need to validate the customer by issuing validation code to the registered mobile number/email id.

This API allows you to issue a dynamic validation code to the customer’s registered mobile number/email id which is required to pass while redeeming points. The validation code is valid only for a specific time period post which it expires automatically. If you try to issue validation code within the validity period, same code will be issued again.

The validity period and communicate via is set on the OTPConfigurations page of InTouch > Settings > Organization Setup

Resource Information

URI points/validationcode/{request_params}
Rate Limited? Yes
Authentication Yes
HTTP Method GET
Batch Support No

Request URL

https://{host}/v1.1/points/validationcode?{identifier}={value}&points={points_to_be_redeemed}&format={xml/json}

Request Parameters

Parameter Datatype Description
identifier* enum Pass any of the identifier types of the customer to issue validation code. Value: mobile, email, external_id, user_id.
value* string Pass the respective identifier value. For example, email=tom.sawyer@example.com
points* int Number of points to redeem.

Response Parameters

Parameter Datatype Description
user_id long Unique ID of the customer.
mobile string Mobile number of the customer.
points int Number of points to redeem.

Redeem Points

Sample Request

http://us.intouch.capillarytech.com/v1.1/points/redeem?validation_type=SMS&program_id=504&format=json

Sample POST Request

{
    "root": {
        "redeem": [{
            "points_redeemed": 10,
            "customer": {
                "mobile": "44700900999",
                "external_id": "",
                "email": "",
                "card_number": "",
                "card_external_id": ""
            },
            custom_fields [{
            "name": "field1",
            "value": "value1"
            },
            {
            "name": "field1",
            "value": "value1"
            }],
            "redemption_time": "2020-03-13 18:02:34",
            "redemption_purpose": "2020-03-13 18:02:34",
            "transaction_number": "red123",
            "billing_time": "",
            "external_reference_number": "toms12d",
            "till_id": "",
            "notes": "10 points redemption by SMS.",
            "validation_code": "4PZGXC",
            "group_redemption": "false"

        }]
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<root>
   <root>
      <redeem>
         <element>
            <customer>
               <email />
               <external_id />
               <mobile>44700900999</mobile>
               <card_number></card_number>
            </customer>
            <notes>10 points redemption by SMS.</notes>
            <points_redeemed>10</points_redeemed>
            <redemption_time>2020-03-13 18:02:34</redemption_time>
            <till_id />
            <transaction_number>red123</transaction_number>
            <external_reference_number>toms12d</external_reference_number>
            <validation_code>4PZGXC</validation_code>
            <group_redemption>false</group_redemption>
         </element>
      </redeem>
   </root>
</root>

Sample Response

{
    "response": {
        "status": {
            "success": "true",
            "code": 200,
            "message": "Success"
        },
        "responses": {
            "points": {
                "mobile": "919700000000",
                "email": "tom.sawyer@example.com",
                "external_id": "",
                "user_id": "98662653",
                "redemption_id": "r0njPT",
                "points_redeemed": "10",
                "redeemed_value": 10,
                "redeemed_local_value": 10,
                "balance": 2906,
                "side_effects": {
                    "effect": [
                        {
                            "id": 1425658,
                            "case_value": "true",
                            "num_points": 10,
                            "currency_value": 10,
                            "validation_code": "4PZGXC",
                            "points_redemption_summary_id": "1425658",
                            "redeemed_on_bill_number": "red123",
                            "redeemed_on_bill_id": -1,
                            "type": "points"
                        }
                    ]
                },
                "item_status": {
                    "success": "true",
                    "code": 800,
                    "message": "Points Redeemed"
                }
            }
        }
    }
}
<?xml version="1.0" encoding="UTF-8"?>
<root>
   <response>
      <responses>
         <points>
            <balance>2906</balance>
            <email>tom.sawyer@example.com</email>
            <external_id />
            <item_status>
               <code>800</code>
               <message>Points Redeemed</message>
               <success>true</success>
            </item_status>
            <mobile>919700000000</mobile>
            <points_redeemed>10</points_redeemed>
            <redeemed_local_value>10</redeemed_local_value>
            <redeemed_value>10</redeemed_value>
            <redemption_id>r0njPT</redemption_id>
            <side_effects>
               <effect>
                  <element>
                     <case_value>true</case_value>
                     <currency_value>10</currency_value>
                     <id>1425658</id>
                     <num_points>10</num_points>
                     <points_redemption_summary_id>1425658</points_redemption_summary_id>
                     <redeemed_on_bill_id>-1</redeemed_on_bill_id>
                     <redeemed_on_bill_number>red123</redeemed_on_bill_number>
                     <type>points</type>
                     <validation_code>4PZGXC</validation_code>
                  </element>
               </effect>
            </side_effects>
            <user_id>98662653</user_id>
         </points>
      </responses>
      <status>
         <code>200</code>
         <message>Success</message>
         <success>true</success>
      </status>
   </response>
</root>

You can redeem points of a customer using the issued validation code. Ensure that you have validated the points to be redeemed and issued validation code to the customer’s mobile number before redeeming. You need to have the validation code to process points redemption.

Resource Information

URI points/redeem
Rate Limited? Yes
Authentication Yes
HTTP Method POST
Batch Support No

Request URL

https://{host}/v1.1/points/redeem?{query_param}={param_value}&format={xml/json}

Request Query Parameters

Parameter Datatype Description
user_group2_primary_user_id** long Unique user ID of the primary member of the group associated with the points to redeem.
user_group2_id** int Unique ID of the group associated with the points to redeem.
user_group2_external_id** string Unique external ID of the group associated with the points to redeem.
skip_validation boolen Pass true to skip customer validation to redeem points.
program_id long Unique ID of the program from which points need to be redeemed. Applicable for orgs with multi-loyalty program enabled.
validation_type enum Validation type used to redeem points. Value: MISSED_CALL, SMS.

Request Body Parameters

Parameter Datatype Description
customer* obj Pass any of the registered identifiers of the customer. Value: mobile, email, external_id, card_number, card_external_id.
points_redeemed* int Provide the number of points to be redeemed.
transaction_number string Provide the transaction number for which the points has to be redeemed.
external_reference_number string Unique external reference number for redemption (say, passed by the integrator). You also need to tag the number to the transaction
validation_code* string Provide the validation code received by the customer through points/validationcode.
redemption_time date-time Provide the redemption date and time in YYYY-MM-DD HH-MM-SS format.
till_id string Till ID from which points are redeemed.
group_redemption boolean Pass true for cross program redemption, that is, redeem loyalty points earned in a loyalty program in a different loyalty program of the org. Default value is false.
redemption_purpose string Purpose of the redemption.
custom_fields array Pass points redemption level custom field details in name and value.

Response Parameters

Parameter Datatype Description
redemption_id long Unique reference ID generated for the redemption. This is also required to reverse redeemed points in case of transaction return.
points_redeemed int Number of points redeemed.
redeemed_value double Value of the points redeemed.
balance int Remaining points in the customer’s account after redemption.
side_effects obj Other effects due to points redemption. You will see details such bill number/ID on which points are redeemed.

Response Codes

Success Codes

Code Description
800 Points redeemed successfully

Error Codes

Code Description
686 User is from campaign and has not enrolled in the loyalty program. Points redemption is not applicable for the user.
804 Insufficient current points.
805 Insufficient lifetime points.
806 Insufficient lifetime purchases amount.
807 Redemptions points not divisible.
809 Customer is marked as fraud.
818 Current points are less than points requested for redemption.
819 Points to redeem exceeds the threshold limit (maximum points that can be redeemed in a transaction).
821 Points you are trying to redeem are less than the minimum points allowed.
886 Unable to process points. Please try again later.
887 Unable to process points. Please try again later.
888 Invalid configuration. Please report to capillary support.
801 Points you are trying to redeem are invalid
802 Mobile number/email id/external id you have entered is invalid
803 Unable to redeem. The points you are trying to redeem is more than the available points
804 Insufficient current points.
805 Insufficient lifetime points.
806 Insufficient lifetime purchases amount.
807 Unable to redeem. Make sure that the points you are trying to redeem is a multiple of . Check the points redemption configuration of your organization.
808 Unable to redeem. Validation code is invalid
809 Unable to process. Customer is marked as fraud
810 Mismatch in points for revert API call
811 The transaction number entered to redeem/revert points is invalid
812 The points have been reverted already for this transaction number
813 Insufficient current points available for redemption
814 No points were redeemed on this transaction number
815 Unable to process points at this moment. Please try again later
816 Unable to find customer in this organization
817 Points redemption failed.
818 Points you are trying to redeem are more than the available points
819 Points you are trying to redeem are more than the maximum allowed redemption limit.
Unable to send message to customer
820 Unable to process. Customer is marked as fraud
821 Points you are trying to redeem are less than the minimum redemption limit
822 Unable to find missed call from the registered mobile number
823 Missed call redemption is disabled for your organization
824 Mobile number validation is mandatory for redeeming points
825 Client signature is required
826 Invalid points category or invalid configuration
827 Unable to redeem points. Points redemption is enabled for your organization
859 The redemption time you have passed is invalid
860 Unable to issue OTP
881 Customer is not registered into the loyalty program
888 Configuration is invalid. Please report to Capillary Support
889 Points processing failed. Please try again later.
894 Unable to process points at this moment. Please try again later
895 Loyalty program is not configured for your organization
898 Unable to process points at this moment. Please try again later
899 Configuration is invalid. Please report to Capillary Support
901 Invalid points or points redemption Id passed.
902 Redemption ID does not exist.
903 Unable to redeem points.
904 Invalid customer details passed.
3045 Points Redemption is not allowed for the customer with id {x} as the status is fraud.
3802 Points reversal redeemed points already reversed.

Coupon

Coupon represents store promotions or discounts created through Capillary Campaign Manager. A single campaign could contain one or more coupons or coupon series. Coupons are issued to loyalty or non-loyalty customers through SMS or email.

You cannot create new coupons using coupon APIs. You can just send or retrieve coupons that are already created in your campaigns. Hence, it is important to note the coupon code, coupon id or coupon series id for making API calls.

You cannot create new coupons using coupon APIs; instead, you can send or retrieve coupons that are already created in your campaigns. Hence, it is important to note the coupon code, coupon id or coupon series id to use coupon APIs.

The coupon entity allows you to perform the following tasks:

Issue Coupon

http://us.intouch.capillarytech.com/v1.1/coupon/issue?format=json

Sample POST Request

{
  "root": {
    "coupon": [{
      "series_id": "832",
      "customer": { "mobile": "447700900000" }
    }]
  }
}
<root>
    <coupon>
        <series_id>832</series_id>
        <customer>
            <mobile>447700900000</mobile>
            <email></email>
            <external_id></external_id>
        </customer>
    </coupon>
</root>

Sample Response

{
  "response": {
    "status": {
      "success": "true",
      "code": "200",
      "message": "SUCCESS"
    },
    "coupon": {
      "code": "xqnq5m5u",
      "valid_till": "2016-12-25",
      "series_info": {
        "id": "832",
        "description": "Sample description",
        "discount_code": "XYZ123",
        "valid_till": "2012-12-31",
        "discount_type": "ABS",
        "discount_value": "0",
        "detailed_info": "Sample information"
      },
      "customer": {
        "mobile": "447700900000",
        "user_id": "4453654"
      },
      "item_status": {
        "success": "true",
        "code": "700",
        "message": "Coupon processing successful"
      }
    }
  }
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status>
        <success>true</success>
        <code>200</code>
        <message>SUCCESS</message>
    </status>
    <coupon>
        <code>xqnq5m5u</code>
<valid_till>2016-12-25</valid_till> 
<!-- this is due date of the coupon -->
<series_info>
<id>832</id>        
<description>Sample description</description>        
<discount_code>XYZ123</discount_code>        
<valid_till>2012-12-31</valid_till>        
<discount_type>ABS</discount_type>        
<discount_value>0</discount_value>        
<discount_on></discount_on>        
<!-- “discount_on” can be on BILL or LINEITEM -->
<detailed_info>Sample information</detailed_info>      
</series_info>    
        <customer>
            <mobile>447700900000</mobile>
            <email></email>
            <external_id></external_id>
            <user_id>4453654</user_id>
            <!-- user_id will be returned
only if the query parameter “user_id” is passed 
and that is set to “true” -->
        </customer>
        <item_status>
            <success>true</success>
            <code>700</code>
            <message>Coupon processing successful</message>
        </item_status>
    </coupon>
</response>

This API allows you to issue a specific coupon series to a customer.

Resource Information

URI coupon/issue
Rate Limited? Yes
Authentication Yes
HTTP Method POST
Batch Support Yes

Request URL

http://{host}/v1.1/coupon/issue?format={xml/json}

Request Parameters

Code Description
Customer identifier* Any identifier of the customer to whom you want to issue coupon
id Coupon series id that you want to issue

Reissue Coupon

# Sample Request
http://us.intouch.capillarytech.com/v1.1/coupon/resend?format=xml&id=13596576

Sample Response

{
   "response":{
      "status":{
         "success":"true",
         "code":"200",
         "message":"SUCCESS"
      },
      "coupons":{
         "coupon":[
            {
               "id":"13596576",
               "code":"4R5A33",
               "item_status":{
                  "success":"true",
                  "code":"700",
                  "message":"Coupon Resent"
               }
            }
         ]
      }
   }
}
<response>  
<status>    
<success>true</success>    
<code>200</code>    
<message>SUCCESS</message>  
</status>  
<coupons>    
<coupon>      
<id>13596576</id>
<code>4R5A33</code>
<!-- id and code will be returned depending
on the request param -->   
<item_status>        
<success>true</success>        
<code>700</code>        
<message>Coupon Resent</message>      
</item_status>    
</coupon>  
</coupons>
</response>

This API allows you to reissue active coupons of a loyalty customer. You can reissue only the coupon code and the coupon validity.

Resource Information

URI coupon/resend
Rate Limited? Yes
Authentication Yes
HTTP Method GET
Batch Support No

Request URL

http://{host}/v1.1/coupon/resend?{identifier}&{input_params}&format={xml/json}

Request Parameters

Any one among the following parameters is mandatory.

Parameter Description
Customer identifier* Any identifier of the customer to whom the coupon needs to be reissued
code Coupon code that you want to issue to the customer

Redeem Coupon

# Sample Request
http://api.capillary.co.in/v1.1/coupon/redeem?format=json

Sample POST Request

{
  "root": {
    "coupon": [{
      "code": "06000041",
      "customer": { 
      "mobile": "447700900000",
      "email": "",
      "external_id": "",
      "card_number": ""
      },
      "custom_fields": {
        "field": [{
          "name": "Sport",
          "value": "Soccer"
        },
        {
           "name": "custom_field2",
           "value": "50"
          }
          ]
      },
      "transaction": [{
        "number": "bill-110",
        "amount": "1000"
      }]
    }]
  } 
}
<root>
<coupon>
<code>06000041</code>
<customer>
<mobile>447700900000</mobile>
<email></email>
<external_id></external_id>
<card_number></card_number>
</customer>
<custom_fields>
<!-- Optional, as Specified by the Brand -->
<field>
    <name>Sport</name>
    <value>Soccer</value>
</field>
</custom_fields>
<redemption_time></redemption_time>
<transaction>
<number>bill-110</number>
<amount>1000</amount>
</transaction>
</coupon>
</root>

Sample Response


{
   "status": {
      "success": "true",
      "code": "200",
      "message": "Success"
   },
   "coupons": {
      "coupon": {
         "customer": {
            "mobile": "447700900000",
            "email": "tom.sawyer@example.com",
            "external_id": "ext_id7342762947"
         },
         "redemptionId": "4577842",
         "code": "P7WNQWF4",
         "discount_code": "XYZ123",
         "series_code": "9076",
         "series_info": [],
         "is_absolute": "false",
         "coupon_value": "10",
         "transaction": {
            "amount": "1000.00",
            "number": "numbr7342762947"
         },
         "side_effects": [],
         "item_status": {
            "success": "true",
            "code": "700",
            "message": "Coupon processing successful"
         }
      }
   }
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
   <status>
      <success>true</success>
      <code>200</code>
      <message>Success</message>
   </status>
   <coupons>
      <coupon>
         <customer>
            <mobile>447700900000</mobile>
            <email>tom.sawyer@example.com</email>
            <external_id>ext_id7342762947</external_id>
         </customer>
         <redemptionId>4577842</redemptionId>
         <code>P7WNQWF4</code>
         <discount_code>XYZ123</discount_code>
         <series_code>9076</series_code>
         <series_info />
         <is_absolute>false</is_absolute>
         <coupon_value>10</coupon_value>
         <transaction>
            <amount>1000.00</amount>
            <number>numbr7342762947</number>
         </transaction>
         <side_effects />
         <item_status>
            <success>true</success>
            <code>700</code>
            <message>Coupon processing successful</message>
         </item_status>
      </coupon>
   </coupons>
</response>

This API allows you to redeem coupons issued to the loyalty customer.

Resource Information

URI coupon/redeem
Rate Limited? Yes
Authentication Yes
HTTP Method POST
Batch Support No

Request URL

http://{host}/v1.1/coupon/redeem?{identifierName}={identifierValue}&format={xml/json}

Request Body Parameters

Parameter Datatype Description
identifierName* enum Any registered identifier type. Value: mobile, email, external_id, id.
identifierValue* string Registered identifier value of the customer. For example, id={customerId}
id long Coupon id that needs to be redeemed.
code string Coupon code that need to be redeemed.
validation_code string Validation code is required for the orgs that use validation based redemption.
number string Transaction number against which the coupon needs to be redeemed.
amount double Transaction amount against which the coupon is redeemed.
custom_fields obj Coupon redemption level custom fields.
name string Name of the custom field.
value string Custom field value.

Get Coupon Details

Sample Request

http://api.capillary.co.in/v1.1/coupon/get?code=06000041&format=xml

Sample Response

{
  "response": {
    "status": {
      "success": "true",
      "code": "200",
      "message": "SUCCESS"
    },
    "coupons": {
      "coupon": {
        "code": "06000041",
        "id": "13596576",
        "valid_till": "31-08-2016",
        "issued_on": "2016-08-01 15:31:44",
        "customer": {
          "user_id": "553232",
          "name": "Suresh Venkitakrishnan",
          "mobile": "919591525725",
          "email": "sv@mail.com"
        },
        "pincode": "224",
        "issued_store": {
          "code": "store.code",
          "name": "store name"
        },
        "series_id": "24325",
        "is_absolute": "true",
        "value": "0",
        "redemption_info": {
          "redeemed": "true",
          "redeemed_on": "2016-08-01 15:56:07",
          "redeemed_at": "till.fitnesse"
        },
        "redeemed_by": {
          "firstname": "TOM",
          "lastname": "Sawyer",
          "email": "tom@email.com",
          "mobile": "919999999999"
        },
        "store": {
          "code": "code.store",
          "name": "name.store"
        },
        "transaction": {
          "number": "BILL-20304",
          "id": "2242536"
        },
        "item_status": {
          "status": "true",
          "code": "700",
          "message": "Coupon processing successful"
        }
      }
    }
  }
}
<response>  
<status>    
<success>true</success>    
<code>200</code>    
<message>SUCCESS</message>  
</status>  
<coupons>    
<coupon>      
<code>06000041</code>      
<id>13596576</id>      
<valid_till>31-08-2016</valid_till>      
<issued_on>2016-08-01 15:31:44</issued_on>      
<customer>
    <user_id>553232</user_id>
<!-- user_id tag will be returned only if query param user_id = true -->
<name>Suresh Venkitakrishnan</name>        
<mobile>919591525725</mobile>        
<email>sv@mail.com</email>      
</customer>      
<pincode>224</pincode>
<issued_store>
    <code>store.code</code>
    <name>store name</name>
</issued_store>
<series_id>24325</series_id>
<is_absolute>true</is_absolute>      
<value>0</value>      
<redemption_info>        
<redeemed>true</redeemed>        
<redeemed_on>2016-08-01 15:56:07</redeemed_on>        
<redeemed_at>till.fitnesse</redeemed_at>      
</redemption_info>      
<redeemed_by>
    <firstname>TOM</firstname>
    <lastname>Sawyer</lastname>
    <email>tom@email.com</email>
    <mobile>919999999999</mobile>
</redeemed_by>
<store>
    <code>code.store</code>
    <name>name.store</name>
</store>
<transaction>
    <number>BILL-20304</number>
    <id>2242536</id>
</transaction>
<item_status>        
<status>true</status>        
<code>700</code>        
<message>Coupon processing successful</message>      
</item_status>    
</coupon>  
</coupons>
</response>

This API allows you to retrieve the details of a specific coupon. You can get information such as coupon issued to, current coupon status, coupon redeemed date, and coupon validity.

Resource Information

URI coupon/get
Rate Limited? Yes
Authentication Yes
HTTP Method GET
Batch Support Yes

Request URL

http://{host}/v1.1/coupon/get?{query_params}={paramValue}&format={xml/json}

Request Query Parameters

Parameter Datatype Description
id** long Pass the coupon id that you want to retrieve. To retrieve details of multiple coupons, pass each id separating with , (comma)
code** string Pass the coupon id that you want to retrieve. To retrieve details of multiple coupons, pass each code separating with , (comma).

Check if Coupon is Redeemable

Sample Request

http://us.intouch.capillarytech.com/v1.1/coupon/isredeemable?format=xml&details=true&code=06000041&mobile=447700900000

Sample Response

{
  "response": {
    "status": {
      "success": "true",
      "code": "200",
      "message": "SUCCESS"
    },
    "coupons": {
      "redeemable": {
        "mobile": "447700900000",
        "code": "06000041",
        "is_redeemable": "false",
        "item_status": {
          "status": "true",
          "code": "706",
          "message": "Cannot redeem same voucher multiple times"
        },
        "series_info": {
          "description": "Sample description",
          "discount_code": "XYZ123",
          "valid_till": "2016-12-31",
          "discount_type": "ABS",
          "discount_value": "0",
          "detailed_info": "sample details"
        }
      }
    }
  }
}
<response>  
<status>    
<success>true</success>    
<code>200</code>    
<message>SUCCESS</message>  
</status>  
<coupons>    
<redeemable>      
<mobile>447700900000</mobile>      
<code>06000041</code>      
<is_redeemable>false</is_redeemable>      
<item_status>        
<status>true</status>        
<code>706</code>        
<message>
Cannot redeem same voucher multiple times
</message>      
</item_status>      
<series_info>    

<description>Sample description</description>        
<discount_code>XYZ123</discount_code>        
<valid_till>2016-12-31</valid_till>        
<discount_type>ABS</discount_type>        
<discount_value>0</discount_value>        
<discount_on></discount_on>        
<detailed_info>sample details</detailed_info>      
</series_info>    
</redeemable>  
</coupons>
</response>

This API allows you to verify whether a coupon is redeemable by a specific customer.

Resource Information

URI coupon/isredeemable
Rate Limited? Yes
Authentication Yes
HTTP Method GET
Batch Support No

Request URL

http://{host}/v1.1/coupon/isredeemable?{identifierName}={identifierValue}&code={coupon_code}&{details=true}&format={xml/json}

Request Query Parameters

Parameter Datatype Description
identifierName* enum Pass any of the registered identifier names of the customer. Values: mobile, email, external_id, id, card_number.
value* string Pass the respective identifier value of the customer whose coupon has to be verified for redemption.
value* string Pass the respective identifier value of the customer whose coupon has to be verified for redemption.
code* string Pass the coupon code that you want to check
details=true - Retrieves the details of the coupon series.
details=extended - Retrieves the details of coupon configurations (set on campaign) of that specific coupon series.

Retrieve Coupon Series Details

Sample Request

http://us.intouch.capillarytech.com/v1.1/coupon/series?format=json&id=7033

Sample Response

{
  "response": {
    "status": {
      "success": "true",
      "code": "200",
      "message": "Success"
    },
    "series": {
      "items": {
        "item": {
          "id": "405",
          "description": "API Coupon 3",
          "series_type": "CAMPAIGN",
          "client_handling_type": "DISC_CODE",
          "discount_code": "XYZ123",
          "valid_till_date": "2017-12-31",
          "valid_days_from_create": "30",
          "expiry_strategy_type": "DAYS",
          "expiry_strategy_value": "30",
          "max_create": "-1",
          "max_redeem": "-1",
          "transferrable": "0",
          "any_user": "0",
          "same_user_multiple_redeem": "0",
          "allow_referral_existing_users": "0",
          "multiple_use": "0",
          "is_validation_required": "0",
          "valid_with_discounted_item": "false",
          "created_by": "4",
          "created": "2016-12-09 08:35:15",
          "last_used": "2016-12-09 08:35:15",
          "series_code": "G8Z08NZL",
          "disable_sms": "0",
          "info": "API Coupon 3",
          "allow_multiple_vouchers_per_user": "1",
          "do_not_resend_existing_voucher": "0",
          "mutual_exclusive_series_ids": "[-1]",
          "store_ids_json": "[-1]",
          "dvs_enabled": "0",
          "dvs_expiry_date": "2017-01-09",
          "priority": "0",
          "short_sms_template": "Hello {{cust_name}}, your voucher code is {{voucher_code}}",
          "max_vouchers_per_user": "-1",
          "min_days_between_vouchers": "-1",
          "max_referrals_per_referee": "-1",
          "discount_on": "BILL",
          "discount_type": "PERC",
          "discount_value": "10",
          "redemption_range": "{\"dom\":[\"-1\"],\"dow\":[\"-1\"],\"hours\":[\"-1\"]}",
          "min_bill_amount": "0",
          "max_bill_amount": "0",
          "redeem_at_store": "[-1]",
          "campaign_id": "458",
          "max_redemptions_in_series_per_user": "-1",
          "min_days_between_redemption": "-1",
          "redemption_valid_from": "2014-04-30",
          "source_org_id": "-1",
          "issue_to_loyalty": "0",
          "redeem_store_type": "redeemable_stores",
          "old_flow_enabled": "0",
          "pre_redeem_event_required": "0",
          "coupons": {
            "issued": "4558",
            "redeemed": "924"
          },
          "offline_redemption_enabled": "true",
          "item_status": {
            "success": "true",
            "code": "700",
            "message": "Coupon series fetched successfully"
          },
          "valid_redemption_org_entities":{
              "concepts":null,

              "zones":null,

              "stores":null,

              "tills":"[12808452]"
          },
          "products": "",
          "brands": "",
          "categories": ""
        }
      }
    }
  }
}


<?xml version="1.0" encoding="UTF-8"?>
<response>
   <status>
      <success>true</success>
      <code>200</code>
      <message>Success</message>
   </status>
   <series>
      <items>
         <item>
            <id>405</id>
            <description>API Coupon 3</description>
            <series_type>CAMPAIGN</series_type>
            <client_handling_type>DISC_CODE</client_handling_type>
            <discount_code>XYZ123</discount_code>
            <valid_till_date>2017-12-31</valid_till_date>
            <valid_days_from_create>30</valid_days_from_create>
            <expiry_strategy_type>DAYS</expiry_strategy_type>
            <expiry_strategy_value>30</expiry_strategy_value>
            <max_create>-1</max_create>
            <max_redeem>-1</max_redeem>
            <transferrable>0</transferrable>
            <any_user>0</any_user>
            <same_user_multiple_redeem>0</same_user_multiple_redeem>
            <allow_referral_existing_users>0</allow_referral_existing_users>
            <multiple_use>0</multiple_use>
            <is_validation_required>0</is_validation_required>
            <valid_with_discounted_item>false</valid_with_discounted_item>
            <created_by>4</created_by>
            <created>2016-12-09 08:35:15</created>
            <last_used>2016-12-09 08:35:15</last_used>
            <series_code>G8Z08NZL</series_code>
            <sms_template />
            <disable_sms>0</disable_sms>
            <info>API Coupon 3</info>
            <allow_multiple_vouchers_per_user>1</allow_multiple_vouchers_per_user>
            <do_not_resend_existing_voucher>0</do_not_resend_existing_voucher>
            <mutual_exclusive_series_ids>[-1]</mutual_exclusive_series_ids>
            <store_ids_json>[-1]</store_ids_json>
            <dvs_enabled>0</dvs_enabled>
            <dvs_expiry_date>2017-01-09</dvs_expiry_date>
            <priority>0</priority>
            <short_sms_template>Hello {{cust_name}}, your voucher code is {{voucher_code}}</short_sms_template>
            <max_vouchers_per_user>-1</max_vouchers_per_user>
            <min_days_between_vouchers>-1</min_days_between_vouchers>
            <max_referrals_per_referee>-1</max_referrals_per_referee>
            <discount_on>BILL</discount_on>
            <discount_type>PERC</discount_type>
            <discount_value>10</discount_value>
            <dvs_items />
            <redemption_range>{&amp;quot;dom&amp;quot;:[&amp;quot;-1&amp;quot;],&amp;quot;dow&amp;quot;:[&amp;quot;-1&amp;quot;],&amp;quot;hours&amp;quot;:[&amp;quot;-1&amp;quot;]}</redemption_range>
            <min_bill_amount>0</min_bill_amount>
            <max_bill_amount>0</max_bill_amount>
            <redeem_at_store>[-1]</redeem_at_store>
            <campaign_id>458</campaign_id>
            <tag />
            <max_redemptions_in_series_per_user>-1</max_redemptions_in_series_per_user>
            <min_days_between_redemption>-1</min_days_between_redemption>
            <redemption_valid_from>2014-04-30</redemption_valid_from>
            <source_org_id>-1</source_org_id>
            <issue_to_loyalty>0</issue_to_loyalty>
            <redeem_store_type>redeemable_stores</redeem_store_type>
            <old_flow_enabled>0</old_flow_enabled>
            <pre_redeem_event_required>0</pre_redeem_event_required>
            <coupons>
               <issued>4558</issued>
               <redeemed>924</redeemed>
            </coupons>
            <offline_redemption_enabled>true</offline_redemption_enabled>
            <campaign_name />
            <purpose/>
            <metadata/>
            <valid_redemption_org_entities>
                <concepts>[12808430,12808431]</concepts>
                <stores null="true" />
                <tills>
                <element>12808452</element>
                </tills>
                <zones null="true" />
            </valid_redemption_org_entities>
            <item_status>
               <success>true</success>
               <code>700</code>
               <message>Coupon series fetched successfully</message>
            </item_status>
            <products />
            <brands />
            <categories />
         </item>
      </items>
   </series>
</response>

This API retrieves the details of a specific series of a campaign based on the series id passed. If no series id is passed, all coupon series details are retrieved.

Resource Information

URI coupon/series
Rate Limited? Yes
HTTP Method GET
Authentication Yes
Batch Support Yes

Request URL

http://{host}/v1.1/coupon/series?format={xml/json}&id={series_id}&expired={true/false/extended}

Request Query Parameters

Parameter Datatype Description
id* long Unique ID of the specific coupon series that you want to retrieve.
expired enum Retrieves the details of the expired coupon series if expired=true and active coupon series details if expired=false. To also include coupon configuration details, pass expired=extended.

Response Codes

Success Codes

Code Description
700 Coupon processed successfully
700 Coupon series fetched successfully

Error Codes

Code Description
701 Unable to find the customer. Please enter correct mobile number/email id/external id
702 Coupon code is invalid
703 Coupon not issued to this customer
704 Unable to send coupon to the customer’s mobile number
705 Invalid coupon code and validation code
706 Unable to redeem coupon
707 Coupon series id is invalid
709 Unable to redeem coupon
710 Coupon cannot be redeemed by this customer
711 Coupon is redeemed already
712 Unable to redeem. Either coupon series or campaign might have expired
713 Coupon has expired
714 Unable to redeem. Maximum redemptions allowed for this campaign are already reached
715 Unable to redeem. The coupon is not valid for this organization
716 Unable to redeem. Cannot redeem same coupon multiple times
718 Unable to redeem. Please enter transaction number must be entered to redeem
719 Coupon code does not exist
720 Unable to redeem. This is just a trial coupon and cannot be redeemed
721 Unable to issue/redeem coupon. Customer is invalid
722 Unable to issue coupon
723 Unable to redeem. The coupon cannot be used by this customer
724 Unable to send message
725 Unable to redeem coupon. Please provide validation code to redeem
726 Validation not required
728 Unable to redeem. Maximum number of coupon redemptions allowed has already been reached
729 Invalid redemption date range for the coupon series
730 Unknown error
732 No Missed call received from the customer
733 Transaction amount invalid
735 Unable to redeem coupon. The coupon cannot be redeemed at this store
736 Unable to redeem coupon. Maximum number of coupon redemptions allowed has already been reached
738 Cannot redeem the coupon. Please wait for days to redeem this coupon again
739 Unable to redeem. Make sure that the redemption date you have entered is valid
740 Unable to process. Customer is marked as fraud
742 Coupon issual or redemption is blocked for this customer
750 Unable to process. Customer is marked as fraud
786 Unable to process coupon. Please try again later
787 Unable to process coupon. Please try again later
788 Configuration is invalid. Please report to Capillary Support
789 Unable to process coupon. Please try again later
790 Unable to process coupon. Please try again later
791 Unable to process coupon. Please try again later
792 Unable to process coupon. Please try again later
793 Unable to process coupon. Please try again later
794 Unable to process coupon. Please try again later
795 Configuration is invalid. Please report to Capillary Support
796 Unable to process coupon. Please try again later
797 Unable to process coupon. Please try again later
798 Unable to process coupon. Please try again later
799 Configuration is invalid. Please report to Capillary Support

Communications

Communications represent personalized messages (SMSs/emails) sent to the loyalty customers. Messages such as transaction notifications, birthday wishes, anniversary wishes can be sent through communications APIs.

The communications entity stores personalized messages, and message templates, To send messages the communication gate way should be enabled for your organization with enough message credits.

The communications entity allows you to perform the following tasks:

Send SMS to Customer

# Sample Request URL
http://us.api.capillarytech.com/v1.1/communications/sms?format=json

Sample POST Request

{
  "root": {
    "sms": [{
      "to": "447700900000",
      "body": "Hi, wish you a happy wedding anniversary!",
      "scheduled_time": "2012-08-05 22:00:00IST"
    }]
  }
}
<root>
   <sms>
      <to>447700900000</to>
      <body>Hi, wish you a happy wedding anniversary!</body>
      <scheduled_time>2012-08-05 22:00:00IST</scheduled_time>
   </sms>
</root>

Sample Response

{
  "response": {
    "status": {
      "success": "true",
      "code": "200",
      "message": "success"
    },
    "sms": {
      "id": "23423443",
      "to": "447700900000",
      "status": "Sent",
      "scheduled_time": "2012-08-05 22:00:00IST"
    }
  }
}
<?xml version="1.0" encoding="UTF-8"?>        
<response>
    <status>
        <success>true</success>
        <code>200</code>
        <message>success</message>
    </status>
    <sms>
        <id>23423443</id>
        <to>447700900000</to>        
        <status>Sent</status>
        <scheduled_time>2012-08-05 22:00:00IST</scheduled_time>
</sms>    
</response>

This API allows you to send sms to a specific mobile number. You can schedule the date and time you wish to send the message.

Resource Information

URI /sms
Authentication Yes
HTTP Methods POST
Batch Support No

Request URL

http://{host}/v1.1/communications/sms?format={xml/json}

Send Email to Customer

# Sample Request URL
http://us.api.capillarytech.com/v1.1/communications/email?format=json

Sample POST Request

{
  "root": {
    "email": [{
      "to": "tom.sawyer@example.com",
      "cc": "cashier1@example.com, cashier2@example.com",
      "bcc": "storemanager@example.com",
      "from": "store1@store.com",
      "#text": "  -- optional
        ",
      "subject": "Testing email",
      "body": "Dear Tom,
            Thanks for visiting our store. Hope you had a pleasant experience.

        ",
      "attachments": {
        "attachment": [{
          "file_name": "sample.pdf",
          "file_type": "pdf",
          "file_data": "  -- base64_encoded file contents
                adsdsadd21121dasd12123123assdad1212123
                234234234234234234
                24234234

            "
        }]
      },
      "scheduled_time": "2016-08-05 22:00:21"
    }
  ]
  }
}
<?xml version="1.0" encoding="UTF-8"?>        
<root>
    <email>
        <to>tom.sawyer@example.com</to>
        <cc>cashier1@example.com, cashier2@example.com</cc>
        <bcc>storemanager@example.com</bcc>
        <from>store1@store.com</from>  -- optional
        <subject><![CDATA[Testing email]]></subject>
        <body><![CDATA[Dear Tom,
            Thanks for visiting our store. Hope you had a pleasant experience.
            ]]>
        </body>    
        <attachments>
            <attachment>
            <file_name>sample.pdf</file_name>
            <file_type>pdf</file_type>
            <file_data><![CDATA[  -- base64_encoded file contents
                adsdsadd21121dasd12123123assdad1212123
                234234234234234234
                24234234
                ]]>
            </file_data>    
        </attachment>    
        </attachments>
        <scheduled_time>2016-08-05 22:00:21</scheduled_time>
    </email>    
      </root>            

Sample Response

{
  "response": {
    "status": {
      "success": "true",
      "code": "200",
      "message": "success"
    },
    "email": {
      "id": "23423443",
      "to": "tom.sawyer@example.com",
      "cc": "cashier1@example.com, cashier2@example.com",
      "bcc": "storemanager@example.com",
      "status": "Queued",
      "subject": "Sample email",
      "description": "Dear Tom,
            Thanks for the treat. Looking forward to more treats",
      "scheduled_time": "2016-08-05 22:00::IST"
    }
  }
}
<?xml version="1.0" encoding="UTF-8"?>        
<response>
    <status>
        <success>true</success>
        <code>200</code>
        <message>success</message>
    </status>
    <email>
        <id>23423443</id>
        <to>tom.sawyer@example.com</to>
            <cc>cashier1@example.com, cashier2@example.com</cc>
        <bcc>storemanager@example.com</bcc>
        <status>Queued</status>
        <subject>Sample email</subject>
        <description>Dear Tom,
            Thanks for the treat. Looking forward to more treats</description>
        <scheduled_time>2016-08-05 22:00::IST</scheduled_time>
     </email>    
</response>

This API allows you to send email to a specific email id. You can schedule the date and time you wish to send the message.

Resource Information

URI /email
Authentication Yes
HTTP Methods POST
Batch Support No

Request URL

http://{host}/v1.1/communications/email?format={xml/json}

Retrieve Details of Emails Sent

# Sample Request
http://us.api.capillarytech.com/v1.1/communications/email?format=xml&id=2342344

Sample Response

<?xml version="1.0" encoding="UTF-8"?>        
<response>
    <status>
        <success>true</success>
        <code>200</code>
        <message>success</message>
    </status>
    <email>
        <id>2342344</id>
        <to>piyush.goel@example.com</to>
        <cc>joe@example.com, jim@example.com</cc>    
<subject>Test Email</subject>
<description>This is body of the email sent</description>
        <status>Delivered</status>
        <sent_time>2016-08-05 22:00::IST</sent_time>
</email>    
</response>

{
  "response": {
    "status": {
      "success": "true",
      "code": "200",
      "message": "success"
    },
    "email": {
      "id": "2342344",
      "to": "piyush.goel@example.com",
      "cc": "joe@example.com, jim@example.com",
      "subject": "Test Email",
      "description": "This is body of the email sent",
      "status": "Delivered",
      "sent_time": "2016-08-05 22:00::IST"
    }
  }
}

Returns the details of a specific sent email based on the message id you pass.

Resource Information

URI /email
Authentication Yes
HTTP Methods GET
Batch Support No

Request URL

http://{host}/v1.1/communications/email?format={xml/json}&id={id}

Request Parameters

id* - Pass the message id generated of the sent message.

Retrieve Details of SMSs Sent

# Sample Request
http://us.api.capillarytech.com/v1.1/communications/sms?format=xml&id=23423443

Sample Response

<?xml version="1.0" encoding="UTF-8"?>        
<response>
    <status>
        <success>true</success>
        <code>200</code>
        <message>success</message>
    </status>
    <sms>
        <id>23423443</id>
        <to>919980616xxx</to>        
        <status>Sent</status>
        <scheduled_time>2016-08-05 22:00:00IST</scheduled_time>
        <message>Sample message</message>
        <sender>test sender</sender>
</sms>    
</response>
{
  "response": {
    "status": {
      "success": "true",
      "code": "200",
      "message": "success"
    },
    "sms": {
      "id": "23423443",
      "to": "919980616xxx",
      "status": "Sent",
      "scheduled_time": "2016-08-05 22:00:00IST",
      "message": "Sample message",
      "sender": "test sender"
    }
  }
}

Returns the details of a specific sent SMS based on the message id you pass.

Resource Information

URI /sms
Authentication Yes
HTTP Methods GET
Batch Support No

Request URL

http://{host}/v1.1/communications/sms?format=<xml/json>&<parameters>

Request Parameters

id* - Pass the unique id of the message that you want to retrieve

Response Codes

Success Codes

Code Description
4100 Message sent successfully
Message fetched successfully
Template added/updated successfully
4200 Email sent successfully / Email fetched successfully

Error Codes

CODE DESCRIPTION
4101 Unable to send message
4201 Unable to send email
4102 Unable to find/retrieve SMS
4202 Unable to find/retrieve email
4203 Invalid template type passed
4204 Template not found
4205 Unable to update the template
4206 Invalid template id passed
4207 No template is available with the given parameters
4208 Invalid email id

Request

Request entity contains APIs corresponding to submitting and retrieving requests. In Capillary APIs, requests are of two types - Change Identifier and Goodwill. Request APIs allow you to change customer identifiers, merge customer accounts, issue Goodwill points/coupons, and retrieve details of submitted requests.

Add Request (Identifier Change)

Sample Request

http://us.api.capillarytech.com/v1.1/request/add

Sample POST Request

<root>
<request>
    <reference_id>1234</reference_id>
    <type>CHANGE_IDENTIFIER</type>
    <base_type>EMAIL</base_type>
    <customer>
        <email>Tom.sawyerold@example.com</email>
        <mobile>44700900000</mobile>
        <external_id>ts1234</external_id>
        <id>395958</id>
    </customer>
    <old_value>Tom.sawyerold@example.com</old_value>
    <new_value>Tom.sawyer@example.com</new_value>
    <requested_on>time in 8601</requested_on>
</request>
</root>

{
  "root": {
    "request": [{
      "reference_id": "1234",
      "type": "CHANGE_IDENTIFIER",
      "base_type": "EMAIL",
      "customer": {
        "email": "Tom.sawyerold@example.com",
        "mobile": "44700900000",
        "external_id": "ts1234",
        "id": "395958"
      },
      "old_value": "Tom.sawyerold@example.com",
      "new_value": "Tom.sawyer@example.com",
      "requested_on": "time in 8601"
    }]
  }
}

Sample Response

<response>
<status>
<success>true</success>
<code>200</code>
<message>SUCCESS</message>
</status>
<requests>
    <request>
<reference_id>1234</reference_id>
<id>23123124</id>
<status>PENDING</status>
<type>CHANGE_IDENTIFIER</type>
<base_type>MOBILE</base_type>
<customer>
<firstname>Tom</firstname>
<lastname>Sawyer</lastname>
<email>tom.sawyerold@example.com</email>
<mobile>44700900000</mobile>
<external_id>ts1234</external_id>
<id>10423</id>
</customer>
<old_value>tom.sawyerold@example.com</old_value>
<new_value>Tom.sawyer@example.com</new_value>
<item_status>
<success>true</success>
<code>9000</code>
<message>Change Identifier request added successfully</message>
</item_status>
</request>
</requests>
</response>
{
  "response": {
    "status": {
      "success": "true",
      "code": "200",
      "message": "SUCCESS"
    },
    "requests": {
      "request": {
        "reference_id": "1234",
        "id": "23123124",
        "status": "PENDING",
        "type": "CHANGE_IDENTIFIER",
        "base_type": "MOBILE",
        "customer": {
          "firstname": "Tom",
          "lastname": "Sawyer",
          "email": "tom.sawyerold@example.com",
          "mobile": "44700900000",
          "external_id": "ts1234",
          "id": "10423"
        },
        "old_value": "tom.sawyerold@example.com",
        "new_value": "Tom.sawyer@example.com",
        "item_status": {
          "success": "true",
          "code": "9000",
          "message": "Change Identifier request added successfully"
        }
      }
    }
  }
}

Lets you submit requests for customer identifier changes. It could be either mobile number, email ID, or external ID.

Requests, when submitted, will be in pending status by default. Capillary back-end team verifies the request and could either approves or rejects it. The request/add API allows you to directly process a request by passing a query param client_auto_approve=true.

If client_auto_approve=true, the request will be created in pending status by default and then processed automatically.

However, requests can be approved automatically based on the following configs set on Member Care.

Config Description
CI_EMAIL_AUTO_APPROVE Approves email id change requests automatically
CI_MOBILE_AUTO_APPROVE Approves mobile number change requests automatically
CI_EXTID_AUTO_APPROVE Approves external id change requests automatically
CI_ADDRESS_AUTO_APPROVE Approves registered address change requests automatically

Resource Information

URI request/add
Authentication Yes
HTTP Methods POST
Batch Support Yes

Request URL

http://{host}/v1.1/request/add&format={xml/json}

Request Query Parameters

Parameter Datatype Description
client_auto_approve boolean If the value is true, approves request directly when the request is submitted. This even overrides the back-end configurations set on Member Care. Hence, highly recommended not to use in normal cases
is_one_step_change boolean Pass true for one step identifier change.

Request Body Parameters

Parameter Datatype Description
mobile/email/external_id/id* string Pass any of the identifiers of the customer with the identifier value.
reference_id* long Unique reference id for the request
type enum Type of request. Value:CHANGE_IDENTIFIER.
base_type enum Identifier that you want to update. Value: MOBILE, EMAIL, EXTERNAL_ID.
old_value string The current value of the customer identifier.
new_value string The new value of the customer identifier.

Response Parameters

Parameter Datatype Description
reference_id string Unique reference ID of the request.
id long Unique ID generated for the request.
status enum Current status of the request. Values: PENDING, APPROVED, REJECTED.
customer obj Details of the customer details associated to the request.

Add Request (Mobile Number Reallocation)

Sample Request

http://us.api.capillarytech.com/v1.1/request/add

Sample POST Request

<?xml version="1.0" encoding="UTF-8"?>
<root>
   <root>
      <request>
         <element>
            <base_type>MOBILE_REALLOC</base_type>
            <customer>
               <email />
               <external_id />
               <mobile>919011111111</mobile>
            </customer>
            <misc_info>
               <target_customer>
                  <email />
                  <external_id />
                  <id />
                  <mobile>9818012000</mobile>
               </target_customer>
            </misc_info>
            <new_value />
            <old_value>919011111111</old_value>
            <type>CHANGE_IDENTIFIER</type>
         </element>
      </request>
   </root>
</root>
{ 
   "root":{ 
      "request":[ 
         { 
            "customer":{ 
               "mobile":"919011111111",
               "external_id":"",
               "email":""
            },
            "old_value":"919011111111",
            "base_type":"MOBILE_REALLOC",
            "new_value":"",
            "type":"CHANGE_IDENTIFIER",
            "misc_info":{ 
               "target_customer":{ 
                  "mobile":"9818012000",
                  "external_id":"",
                  "email":" ",
                  "id":""
               }
            }
         }
      ]
   }
}

Sample Response

<?xml version="1.0" encoding="UTF-8"?>
<root>
   <response>
      <requests>
         <request>
            <element>
               <base_type>MOBILE_REALLOC</base_type>
               <comments />
               <customer>
                  <email>rita.john@example.com</email>
                  <external_id>XYPZ006</external_id>
                  <firstname>Rita</firstname>
                  <id>343439221</id>
                  <lastname>John</lastname>
                  <mobile>919011111111</mobile>
               </customer>
               <id>789849</id>
               <item_status>
                  <code>9000</code>
                  <message>Change Identifier request added successfully</message>
                  <success>true</success>
               </item_status>
               <misc_info null="true" />
               <new_type />
               <new_value>343490735</new_value>
               <old_type />
               <old_value>343439221</old_value>
               <reason />
               <reference_id null="true" />
               <requested_on>2020-01-02 12:02:29</requested_on>
               <status>PENDING</status>
               <transaction_id>0</transaction_id>
               <type>CHANGE_IDENTIFIER</type>
            </element>
         </request>
      </requests>
      <status>
         <code>200</code>
         <message>Success</message>
         <success>true</success>
      </status>
   </response>
</root>
{
   "response":{
      "status":{
         "success":true,
         "code":200,
         "message":"Success"
      },
      "requests":{
         "request":[
            {
               "reference_id":null,
               "id":"789849",
               "status":"PENDING",
               "requested_on":"2020-01-02 12:02:29",
               "type":"CHANGE_IDENTIFIER",
               "base_type":"MOBILE_REALLOC",
               "customer":{
                  "firstname":"Rita",
                  "lastname":"John",
                  "email":"rita.john@example.com",
                  "mobile":"919011111111",
                  "external_id":"XYPZ006",
                  "id":343439221
               },
               "old_value":"343439221",
               "new_value":"343490735",
               "old_type":"",
               "new_type":"",
               "misc_info":null,
               "transaction_id":"0",
               "reason":"",
               "comments":"",
               "item_status":{
                  "success":true,
                  "code":9000,
                  "message":"Change Identifier request added successfully"
               }
            }
         ]
      }
   }
}

Lets you submit mobile number reallocation requests. You can reallocate only registered mobile numbers.

Requests, when submitted, will go in pending status by default. Capillary back-end team verifies the request and could either approves or rejects it. The request/add API allows you to directly process a request by passing a query param client_auto_approve=true.

If client_auto_approve=true, the request will be created in pending status by default and then processed automatically.

However, requests can be approved automatically based on the following configs set on Member Care.

Config Description
CI_MOBILEREALLOC_AUTO_APPROVE Approves mobile number reallocation requests automatically

Resource Information

URI request/add
Authentication Yes
HTTP Methods POST
Batch Support Yes

Request URL

http://{host}/v1.1/request/add&format={xml/json}

Request Query Parameters

Parameter Datatype Description
client_auto_approve boolean If the value is true, the request is approved directly. This even overrides the back-end configurations set on Member Care. Hence, we strictly recommended not to use in normal cases
is_one_step_change boolean Pass true for one step identifier change.

Request Body Parameters

Parameter Datatype Description
customer obj Details of source account.
target_customer obj Details of target account.
mobile/email/external_id/id* string Pass any of the identifiers of the customer with the identifier value.
old_value string The mobile number of the source customer that has to reassign to the target customer.
type enum Type of request. Value: CHANGE_IDENTIFIER.
base_type enum Sub-type of the request. Value: MOBILE_REALLOC.

Response Parameters

Parameter Datatype Description
requested_on date-time Date and time when the request is created.
id long Unique ID generated for the request.
status enum Current status of the request. Value: PENDING, APPROVED, REJECTED. The status will be APPROVED if mobile number reallocation (CI_MOBILEREALLOC_AUTO_APPROVE) is auto approved either on the UI or through API (client_auto_approve).
customer obj Updated details of the target customer.

Add Request (Merge Accounts)

Sample Request

http://us.api.capillarytech.com/v1.1/request/add

Sample POST Request

<?xml version="1.0" encoding="UTF-8" ?>
<root>
  <request>
    <customer>
      <mobile></mobile>
      <external_id></external_id>
      <email>tom739@capillarytech.com</email>
      <id></id>
    </customer>
    <old_value></old_value>
    <base_type>MERGE</base_type>
    <new_value></new_value>
    <type>CHANGE_IDENTIFIER</type>
    <misc_info>
      <target_customer>
        <mobile></mobile>
        <external_id></external_id>
        <email></email>
        <id>342979941</id>
      </target_customer>
    </misc_info>
  </request>
</root>
{
   "root":{
      "request":[
         {
            "customer":{
               "mobile":"",
               "external_id":"",
               "email":"tom739@capillarytech.com",
               "id":""
            },
            "old_value":"",
            "base_type":"MERGE",
            "new_value":"",
            "type":"CHANGE_IDENTIFIER",
            "misc_info":{
               "target_customer":{
                  "mobile":"",
                  "external_id":"",
                  "email":"",
                  "id":"342979941"
               }
            }
         }
      ]
   }
}

Sample Response

<?xml version="1.0" encoding="UTF-8" ?>
<response>
  <status>
    <success>true</success>
    <code>200</code>
    <message>Success</message>
  </status>
  <requests>
    <request>
      <reference_id/>
      <id>789186</id>
      <status>PENDING</status>
      <requested_on>2019-12-31 16:58:02</requested_on>
      <type>CHANGE_IDENTIFIER</type>
      <base_type>MERGE</base_type>
      <customer>
        <firstname>unknown739</firstname>
        <lastname/>
        <email>unknown739@capillarytech.com</email>
        <mobile>919901032739</mobile>
        <external_id/>
        <id>322393226</id>
      </customer>
      <old_value>322393226</old_value>
      <new_value>342979941</new_value>
      <old_type></old_type>
      <new_type></new_type>
      <misc_info/>
      <transaction_id>0</transaction_id>
      <reason></reason>
      <comments></comments>
      <item_status>
        <success>true</success>
        <code>9000</code>
        <message>Change Identifier request added successfully</message>
      </item_status>
    </request>
  </requests>
</response>
{
    "response": {
        "status": {
            "success": true,
            "code": 200,
            "message": "Success"
        },
        "requests": {
            "request": [
                {
                    "reference_id": null,
                    "id": "789186",
                    "status": "PENDING",
                    "requested_on": "2019-12-31 16:58:02",
                    "type": "CHANGE_IDENTIFIER",
                    "base_type": "MERGE",
                    "customer": {
                        "firstname": "unknown739",
                        "lastname": null,
                        "email": "unknown739@capillarytech.com",
                        "mobile": "919901032739",
                        "external_id": null,
                        "id": 322393226
                    },
                    "old_value": "322393226",
                    "new_value": "342979941",
                    "old_type": "",
                    "new_type": "",
                    "misc_info": null,
                    "transaction_id": "0",
                    "reason": "",
                    "comments": "",
                    "item_status": {
                        "success": true,
                        "code": 9000,
                        "message": "Change Identifier request added successfully"
                    }
                }
            ]
        }
    }
}

Lets you submit requests of merge accounts.

Requests, when submitted, will be in pending status by default. Capillary back-end team verifies the request and could either approves or rejects it. The request/add API allows you to directly process a request by passing a query param client_auto_approve=true.

If client_auto_approve=true, the request will be created in pending status by default and then processed automatically.

However, requests can be approved automatically based on the following configs set on Member Care.

Config Description
CI_MERGE_AUTO_APPROVE Approves customer accounts merge requests automatically

Resource Information

URI request/add
Authentication Yes
HTTP Methods POST
Batch Support Yes

Request URL

http://{host}/v1.1/request/add&format={xml/json}

Request Query Parameters

Parameter Datatype Description
client_auto_approve boolean If the value is true, approves request directly when the request is submitted. This even overrides the back-end configurations set on Member Care. Hence, highly recommended not to use in normal cases
is_one_step_change boolean Pass true for one step account merge.

Request Body Parameters

Parameter Datatype Description
customer obj Details of the victim account - the account that you want to merge into another account.
target_customer obj Details of the survivor account - the account that will continue to remain after merging.
mobile/email/external_id/id* string Pass any of the identifiers of the customer with the identifier value.
type enum Pass CHANGE_IDENTIFIER for merge requests.
base_type enum Sub-type of the request. Value: MERGE

Response Parameters

Parameter Datatype Description
requested_on date-time Date and time when the request is created in YYYY-MM-DD format

Add Request (Goodwill Points/Coupons)

Sample Request

http://us.api.capillarytech.com/v1.1/request/add?program_id=687

Sample POST Request

# For goodwill points
<root>
   <request>
      <customer>
         <id>2345</id>
         <mobile></mobile>
         <email></email>
         <external_id></external_id>
      </customer>
      <comments>API Service request - Awarding him 200 points.</comments>
      <reason>POINTS_ISSUE</reason>
      <type>GOODWILL</type>
      <base_type>POINTS</base_type>
      <points>200</points>
   </request>
</root>
# For points
{
  "root":{
    "request":[
      {
        "customer":{
          "id":"2345",
          "mobile":"",
          "email":"",
          "external_id":""
        },
        "comments":"API Service request - Awarding 200 points.",
        "reason":"Issue Goodwill points",
        "type":"GOODWILL",
        "base_type":"POINTS",
        "points":"200"
      }
    ]
  }
}
# For Goodwill Coupon
{
   "root":{
      "request":[
         {
            "customer":{
               "mobile":"919011111111",
               "external_id":"",
               "email":""
            },
            "reason":"Sample reason",
            "comments":"Additional comment if required",
            "type":"GOODWILL",
            "base_type":"COUPON",
            "series_id":"80197"
         }
      ]
   }
}
# For Goodwill Coupon
<?xml version="1.0" encoding="UTF-8"?>
<root>
   <root>
      <request>
         <element>
            <base_type>COUPON</base_type>
            <comments>Additional comment if required</comments>
            <customer>
               <email />
               <external_id />
               <mobile>919011111111</mobile>
            </customer>
            <reason>Sample reason</reason>
            <series_id>80197</series_id>
            <type>GOODWILL</type>
         </element>
      </request>
   </root>
</root>

Sample Response

<?xml version="1.0" encoding="UTF-8"?>
<root>
   <response>
      <requests>
         <request>
            <element>
               <base_type>POINTS</base_type>
               <comments />
               <customer>
                  <email>shigan@example.com</email>
                  <external_id>SG006</external_id>
                  <firstname>Shi</firstname>
                  <id>343490735</id>
                  <lastname>Gan</lastname>
                  <mobile>919011111111</mobile>
               </customer>
               <id>789850</id>
               <item_status>
                  <code>9100</code>
                  <message>Goodwill request added successfully</message>
                  <success>true</success>
               </item_status>
               <misc_info null="true" />
               <new_type />
               <new_value />
               <old_type />
               <old_value>919011111111</old_value>
               <reason />
               <reference_id null="true" />
               <requested_on>2020-01-02 13:13:38</requested_on>
               <status>PENDING</status>
               <transaction_id>0</transaction_id>
               <type>GOODWILL</type>
            </element>
         </request>
      </requests>
      <status>
         <code>200</code>
         <message>Success</message>
         <success>true</success>
      </status>
   </response>
</root>
{
    "response": {
        "status": {
            "success": true,
            "code": 200,
            "message": "Success"
        },
        "requests": {
            "request": [
                {
                    "reference_id": null,
                    "id": "789850",
                    "status": "PENDING",
                    "requested_on": "2020-01-02 13:13:38",
                    "type": "GOODWILL",
                    "base_type": "POINTS",
                    "customer": {
                        "firstname": "Shi",
                        "lastname": "Gan",
                        "email": "shigan@example.com",
                        "mobile": "919011111111",
                        "external_id": "SG006",
                        "id": 343490735
                    },
                    "old_value": "919011111111",
                    "new_value": "",
                    "old_type": "",
                    "new_type": "",
                    "misc_info": null,
                    "transaction_id": "0",
                    "reason": "",
                    "comments": "",
                    "item_status": {
                        "success": true,
                        "code": 9100,
                        "message": "Goodwill request added successfully"
                    }
                }
            ]
        }
    }
}

Lets you submit goodwill points or coupon allocation requests for loyalty customers.

Requests, when submitted, will go in pending status by default. Capillary back-end team verifies the request and could either approves or rejects it. The request/add API allows you to directly process a request by passing a query param client_auto_approve=true.

If client_auto_approve=true, the request will be created in pending status by default and then processed automatically.

Resource Information

URI request/add?{params}
Authentication Yes
HTTP Methods POST
Batch Support Yes

Request URL

`http://{host}/v1.1/request/add?{params}&format={xml/json

Request Query Parameters

Parameter Datatype Description
client_auto_approve boolean If the value is true, the request is approved directly. This even overrides the back-end configurations set on Member Care. Hence, highly recommended not to use in normal cases.
is_one_step_change boolean Pass true for one step identifier change.
program_id long The loyalty program ID from which you want to issue points. This is applicable if the org has multiple loyalty programs configured.

Request Body Parameters

Parameter Datatype Description
customer obj Details of the customer to whom you want to issue goodwill points or coupons.
mobile/email/external_id/id