NAV Navbar
Logo
json

Release Updates

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

Q2 Releases (2021-2022)

Q1 Releases (2021-2022)

Q4 Releases (2020-2021)

Releases (2020-2021)

Q3 Releases (2020-2021)

Following headers can be used to pass store or till identifiers.

Q2 Releases (2020-2021)

Releases (2019-2020)

Q4 Releases (2019-20)

Introduction

Capillary RESTful APIs are be consumed by Capillary and other brands that are registered with Capillary/MartJack to manage their CRM. Capillary V2 and V3 APIs support multiple sources such as InStore, MartJack, Facebook, and WeChat.

This document provides detailed information on all the APIs and guides in how to each API with the appropriate samples.

Source

Source is an entry through which a customer is registered. Unlike v1.1 APIs, v2.0 APIs provide extended support for multiple sources, i.e., you can now manage accounts of different sources such as InStore, MartJack, WeChat, e-commerce and Facebook.

V2.0 APIs also support multiple accounts of a single source. For example, an org could have multiple accounts of WeChat and Facebook. Each account will have a different account id. You would need to pass the respective account id when making API calls.

Account IDs

An organization can have multiple accounts of a source (such as WeChat). Each account will have a unique account id. You can manage customers from different accounts by passing the respective account id along with the source.

Identifiers

A customer identifier is a unique identifier that is used for registering in a source such as mobile number, email id, or external id. Identifier are also used to lookup customers and retrieve their capillary unique ids.

Capillary V2.0 APIs merge accounts automatically when a same identifier is registered in different sources.For example, assume that a customer has registered on InStore using his mobile number and e-commerce site using his email id. Now, if the customer registers the same mobile number in e-commerce site, the accounts will be merged automatically to a single customer id. You can retrieve the customer details from various sources of an organization using the unique customer id.

Before starting with v2.0 APIs, it is important to understand different official accounts created for each source and the respective account ids.

Organization Setup

The following sub-sections guides you in authenticating your organization to use Capillary v2.0 APIs.

Authentication

Capillary supports two types of authentication.

Capillary APIs can be accessed either using Basic auth (TILL/Store Center credentials), or OAuth (Client key and secret associated with 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

To configure your API keys, see API Authentication Configuration.

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

You can either pass the Authorization Header or use Till ID and password for authentication through Basic Auth.

Authorization Header

Construct the authorization header as mentioned below - pass the Base64 decoded form of username and md5 formatted password.

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

For example, if the username or TILL ID is store.server123 and the password is ‘server123’, md5 of the password

For example, if the username is store.server and the password is ‘server123’,

So the Authentication Header is

Authorization: Basic c3RvcmUuc2VydmVyOjhhMTZhNmI3MDUwNWViMWYxZmY3Y2RjMGNkNTU1OWE3

Username & Password

To use username and password for authentication, pass TILL ID as username and md5 hash encrypted password.

Consider the preceding example: username: store.server Password: md5 hash (server123) which is 8a16a6b70505eb1f1ff7cdc0cd5559a7

Now, v2 API supports submitting requests on behalf of other TILLs (active TILLs). In db the combination of attribution_lookup and lookup_code are mapped to TILL ids and org ids. When a new POST request is placed with the combination of a lookup name and lookup code, the data will be inserted in the db on behalf of the TILL that is mapped to the specified combination.

To submit requests on behalf of other TILLs, include the following code along with the HEADER:

X-CAP-API-ATTRIBUTION-LOOKUP-TYPE:<name> X-CAP-API-ATTRIBUTION-LOOKUP:<value>(value is case sensitive)

Headers Required for Basic Authentication

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 OAuth Documentation.

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

Endpoint

{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
}

Other Headers Required

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

Request Information

Request URL

https://{host}/v2/{resource}/{endpoint}?{query params}

Entry Description
Host The server to which the API calls are made, usually the cluster URL.
India: https://apac.api.capillarytech.com
APAC2: https://apac2.api.capillarytech.com
EU: https://eu.api.capillarytech.com
US: https://us.api.capillarytech.com
China: https://cdn-api.capillarytech.cn.com [or] https://api.capillarytech.cn.com
BasePath v2 or v3(API version)
Resource Provide the appropriate entity based on the action to be performed. Supported Resources: customers, communications, coupon, organization, points, product, store, transaction, goodwill requests, add events, integration resources, referral, request and other resources.
HTTP Methods The Capillary Cloud REST APIs support the standard HTTP methods GET, PUT, DELETE and POST.
Response Format JSON. All V2 and V3 APIs support only JSON response.

HTTP Status Codes

These are the standard codes that that provided the result of a client request. The response codes for each resource are provided in the respective sections.

Code Description
200 Global request success.
201 One or more requests have failed due to errors.
400 Invalid input. Please check request body parameters or input xml/json.
Invalid path parameter.
Invalid X-CAP-API-ATTRIBUTION-LOOKUP-TYPE specified.
Error with range passed or array in indexing.
401 Authentication failed. Please check username and password.
403 V2 is not enabled for the org.
Mandatory field is missing. Field {x} is mandatory.
404 Incorrect resource or resource not found.
405 The operation is not supported for the resource.
415 Unsupported media type.
461 Search Engine is busy or unable to respond. Please try after some time.
500 Requests have failed due to errors.
521 Multiple actions are running for the same customer. Please try after some time.
1060 Batch limit size exceeded.
1061 X-CAP-API-ATTRIBUTION-LOOKUP-TYPE header required with X-CAP-API-ATTRIBUTION-LOOKUP header.
1062 Invalid test and control status.
1064 Invalid org ID passed.

Customer

A customer is an individual who is either enrolled in the org’s loyalty program or subscribed to the org’s newsletters. An org is a business firm that is registered with Capillary - a retail store, hospital, pharmacy, restaurant, or any other firm.

Register Customer

Sample Request



https://us.api.capillarytech.com/v2/customers

Sample POST Request

{
  "loyaltyInfo": {
    "loyaltyType": "loyalty"
  },
  "associatedWith": "bukl.till",
  "profiles": [
    {
      "firstName": "Tom",
      "lastName": "Sawyer",
      "identifiers": [
        {
          "type": "mobile",
          "value": "919010000022"
        },
        {
          "type": "cuid",
          "value": "cuid_91901000002"
        },
        {
          "type": "unionId",
          "value": "unionId_91901000002"
        },
        {
          "type": "cardnumber",
          "value": "test123112121",
          "seriesId": 19,
          "statusLabel": "ACTIVE"
        }
      ],
      "commChannels": [
        {
          "type": "mobilePush",
          "meta": {
            "lastViewedDate": "2019-10-10T22:04:38+05:30",
            "residence": false,
            "office": false
          },
          "verified": "true",
          "primary": "true",
          "value": "abc123456"
        },
        {
          "type": "mobile",
          "value": "91901000001",
          "primary": true,
          "verified": true,
          "meta": {
            "lastViewedDate": "",
            "residence": true,
            "office": false
          }
        }
      ],    
      "source": "MOBILE_APP",
      "accountId":"400"
      "fields": {
        "employee": "true",
        "dateofbirth": "22-10-2000"
      },
    }
  ],
  "extendedFields": {
    "gender": "Male",
    "city": "Bangalore"
  },
  "loyaltyProgramEnrollments": [
    {
      "programId": 1016,
      "tierNumber": 234,
      "loyaltyPoints": 75,
      "tierExpiryDate": "2022-02-11T16:36:17+05:30",
      "pointsExpiryDate": "2022-02-11T16:36:17+05:30"
    }
  ]
}

Sample Schema to issue external cardStatus

 ... 
  {
    "type": "cardnumber",
    "value":"EXTERNALCARD9875692",
    "seriesCode": "GOLDPHY98"
  }
 ...

Sample Response

{
    "createdId": 130713699,
    "warnings": [],
    "sideEffects": [
        {
            "awardedPoints": 100,
            "type": "points"
        },
        {
            "id": 263244517,
            "couponType": "PE",
            "couponCode": "HL1FALGQ",
            "validTill": "2120-02-11T23:59:59Z",
            "description": "Test Offer 20",
            "discountCode": "NO_VALUE",
            "trimmedCouponCode": "HL1FALGQ",
            "type": "coupon"
        }
    ]
}

If the customer is registered in a different source

{
    "createdId": 342963216,
    "warnings": [
        {
            "status": false,
            "code": 8050,
            "message": "Same Customer found in other sources,Combining"
        }
    ],
    "sideEffects": [
        {
            "awardedPoints": 100,
            "type": "points"
        },
        {
            "id": 263244517,
            "couponType": "PE",
            "couponCode": "HL1FALGQ",
            "validTill": "2120-02-11T23:59:59Z",
            "description": "Test Offer 20",
            "discountCode": "NO_VALUE",
            "trimmedCouponCode": "HL1FALGQ",
            "type": "coupon"
        }
    ]
}

Lets you register customers in the org’s loyalty program or just register their identifiers across sources such as InStore, Facebook,Webengage, WeChat, Martjack, TMall, Taobao, JD, ecommerce, Line, Website, and Mobile app. You can also add customer-level extended and custom field details.

With this API, you can also issue loyalty card to the customer.

The Customer Register API functions as follows.

Prerequisites

Following are the prerequisites to use customer registration API:

Resource Information

URI /customers
Authentication Yes
HTTP Method POST
Batch Support No

Request Header (Optional)

Header Description
WAIT_FOR_DOWNSTREAM Pass true to wait for Loyalty activities to complete and then respond to the client with side effects in the API response.
Pass false to run Loyalty activities in the background. No side effects are returned in the API response.
X-CAP-DIRECT-REPLAY Pass true to add the customer but enable loyalty events to be executed at a later point of time. The events will be pushed to queue and will be executed in near real-time.

Request URL

{host}/v2/customers

Request Query Parameters

Parameter Type Description
rawSideEffects boolean Pass true to get complete details of incentives such as awardOn, expiryDate, strategyIds and so on. See rawSideEffects in response for more details.

Request Body Parameters

Parameter Type Description
loyaltyType* enum Loyalty status of the customer. Value: loyalty, non_loyalty.
profiles list Meta information of the customer.
     Firstname string First name of the customer.
     Lastname string Last name of the customer.
     identifiers* list obj Identifiers of the customer in type and value.
     source* enum Source in which you want to register a customer. Value: FACEBOOK, WEB_ENGAGE, WECHAT, INSTORE, MARTJACK, TMALL, TAOBAO, JD, ECOMMERCE, WEBSITE, LINE, MOBILE_APP. You can add customers on different sources.
     accountId** string For sources that support multiple accounts, provide the account ID. For example, FACEBOOK, WEB_ENGAGE, WECHAT, MOBILE_APP.
activity enum State of the customer’s lifecycle (entity lifecycle). State is auto assigned according to the activity.
seriesId int Card series ID (for card series generated in Capillary). Required for the identifier type, card.
seriesCode string Unique card series code (for external card series). Applicable for the identifier type, card.
statusLabel string User defined card status. Required for the identifier type, card.
     commChannels obj Available communication channels of the customer. Value: mobile, email, wechat, ios, android, line, mobilePush.
          type enum Type of the customer identifier. Values: mobile, email, externalId, wechat,martjackId, fbId mobile, tmall_uname, cuid, ali_uname, jd_uname, vip_uname, mobilePush, and line, and card (to issue loyalty card to the customers through registration).
          value string Value of the specified identifier. For the type card, value is card number.
          primary boolean Pass true if it is the primary identifier of the org (for registration).
          verified boolean Pass true if the identifier is verified.
          subscribed boolean Pass true if the identifier is subscribed for the org’s newsletters (bulk messages).
          meta obj Additional details of the identifier.
          attributes obj Additional details of the identifier.
createDate date-time Time and date of registration in YYYY-MM-DDTHH:MM:SS+HH:MM format. Example: 2016-06-23T19:11:18+08:00
associatedWith string The TILL code associated with the customer registration.
     extendedFields obj Customer level extended field details in key:value pairs. You can only pass extended fields that are enabled for your org with the respective datatype values.
     fields obj Customer level custom field details in key-value pairs.
lastViewedDate** Date Date when the customer recently opened the app. Applicable for the channel mobilePush.
loyaltyProgramEnrollments obj Lets you enroll new customers in the loyalty program.
programId int Unique ID of the loyalty program in which you want to enroll.
tierNumber int Sequence number of the tier that you want to allocate to the customer. For example, 1 for the lowest tier, 2 for the subsequent tier, and so on.
loyaltyPoints int Loyalty points to credit in customer’s account.
tierExpiryDate date-time Expiry date and time of the specified tier. Supported Format: YYYY-MM-DDTHH:MM:SS+/-(time-zone).
pointsExpiryDate date-time Expiry date and time of the points issued. Supported Format: YYYY-MM-DDTHH:MM:SS+/-(time-zone).
endPointsEnabled array Use this to add dummy customers (for internal or testing purposes) and specify the respective endpoints. Values: REFERRAL_ENDPOINT, DVS_ENDPOINT, TIMELINE_ENDPOINT, POINTSENGINE_ENDPOINT.

Update Customer Details (using userId)

Sample Request


https://us.api.capillarytech.com/v2/customers/329?source=WECHAT&accountId=22232

Sample PUT request

{  
   "profiles":[  
      {  
         "firstName":"Tom",
         "lastName":"Sawyer",
         "fields":{  
            "gender":"Male",
            "city":"Bangalore"
         },
         "identifiers":[  
            {  
               "type":"mobile",
               "value":919111111111
            },
            {  
               "type":"email",
               "value":"tom.sawyer@example.com"
            },
            {  
               "type":"wechat",
               "value":"wc_2"
            }
         ],
         "commChannels":[  
            {  
               "type":"email",
               "value":"tom.sawyer@example.com",
               "primary":"true",
               "verified":"false",
               "meta":{  
                  "residence":true
               }
            },
            {  
               "type":"wechat",
               "value":"wc_2",
               "primary":"true",
               "verified":"true",
               "meta":{  
                  "residence":true
               }
            }
         ],
         "source":"WECHAT",
         "accountId":"1234"
      }
   ],
   "loyaltyInfo":{  
      "loyaltyType":"loyalty"
   },
   "extendedFields":  
      {  
         "gender":"MALE",
         "city":"Bangalore"
      },
     "loyaltyProgramEnrollments":[{
     "programId":1016,
     "tierNumber": 234,
    "loyaltyPoints": 75,
    "tierExpiryDate": "2022-02-11T16:36:17+05:30",
    "pointsExpiryDate": "2022-02-11T16:36:17+05:30"
}]

}

# Sample Schema of mobilePush
{  
    "type":"mobilePush",
    "value":"abcd12343434", //This is an FCM Token
    "primary":true,
    "verified":true,
    "meta":{
      "lastViewedDate": "2019-10-25"
    }
}

Sample Response

{
    "createdId": 162116213,
    "warnings": [],
    "sideEffects": [
    {
    "awardedPoints": 25,
    "type": "points"
    }
  ]
}

Allows updating customer details on any source - FACEBOOK, WEB_ENGAGE, WECHAT, INSTORE, MARTJACK, TMALL, TAOBAO, JD, ECOMMERCE, WEBSITE or LINE. You can update profile information, extended field values, communication details, custom field values, and loyalty status (only non loyalty to loyalty).

Limitations of the customer update API:

Prerequisites

The following are the prerequisites for updating customer details:

Resource Information

URI /{customerId}?{queryParam}={paramValue}
Authentication Yes
HTTP Method PUT
Batch Support No

Request URL

For sources with single accounts

{host}/v2/customers/{customerId}?source={sourceName}

For sources with multiple accounts {host}/v2/customers/{customerId}?source={sourceName}&accountId={accountId}

Request Query Parameters

Parameter Description
customerId* Unique ID of the customer whose details need to be updated
source* Specify the source in which you want to update the customer details - FACEBOOK, WEB_ENGAGE, WECHAT, INSTORE, MARTJACK, TMALL, TAOBAO, JD, ECOMMERCE, WEBSITE, LINE, MOBILE_APP. For sources with multiple accounts such as WECHAT, FACEBOOK, MOBILE_APP, or LINE, you also need to provide the respective account id.
accountId** Account in which you want to update the customer details (Required only for sources with multiple accounts)
use_async boolean

Request Body Parameters

Parameter Type Description
loyaltyType enum Loyalty status of the customer. Value: loyalty, non_loyalty.
commChannels obj Communication channels of the customer.
type enum Type of the communication channel. Value: mobile, email, wechat, ios, android, line, mobilePush.
value string Based on the channel type enter the channel value. Example, mobile number is the value for type:mobile, firebase token for type:mobilePush. mobilePush is supported for sources mobile_app, Instore, Martjack, Ecommerce, and Website
primary boolean Whether the current identifier is the primary identifier of the customer (primary identifier as per the org’s configuration).
lastViewedDate date Date when the customer recently opened the app. Applicable for the channel ‘mobilePush’.
verified boolean Whether the current identifier is verified or not. For example, through OTP.
profiles obj Profile information of the customer.
meta obj Additional information of the identifier.
Firstname string First name of the customer.
Lastname string Last name of the customer.
identifiers obj Identifiers of the customer that you want to add in type and value. Supported types: mobile, email, externalId, wechat,martjackId, fbId mobile, tmall_uname, cuid, ali_uname, jd_uname, vip_uname, and line.
profiles fields Custom field details (only that configured for the organization)
extendedFields obj Extended field details of the customer in key:value pairs. You can only pass extended fields that are enabled for your org with the respective datatypes for values.
fields obj Custom field details of the customer in key:value pairs.
loyaltyProgramEnrollments obj Lets you enroll new customers in the loyalty program.
programId int Unique ID of the loyalty program in which you want to enroll. You cannot update details if the customer is already enrolled in the loyalty program.
tierNumber int Sequence number of the tier that you want to allocate to the customer. For example, 1 for the lower tier, 2 for the next tier, and so on.
loyaltyPoints int Loyalty points to credit in customer’s account.
tierExpiryDate date-time Expiry date and time of the specified tier. Supported Format: YYYY-MM-DDTHH:MM:SS+/-(time-zone).
pointsExpiryDate date-time Expiry date and time of the points issued. Supported Format: YYYY-MM-DDTHH:MM:SS+/-(time-zone).

Update Customer Identifiers/Issue Card

Sample Request

https://us.api.capillarytech.com/v2/customers/418/changeIdentifier?source=WECHAT&accountId=22232

Sample POST Request

{
    "add": [
        {
            "type": "wechat",
            "value": "ray11"
        }
    ],
    "remove": [
        {
            "type": "email",
            "value": "tom.sawyer@example.com"
        }
    ]
}

Sample POST Request (to Issue Card)

{
  "add": [
    {
      "value": "TTM001110000000001ZS",
      "type": "cardnumber",
      "seriesId": 19,
      "statusLabel": "ACTIVE"
    }
  ]
}

Sample Response

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

Lets you add/remove identifiers or loyalty cards of a customer across sources.

Identifiers: mobile, email, externalId, wechat, martjackId, fbId, tmall_uname, cuid, ali_uname, jd_uname, vip_uname, line.

Limitations of the customer identifier update API:

Prerequisites

Resource Information

URI `/{customerId}/changeIdentifier?source={source}&accountId={accountId}‘
Authentication Yes
HTTP Method POST
Batch Support No

Request URL

{host}/v2/customers/{customerId}/changeIdentifier?source={source}&accountId={accountId}

Request Query Parameters

Parameter Type Description
customerId* int Unique ID of the customer whose identifiers need to be updated
source* enum Source in which you want to update customer identifier(s) - FACEBOOK, WEB_ENGAGE, WECHAT, INSTORE, MARTJACK, TMALL, TAOBAO, JD, ECOMMERCE, WEBSITE. For sources that support multiple accounts, you also need to provide the associated account id.
accountId** string Account for which you want to update the customer identifier (Required only for sources with multiple accounts)
seriesId int Series ID of the card that you want to add or remove.
statusLabel enum Status of the card. Value: ACTIVE (to activate a card).
use_async boolean Pass true to run Loyalty activities in the background, side effects will not be returned in the API response. If false, API will wait for Loyalty activities to complete and then respond to the client with side effects in the API response.

Request Body Parameters

Attributes Type Description
add** obj New identifier that you want to add to the existing account. Pass the identifiers as a key value pair.
{“type": "wechat", "value": "TS11"}
remove** obj Existing Identifier that you want to remove from the specified account. {"type": "email", "value": "tom.sawyer@example.com"}
type* enum Type of the identifier that you want to add or remove. Value: cardnumber, email, mobile, and wechat.
value* string Value of the specified type. For example, if type is email, then pass the email id that you want to add or remove in value; for cardNumber pass card number to add or remove.

Error Codes

CODE DESCRIPTION
8007 Unable to update. The identifier is already registered in the same source.
8008 The new identifier already exists in the same source.
8009 Unable to identify the customer. Customer id is invalid.
8051 Same identifier found in other source. Merging into the account with user id X.
8053 Each identifier is registered with a different customer in other source. Unable to merge accounts.
8053 Same identifier is registered on other source. The account is already merged with user id X.
8064 External id validation failed.
8066 Unable to combine,User id already used in same source.
8067 Same customer found in other source. The account is already merged with user id X.
8059 Unable to push customer to solr.
8058 Invalid mobile number passed in the communication channel.
8057 Invalid email id passed in the communication channel.
8056 Invalid mobile number.
8055 Invalid email id.
8045 Account id is not passed.
8010 communication channel is invalid.

Associate Customer with Customer/Hierarchy

Lets you batch register customers, or associate a customer with company or hierarchy. This API registers parent and child customers (if not registered), and associates the customer with hierarchy code, company role, parent and child customers.

Sample Request

https://us.api.capillarytech.com/v2/customers/bulk

Sample POST Request (Associate Child with Parent)

[
   {
      "profiles":[
         {
            "firstName":"Capillary",
            "lastName":"Customer",
            "identifiers":[
               {
                  "type":"mobile",
                  "value":"917979000000"
               },
               {
                  "type":"cuid",
                  "value":"cuid_917979000000"
               },
               {
                  "type":"unionId",
                  "value":"unionId_917979000000"
               },
               {
                  "type":"cardnumber",
                  "cardExternalId":"carduuid_710000",
                  "value":"card_710000",
                  "seriesCode":"FleetCard1",
                  "statusLabel":"ACTIVE",
                  "extendedFields":{
                     "custom_card_name":"64346srt34532323",
                     "vehicle_number":"879976453431adsgfsf"
                  }
               }
            ],
            "commChannels":[
               {
                  "type":"mobile",
                  "value":"9020000000",
                  "primary":true,
                  "verified":true
               },
               {
                  "type":"email",
                  "value":"tom.sawyer@mail.com",
                  "primary":true,
                  "verified":true
               }
            ],
            "fields":{
               "gender":"MALE",
               "city":"city0"
            },
            "source":"WECHAT",
            "accountId":"WECHAT-CM"
         }
      ],
      "extendedFields":{
         "gender":"Male",
         "city":"city_6878387"
      },
      "loyaltyInfo":{
         "loyaltyType":"loyalty"
      },
      "referralCode":"",
      "associationDetails":{
         "hierarchyCode":"code-association2",
         "roleCode":"FA",
         "childCustomers":[
            {
               "profiles":[
                  {
                     "firstName":"Capillary",
                     "lastName":"Customer",
                     "identifiers":[
                        {
                           "type":"mobile",
                           "value":"{{mobile2}}"
                        },
                        {
                           "type":"cuid",
                           "value":"cuid_{{mobile2}}"
                        },
                        {
                           "type":"unionId",
                           "value":"unionId_{{mobile2}}"
                        }
                     ],
                     "commChannels":[
                        {
                           "type":"mobile",
                           "value":"{{mobile2}}",
                           "primary":true,
                           "verified":true
                        },
                        {
                           "type":"email",
                           "value":"{{mobile2}}@mail.com",
                           "primary":true,
                           "verified":true
                        }
                     ],
                     "fields":{
                        "gender":"MALE",
                        "city":"city0"
                     },
                     "source":"WECHAT",
                     "accountId":"WECHAT-CM"
                  }
               ],
               "extendedFields":{
                  "gender":"Male",
                  "city":"city_6878387"
               }
            },
            {
               "profiles":[
                  {
                     "firstName":"Capillary",
                     "lastName":"Customer",
                     "identifiers":[
                        {
                           "type":"mobile",
                           "value":"{{mobile3}}"
                        },
                        {
                           "type":"cuid",
                           "value":"cuid_{{mobile3}}"
                        },
                        {
                           "type":"unionId",
                           "value":"unionId_{{mobile3}}"
                        }
                     ],
                     "commChannels":[
                        {
                           "type":"mobile",
                           "value":"{{mobile3}}",
                           "primary":true,
                           "verified":true
                        },
                        {
                           "type":"email",
                           "value":"{{mobile3}}@mail.com",
                           "primary":true,
                           "verified":true
                        }
                     ],
                     "fields":{
                        "gender":"MALE",
                        "city":"city0"
                     },
                     "source":"WECHAT",
                     "accountId":"WECHAT-CM"
                  }
               ],
               "extendedFields":{
                  "gender":"Male",
                  "city":"city_6878387"
               }
            }
         ],
         "fleetCompany":{
            "externalId":"ex917471949194"
         },
         "childRoleCode":"FC"
      }
   }
]

Sample POST Request (Associate Child to Parent )

...
{
   "associationDetails":{
      "hierarchyCode":"code-association2",
      "roleCode":"FC",
      "parentCustomer":{
         "profiles":[
            {
               "firstName":"慧慧",
               "lastName":"慧慧",
               "identifiers":[
                  {
                     "type":"mobile",
                     "value":"917875000000"
                  },
                  {
                     "type":"cuid",
                     "value":"cuid_917875000000"
                  },
                  {
                     "type":"unionId",
                     "value":"unionId_917875000000"
                  }
               ],
               "commChannels":[
                  {
                     "type":"mobile",
                     "value":"917685000000",
                     "primary":true,
                     "verified":true
                  },
                  {
                     "type":"email",
                     "value":"917685000000@mail.com",
                     "primary":true,
                     "verified":true
                  }
               ],
               "source":"WECHAT",
               "accountId":"WECHAT-CM"
            }
         ],
         "extendedFields":{
            "gender":"Male",
            "city":"city_6878387"
         }
      },
      "fleetCompany":{
         "externalId":"ex91747000000"
      }
   }
}

Sample Response

[
   {
      "entity":{
         "id":409966467,
         "profiles":[
            {
               "firstName":"Capillary",
               "lastName":"Customer",
               "attribution":{
                  "createDate":"2021-07-30T11:25:21+05:30",
                  "createdBy":{
                     "id":15071481,
                     "code":"cm.1",
                     "description":"",
                     "name":"cm.1",
                     "type":"TILL",
                     "adminType":"GENERAL",
                     "isActive":true,
                     "isOuEnabled":true,
                     "timeZoneId":0,
                     "currencyId":95,
                     "languageId":-1
                  },
                  "modifiedBy":{
                     "id":15071481,
                     "code":"cm.1",
                     "description":"",
                     "name":"cm.1",
                     "type":"TILL",
                     "adminType":"GENERAL",
                     "isActive":true,
                     "isOuEnabled":true,
                     "timeZoneId":0,
                     "currencyId":95,
                     "languageId":-1
                  },
                  "modifiedDate":"2021-07-30T11:25:21+05:30"
               },
               "fields":{
                  "gender":"MALE"
               },
               "identifiers":[
                  {
                     "type":"mobile",
                     "value":"917979015462"
                  },
                  {
                     "type":"cuid",
                     "value":"cuid_917979015462"
                  },
                  {
                     "type":"cardnumber",
                     "value":"card_917979015462",
                     "seriesCode":"FleetCard1",
                     "statusLabel":"ACTIVE",
                     "cardExternalId":"carduuid_917979015462",
                     "extendedFields":{
                        "custom_card_name":"64346srt34532323",
                        "vehicle_number":"879976453431adsgfsf"
                     }
                  },
                  {
                     "type":"unionId",
                     "value":"unionId_917979000000"
                  }
               ],
               "commChannels":[
                  {
                     "type":"mobile",
                     "value":"917979000000",
                     "primary":true,
                     "verified":true,
                     "meta":{
                        "residence":false,
                        "office":false
                     },
                     "attributes":{

                     }
                  },
                  {
                     "type":"email",
                     "value":"917979000000@mail.com",
                     "primary":true,
                     "verified":true,
                     "meta":{
                        "residence":false,
                        "office":false
                     },
                     "attributes":{

                     }
                  }
               ],
               "source":"WECHAT",
               "userId":409966467,
               "accountId":"WECHAT-CM",
               "conflictingProfileList":[

               ],
               "autoUpdateTime":"2021-07-30T11:25:21+05:30",
               "identifiersAll":[
                  {
                     "type":"mobile",
                     "value":"917979015462"
                  },
                  {
                     "type":"cuid",
                     "value":"cuid_917979015462"
                  },
                  {
                     "type":"cardnumber",
                     "value":"card_917979015462",
                     "seriesCode":"FleetCard1",
                     "statusLabel":"ACTIVE",
                     "cardExternalId":"carduuid_917979015462",
                     "extendedFields":{
                        "custom_card_name":"64346srt34532323",
                        "vehicle_number":"879976453431adsgfsf"
                     }
                  },
                  {
                     "type":"unionId",
                     "value":"unionId_917979015462"
                  }
               ]
            }
         ],
         "loyaltyInfo":{
            "loyaltyType":"loyalty"
         },
         "segments":{

         },
         "referralCode":"",
         "associationDetails":{
            "hierarchyCode":"code-association2",
            "hierarchyId":21,
            "roleCode":"FA",
            "childCustomers":[
               {
                  "profiles":[
                     {
                        "firstName":"Capillary",
                        "lastName":"Customer",
                        "attribution":{
                           "createDate":"2021-07-30T11:25:21+05:30",
                           "createdBy":{
                              "id":15071481,
                              "code":"cm.1",
                              "description":"",
                              "name":"cm.1",
                              "type":"TILL",
                              "adminType":"GENERAL",
                              "isActive":true,
                              "isOuEnabled":true,
                              "timeZoneId":0,
                              "currencyId":95,
                              "languageId":-1
                           },
                           "modifiedBy":{
                              "id":15071481,
                              "code":"cm.1",
                              "description":"",
                              "name":"cm.1",
                              "type":"TILL",
                              "adminType":"GENERAL",
                              "isActive":true,
                              "isOuEnabled":true,
                              "timeZoneId":0,
                              "currencyId":95,
                              "languageId":-1
                           },
                           "modifiedDate":"2021-07-30T11:25:21+05:30"
                        },
                        "fields":{
                           "gender":"MALE"
                        },
                        "identifiers":[
                           {
                              "type":"cuid",
                              "value":"cuid_91553000000"
                           },
                           {
                              "type":"unionId",
                              "value":"unionId_91553000000"
                           },
                           {
                              "type":"cardnumber",
                              "value":"regcm0000000000182412"
                           }
                        ],
                        "commChannels":[
                           {
                              "type":"email",
                              "value":"91553000000@mail.com",
                              "primary":true,
                              "verified":true,
                              "meta":{
                                 "residence":false,
                                 "office":false
                              },
                              "attributes":{

                              }
                           }
                        ],
                        "source":"WECHAT",
                        "userId":409966468,
                        "accountId":"WECHAT-CM",
                        "conflictingProfileList":[

                        ],
                        "autoUpdateTime":"2021-07-30T11:25:21+05:30",
                        "identifiersAll":[
                           {
                              "type":"cuid",
                              "value":"cuid_91553000000"
                           },
                           {
                              "type":"unionId",
                              "value":"unionId_91553000000"
                           },
                           {
                              "type":"cardnumber",
                              "value":"regcm0000000000182412"
                           }
                        ]
                     }
                  ],
                  "extendedFields":{
                     "city":"city_6878387",
                     "gender":"Male"
                  }
               },
               {
                  "profiles":[
                     {
                        "firstName":"Capillary",
                        "lastName":"Customer",
                        "attribution":{
                           "createDate":"2021-07-30T11:25:21+05:30",
                           "createdBy":{
                              "id":15071481,
                              "code":"cm.1",
                              "description":"",
                              "name":"cm.1",
                              "type":"TILL",
                              "adminType":"GENERAL",
                              "isActive":true,
                              "isOuEnabled":true,
                              "timeZoneId":0,
                              "currencyId":95,
                              "languageId":-1
                           },
                           "modifiedBy":{
                              "id":15071481,
                              "code":"cm.1",
                              "description":"",
                              "name":"cm.1",
                              "type":"TILL",
                              "adminType":"GENERAL",
                              "isActive":true,
                              "isOuEnabled":true,
                              "timeZoneId":0,
                              "currencyId":95,
                              "languageId":-1
                           },
                           "modifiedDate":"2021-07-30T11:25:21+05:30"
                        },
                        "fields":{
                           "gender":"MALE"
                        },
                        "identifiers":[
                           {
                              "type":"mobile",
                              "value":"916894126424"
                           },
                           {
                              "type":"cuid",
                              "value":"cuid_916894126424"
                           },
                           {
                              "type":"cardnumber",
                              "value":"regcm0000000000182413"
                           },
                           {
                              "type":"unionId",
                              "value":"unionId_916894126424"
                           }
                        ],
                        "commChannels":[
                           {
                              "type":"email",
                              "value":"916894126424@mail.com",
                              "primary":true,
                              "verified":true,
                              "meta":{
                                 "residence":false,
                                 "office":false
                              },
                              "attributes":{

                              }
                           },
                           {
                              "type":"mobile",
                              "value":"916894126424",
                              "primary":true,
                              "verified":true,
                              "meta":{
                                 "residence":false,
                                 "office":false
                              },
                              "attributes":{

                              }
                           }
                        ],
                        "source":"WECHAT",
                        "userId":409966469,
                        "accountId":"WECHAT-CM",
                        "conflictingProfileList":[

                        ],
                        "autoUpdateTime":"2021-07-30T11:25:21+05:30",
                        "identifiersAll":[
                           {
                              "type":"mobile",
                              "value":"916894126424"
                           },
                           {
                              "type":"cuid",
                              "value":"cuid_916894126424"
                           },
                           {
                              "type":"cardnumber",
                              "value":"regcm0000000000182413"
                           },
                           {
                              "type":"unionId",
                              "value":"unionId_916894126424"
                           }
                        ]
                     }
                  ],
                  "extendedFields":{
                     "city":"city_6878387",
                     "gender":"Male"
                  }
               }
            ],
            "fleetCompany":{
               "externalId":"ex917471949194",
               "companyId":71
            },
            "childRoleCode":"FC",
            "skipLevelAllowed":false,
            "new":true,
            "childCustomer":false
         },
         "extendedFields":{
            "city":"city_6878387",
            "gender":"Male"
         },
         "warnings":[
            {
               "status":false,
               "code":19223,
               "message":"Points processing failed"
            }
         ]
      },
      "childEntities":[
         {
            "id":409966468,
            "profiles":[
               {
                  "firstName":"Capillary",
                  "lastName":"Customer",
                  "attribution":{
                     "createDate":"2021-07-30T11:25:21+05:30",
                     "createdBy":{
                        "id":15071481,
                        "code":"cm.1",
                        "description":"",
                        "name":"cm.1",
                        "type":"TILL",
                        "adminType":"GENERAL",
                        "isActive":true,
                        "isOuEnabled":true,
                        "timeZoneId":0,
                        "currencyId":95,
                        "languageId":-1
                     },
                     "modifiedBy":{
                        "id":15071481,
                        "code":"cm.1",
                        "description":"",
                        "name":"cm.1",
                        "type":"TILL",
                        "adminType":"GENERAL",
                        "isActive":true,
                        "isOuEnabled":true,
                        "timeZoneId":0,
                        "currencyId":95,
                        "languageId":-1
                     },
                     "modifiedDate":"2021-07-30T11:25:21+05:30"
                  },
                  "fields":{
                     "gender":"MALE"
                  },
                  "identifiers":[
                     {
                        "type":"cuid",
                        "value":"cuid_91553015360"
                     },
                     {
                        "type":"unionId",
                        "value":"unionId_91553015360"
                     },
                     {
                        "type":"cardnumber",
                        "value":"regcm0000000000182412"
                     }
                  ],
                  "commChannels":[
                     {
                        "type":"email",
                        "value":"91553015360@mail.com",
                        "primary":true,
                        "verified":true,
                        "meta":{
                           "residence":false,
                           "office":false
                        },
                        "attributes":{

                        }
                     }
                  ],
                  "source":"WECHAT",
                  "userId":409966468,
                  "accountId":"WECHAT-CM",
                  "conflictingProfileList":[

                  ],
                  "autoUpdateTime":"2021-07-30T11:25:21+05:30",
                  "identifiersAll":[
                     {
                        "type":"cuid",
                        "value":"cuid_91553015360"
                     },
                     {
                        "type":"unionId",
                        "value":"unionId_91553015360"
                     },
                     {
                        "type":"cardnumber",
                        "value":"regcm0000000000182412"
                     }
                  ]
               }
            ],
            "loyaltyInfo":{
               "loyaltyType":"loyalty"
            },
            "segments":{

            },
            "associationDetails":{
               "hierarchyId":21,
               "roleCode":"FC",
               "fleetCompany":{
                  "externalId":"ex917471949194",
                  "companyId":71
               },
               "parentRoleId":83,
               "skipLevelAllowed":false,
               "new":true,
               "childCustomer":true
            },
            "extendedFields":{
               "city":"city_6878387",
               "gender":"Male"
            },
            "warnings":[
               {
                  "status":false,
                  "code":8056,
                  "message":"Invalid mobile"
               },
               {
                  "status":false,
                  "code":8058,
                  "message":"Invalid mobile in comm channel"
               },
               {
                  "status":false,
                  "code":19223,
                  "message":"Points processing failed"
               }
            ]
         },
         {
            "id":409966469,
            "profiles":[
               {
                  "firstName":"Capillary",
                  "lastName":"Customer",
                  "attribution":{
                     "createDate":"2021-07-30T11:25:21+05:30",
                     "createdBy":{
                        "id":15071481,
                        "code":"cm.1",
                        "description":"",
                        "name":"cm.1",
                        "type":"TILL",
                        "adminType":"GENERAL",
                        "isActive":true,
                        "isOuEnabled":true,
                        "timeZoneId":0,
                        "currencyId":95,
                        "languageId":-1
                     },
                     "modifiedBy":{
                        "id":15071481,
                        "code":"cm.1",
                        "description":"",
                        "name":"cm.1",
                        "type":"TILL",
                        "adminType":"GENERAL",
                        "isActive":true,
                        "isOuEnabled":true,
                        "timeZoneId":0,
                        "currencyId":95,
                        "languageId":-1
                     },
                     "modifiedDate":"2021-07-30T11:25:21+05:30"
                  },
                  "fields":{
                     "gender":"MALE"
                  },
                  "identifiers":[
                     {
                        "type":"mobile",
                        "value":"916894126424"
                     },
                     {
                        "type":"cuid",
                        "value":"cuid_916894126424"
                     },
                     {
                        "type":"cardnumber",
                        "value":"regcm0000000000182413"
                     },
                     {
                        "type":"unionId",
                        "value":"unionId_916894126424"
                     }
                  ],
                  "commChannels":[
                     {
                        "type":"email",
                        "value":"916894126424@mail.com",
                        "primary":true,
                        "verified":true,
                        "meta":{
                           "residence":false,
                           "office":false
                        },
                        "attributes":{

                        }
                     },
                     {
                        "type":"mobile",
                        "value":"916894126424",
                        "primary":true,
                        "verified":true,
                        "meta":{
                           "residence":false,
                           "office":false
                        },
                        "attributes":{

                        }
                     }
                  ],
                  "source":"WECHAT",
                  "userId":409966469,
                  "accountId":"WECHAT-CM",
                  "conflictingProfileList":[

                  ],
                  "autoUpdateTime":"2021-07-30T11:25:21+05:30",
                  "identifiersAll":[
                     {
                        "type":"mobile",
                        "value":"916894126424"
                     },
                     {
                        "type":"cuid",
                        "value":"cuid_916894126424"
                     },
                     {
                        "type":"cardnumber",
                        "value":"regcm0000000000182413"
                     },
                     {
                        "type":"unionId",
                        "value":"unionId_916894126424"
                     }
                  ]
               }
            ],
            "loyaltyInfo":{
               "loyaltyType":"loyalty"
            },
            "segments":{

            },
            "associationDetails":{
               "hierarchyId":21,
               "roleCode":"FC",
               "fleetCompany":{
                  "externalId":"ex9174710000",
                  "companyId":71
               },
               "parentRoleId":83,
               "skipLevelAllowed":false,
               "new":true,
               "childCustomer":true
            },
            "extendedFields":{
               "city":"city_6878387",
               "gender":"Male"
            },
            "warnings":[
               {
                  "status":false,
                  "code":19223,
                  "message":"Points processing failed"
               }
            ]
         }
      ],
      "childCount":2,
      "childFailureCount":0,
      "childSuccessCount":2
   }
]

Resource Information

URI customers/bulk
Authentication Yes
HTTP Method POST
Batch Support Yes

Request URL

{host}/v2/customers/bulk

Request Body Parameters

Parameter Type Description
loyaltyType* enum Loyalty status of the customer. Value: loyalty, non_loyalty.
profiles obj Meta information of the customer.
identifiers* obj Identifiers of the customer in type and value.
type enum Type of the customer identifier. Values: mobile, email, externalId, wechat,martjackId, fbId mobile, tmall_uname, cuid, ali_uname, jd_uname, vip_uname, mobilePush, and line, and card (to issue loyalty card to the customers through registration).
value string Value of the specified identifier. For the type card, value is card number.
seriesId int Card series ID (for card series generated in Capillary). Required for the identifier type, card.
seriesCode string Unique card series code (for external card series). Applicable for the identifier type, card.
statusLabel string User defined card status. Required for the identifier type, card.
lastViewedDate** Date Date when the customer recently opened the app. Applicable for the channel mobilePush.
loyaltyProgramEnrollments obj Lets you enroll new customers in the loyalty program.
programId int Unique ID of the loyalty program in which you want to enroll.
tierNumber int Sequence number of the tier that you want to allocate to the customer. For example, 1 for the lowest tier, 2 for the subsequent tier, and so on.
loyaltyPoints int Loyalty points to credit in customer’s account.
tierExpiryDate date-time Expiry date and time of the specified tier. Supported Format: YYYY-MM-DDTHH:MM:SS+/-(time-zone).
pointsExpiryDate date-time Expiry date and time of the points issued. Supported Format: YYYY-MM-DDTHH:MM:SS+/-(time-zone).
hierarchyCode string Unique code of the hierarchy to associate with the customer/company. All configurations set for the hierarchy will be applicable to the customer/company.
roleCode string Pre defined role code - Role of the customer in the hierarchy.
parentCustomer obj User profile of the parent customer.
fleetCompany obj Details of the company the customer is associated with.
childCustomers obj Profiles of the child customers.
externalId string External ID of the company.
profiles obj Details of the customer to associate.
Firstname string First name of the customer.
Lastname string Last name of the customer.
identifiers* obj Identifiers of the customer in type and value.
type enum Type of the customer identifier. Values: mobile, email, externalId, wechat,martjackId, fbId mobile, tmall_uname, cuid, ali_uname, jd_uname, vip_uname, mobilePush, and line, and card (to issue loyalty card to the customers through registration).
value string Value of the specified identifier. For the type card, value is card number.
commChannels obj Available communication channels of the customer. Value: mobile, email, wechat, ios, android, line, mobilePush.
Firstname string First name of the customer.
Lastname string Last name of the customer.
createDate date-time Time and date of registration in YYYY-MM-DDTHH:MM:SS+HH:MM format. Example: 2016-06-23T19:11:18+08:00
associatedWith string The TILL code associated with the customer registration.
extendedFields obj Customer level extended field details of the customer in key:value pairs. You can only pass extended fields that are enabled for your org with the respective datatypes for values.
fields obj Custom field details of customers in key-value pairs.

Update Association Details (for Customer/Company)

Lets you update group customer details.

http://eu.api.capillarytech.com/v2/customers/bulk?source=WECHAT&accountId=WECHAT-CM

Sample PUT Request

[{
  "profiles": [
    {
       "firstName": "Tom",
      "lastName": "Sawyer",
      "identifiers": [
        {
          "type": "mobile",
          "value": "915905000000"
        },
        {
          "type": "cuid",
          "value": "cuid_915905000000"
        },
        {
          "type": "unionId",
          "value": "unionId_915905000000"
        }
      ],
      "commChannels": [
        {
          "type": "mobile",
          "value": "915905000000",
          "primary": true,
          "verified": true
        },
        {
          "type": "email",
          "value": "915905000000@mail.com",
          "primary": true,
          "verified": true
        }
      ],
      "source": "WECHAT",
      "accountId": "WECHAT-CM"
    }
  ],
  "extendedFields": {
    "gender": "Male",
    "city": "city_6878387"
  },
  "loyaltyInfo": {
    "loyaltyType": "loyalty"
  },
  "referralCode": "",
  "associationDetails": {
    "hierarchyCode": "code-association2",
      "roleCode": "FA",
    "parentCustomer": 
      {
        "profiles": [
          {
            "firstName": "Jim",
            "lastName": "Solace",
            "identifiers": [
              {
                "type": "mobile",
                "value": "919905000000"
              },
              {
                "type": "cuid",
                "value": "cuid_919905000000"
              },
              {
                "type": "unionId",
                "value": "unionId_919905000000"
              }
            ],
            "commChannels": [
              {
                "type": "mobile",
                "value": "919905000000",
                "primary": true,
                "verified": true
              },
              {
                "type": "email",
                "value": "919905000000@mail.com",
                "primary": true,
                "verified": true
              }
            ],
            "source": "WECHAT",
            "accountId": "WECHAT-CM"
          }
        ],
        "extendedFields": {
          "gender": "Male",
          "city": "city_6878387"
        }
      },
    "fleetCompany": {
      "externalId": "ex917471000000"
    }
  }
}]

Sample Response

[
   {
      "profiles":[
         {
            "firstName":"Tom",
            "lastName":"Sawyer",
            "attribution":{
               "createDate":"2021-08-03T17:05:38+05:30",
               "createdBy":{

               },
               "modifiedBy":{

               },
               "modifiedDate":"2021-08-03T17:05:38+05:30"
            },
            "fields":{

            },
            "identifiers":[
               {
                  "type":"unionId",
                  "value":"unionId_915905000000"
               },
               {
                  "type":"cuid",
                  "value":"cuid_915905000000"
               },
               {
                  "type":"mobile",
                  "value":"915905000000"
               }
            ],
            "commChannels":[
               {
                  "type":"email",
                  "value":"915905000000@mail.com",
                  "primary":true,
                  "verified":true,
                  "meta":{
                     "residence":false,
                     "office":false
                  },
                  "attributes":{

                  }
               },
               {
                  "type":"mobile",
                  "value":"915905000000",
                  "primary":true,
                  "verified":true,
                  "meta":{
                     "residence":false,
                     "office":false
                  },
                  "attributes":{

                  }
               }
            ],
            "source":"WECHAT",
            "accountId":"WECHAT-CM",
            "conflictingProfileList":[

            ],
            "autoUpdateTime":"2021-08-03T17:05:38+05:30",
            "identifiersAll":[
               {
                  "type":"unionId",
                  "value":"unionId_915905000000"
               },
               {
                  "type":"cuid",
                  "value":"cuid_915905000000"
               },
               {
                  "type":"mobile",
                  "value":"915905000000"
               }
            ]
         }
      ],
      "loyaltyInfo":{
         "loyaltyType":"loyalty"
      },
      "segments":{

      },
      "referralCode":"",
      "associationDetails":{
         "hierarchyCode":"code-association2",
         "roleCode":"FA",
         "parentCustomer":{
            "profiles":[
               {
                  "firstName":"Jim",
                  "lastName":"Solace",
                  "attribution":{
                     "createDate":"2021-08-03T17:05:38+05:30",
                     "createdBy":{

                     },
                     "modifiedBy":{

                     },
                     "modifiedDate":"2021-08-03T17:05:38+05:30"
                  },
                  "fields":{

                  },
                  "identifiers":[
                     {
                        "type":"cuid",
                        "value":"cuid_919905000000"
                     },
                     {
                        "type":"unionId",
                        "value":"unionId_919905000000"
                     },
                     {
                        "type":"mobile",
                        "value":"919905000000"
                     }
                  ],
                  "commChannels":[
                     {
                        "type":"mobile",
                        "value":"919905000000",
                        "primary":true,
                        "verified":true,
                        "meta":{
                           "residence":false,
                           "office":false
                        },
                        "attributes":{

                        }
                     },
                     {
                        "type":"email",
                        "value":"919905000000@mail.com",
                        "primary":true,
                        "verified":true,
                        "meta":{
                           "residence":false,
                           "office":false
                        },
                        "attributes":{

                        }
                     }
                  ],
                  "source":"WECHAT",
                  "accountId":"WECHAT-CM",
                  "conflictingProfileList":[

                  ],
                  "autoUpdateTime":"2021-08-03T17:05:38+05:30",
                  "identifiersAll":[
                     {
                        "type":"cuid",
                        "value":"cuid_919905000000"
                     },
                     {
                        "type":"unionId",
                        "value":"unionId_919905000000"
                     },
                     {
                        "type":"mobile",
                        "value":"919905000000"
                     }
                  ]
               }
            ],
            "extendedFields":{
               "city":"city_6878387",
               "gender":"Male"
            }
         },
         "fleetCompany":{
            "externalId":"ex917471000000"
         },
         "skipLevelAllowed":false,
         "new":true,
         "childCustomer":false
      },
      "extendedFields":{
         "city":"city_6878387",
         "gender":"Male"
      },
      "errors":[
         {}
      ]
   }
]

Resource Information

URI `/bulk?{queryParam}={paramValue}’
Authentication Yes
HTTP Method PUT
Batch Support Yes

Request URL

{host}/v2/customers/search?{queryParam}={paramValue}

Request Query Parameters

Parameter Datatype Description
source* enum Source on which the customer details need to be updated Values: FACEBOOK, WEB_ENGAGE, WECHAT, INSTORE, MARTJACK, TMALL, TAOBAO, JD, ECOMMERCE, WEBSITE, LINE, ALL.
accountId** string The account id of the specific source. Required for sources with multiple accounts such as WeChat or Facebook.

Request Body Parameters

Parameter Datatype Description

Request Body Parameters

Parameter Type Description
loyaltyType* enum Loyalty status of the customer. Value: loyalty, non_loyalty.
profiles obj Meta information of the customer.
identifiers* obj Identifiers of the customer in type and value.
type enum Type of the customer identifier. Values: mobile, email, externalId, wechat,martjackId, fbId mobile, tmall_uname, cuid, ali_uname, jd_uname, vip_uname, mobilePush, and line, and card (to issue loyalty card to the customers through registration).
value string Value of the specified identifier. For the type card, value is card number.
seriesId int Card series ID (for card series generated in Capillary). Required for the identifier type, card.
seriesCode string Unique card series code (for external card series). Applicable for the identifier type, card.
statusLabel string User defined card status. Required for the identifier type, card.
lastViewedDate** Date Date when the customer recently opened the app. Applicable for the channel mobilePush.
loyaltyProgramEnrollments obj Lets you enroll new customers in the loyalty program.
programId int Unique ID of the loyalty program in which you want to enroll.
tierNumber int Sequence number of the tier that you want to allocate to the customer. For example, 1 for the lowest tier, 2 for the subsequent tier, and so on.
loyaltyPoints int Loyalty points to credit in customer’s account.
tierExpiryDate date-time Expiry date and time of the specified tier. Supported Format: YYYY-MM-DDTHH:MM:SS+/-(time-zone).
pointsExpiryDate date-time Expiry date and time of the points issued. Supported Format: YYYY-MM-DDTHH:MM:SS+/-(time-zone).
hierarchyCode string Unique code of the hierarchy to associate with the customer/company.
roleCode string Pre defined role code.
childCustomers obj Details of child customers.
profiles obj Details of the customer to associate.
Firstname string First name of the customer.
Lastname string Last name of the customer.
identifiers* obj Identifiers of the customer in type and value.
type enum Type of the customer identifier. Values: mobile, email, externalId, wechat,martjackId, fbId mobile, tmall_uname, cuid, ali_uname, jd_uname, vip_uname, mobilePush, and line, and card (to issue loyalty card to the customers through registration).
value string Value of the specified identifier. For the type card, value is card number.
commChannels obj Available communication channels of the customer. Value: mobile, email, wechat, ios, android, line, mobilePush.
Firstname string First name of the customer.
Lastname string Last name of the customer.
createDate date-time Time and date of registration in YYYY-MM-DDTHH:MM:SS+HH:MM format. Example: 2016-06-23T19:11:18+08:00
associatedWith string The TILL code associated with the customer registration.
extendedFields obj Customer level extended field details of the customer in key:value pairs. You can only pass extended fields that are enabled for your org with the respective datatypes for values.
fields obj Custom field details of customers in key-value pairs.
fleetCompany obj Details of
externalId string External ID of the company.

Get Customers (Group Loyalty)

Retrieves all child customers for a parent customer.

Sample Request

http://eu.api.capillarytech.com/v2/customers/bulk?source=WECHAT&accountId=WECHAT-CM&associationEntityType=parentCustomer&associationEntityIdentifierType=mobile&associationEntityIdentifierValue=917169721931&limit=10&offset=0&sortOrder=DESC

Sample Response

{
   "entity":{
      "customers":[
         {
            "profiles":[
               {
                  "firstName":"Capillary",
                  "lastName":"Customer",
                  "fields":{
                     "gender":"MALE"
                  },
                  "identifiers":[
                     {
                        "type":"cardnumber",
                        "value":"regcm0000000000182418"
                     },
                     {
                        "type":"cuid",
                        "value":"cuid_91677872472"
                     },
                     {
                        "type":"unionId",
                        "value":"unionId_91677872472"
                     }
                  ],
                  "commChannels":[
                     {
                        "type":"email",
                        "value":"91677872472@mail.com",
                        "primary":true,
                        "verified":true,
                        "meta":{
                           "residence":false,
                           "office":false
                        },
                        "attributes":{

                        }
                     }
                  ],
                  "source":"WECHAT",
                  "userId":409967645,
                  "accountId":"WECHAT-CM",
                  "conflictingProfileList":[

                  ],
                  "autoUpdateTime":"2021-07-30T16:43:25+05:30",
                  "identifiersAll":[
                     {
                        "type":"cardnumber",
                        "value":"regcm0000000000182418"
                     },
                     {
                        "type":"cuid",
                        "value":"cuid_91677872472"
                     },
                     {
                        "type":"unionId",
                        "value":"unionId_91677872472"
                     }
                  ]
               }
            ],
            "extendedFields":{
               "city":"city_6878387",
               "gender":"Male"
            }
         },
         {
            "profiles":[
               {
                  "firstName":"Capillary",
                  "lastName":"Customer",
                  "fields":{
                     "gender":"MALE"
                  },
                  "identifiers":[
                     {
                        "type":"cardnumber",
                        "value":"regcm0000000000182417"
                     },
                     {
                        "type":"unionId",
                        "value":"unionId_915610000000"
                     },
                     {
                        "type":"cuid",
                        "value":"cuid_915610000000"
                     }
                  ],
                  "commChannels":[
                     {
                        "type":"email",
                        "value":"915610000000@mail.com",
                        "primary":true,
                        "verified":true,
                        "meta":{
                           "residence":false,
                           "office":false
                        },
                        "attributes":{

                        }
                     }
                  ],
                  "source":"WECHAT",
                  "userId":409967644,
                  "accountId":"WECHAT-CM",
                  "conflictingProfileList":[

                  ],
                  "autoUpdateTime":"2021-07-30T16:43:25+05:30",
                  "identifiersAll":[
                     {
                        "type":"cardnumber",
                        "value":"regcm0000000000182417"
                     },
                     {
                        "type":"unionId",
                        "value":"unionId_915610000000"
                     },
                     {
                        "type":"cuid",
                        "value":"cuid_915610000000"
                     }
                  ]
               }
            ],
            "extendedFields":{
               "city":"city_6878387",
               "gender":"Male"
            }
         }
      ],
      "count":2,
      "errors":[

      ],
      "warnings":[

      ]
   },
   "warnings":[

   ],
   "errors":[

   ],
   "success":true
}

Resource Information

URI customers/bulk?{queryParam}={paramValue}
Authentication Yes
HTTP Method GET
Batch Support Yes

Request URL

{host}/v2/customers/bulk?{queryParam}={paramValue}

Request Query Parameters

Parameter Datatype Description
source* enum Source from which you want to fetch customer details. Values: FACEBOOK, WEB_ENGAGE, WECHAT, INSTORE, MARTJACK, TMALL, TAOBAO, JD, ECOMMERCE, WEBSITE, LINE, ALL
accountId** string Account ID for sources with multiple accounts. This is required for required for sources with multiple accounts such as WeChat or Facebook.
associationEntityType enum Pass parentCustomer.
associationEntityIdentifierType enum Identifier type used for parent customer. Value: mobile, email, externalId, cardnumber, wechat, martjackId, fbId.
associationEntityIdentifierValue string Value of the parent customer.
limit int Limit the number of results to retrieve.
sortBy enum Lets you sort the list by created date, createdon or last updated date, lastUpdatedOn.
sortOrder enum Sort the results in ascending, ASC or descending, DESC order of sortBy

Sample Request

http://eu.api.capillarytech.com/v2/customers/search?limit=10&offset=0&q=tom

Sample Response

{
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 33
  },
  "data": [
    {
      "userId": 261504789,
      "matchedIdentifiers": [
        {
          "idType": "firstName",
          "idValue": "Tom",
          "source": "INSTORE",
          "accountId": ""
        }
      ],
      "profiles": [
        {
          "source": "INSTORE",
          "firstName": "Tom",
          "lastName": "Sawyer"
        }
      ]
    },
    {
      "userId": 261506099,
      "matchedIdentifiers": [
        {
          "idType": "firstName",
          "idValue": "Tom",
          "source": "INSTORE",
          "accountId": ""
        }
      ],
      "profiles": [
        {
          "source": "INSTORE",
          "firstName": "Tom",
          "lastName": "Sawyer"
        }
      ]
    },
    {
      "userId": 261504579,
      "matchedIdentifiers": [
        {
          "idType": "firstName",
          "idValue": "Tom",
          "source": "INSTORE",
          "accountId": ""
        }
      ],

      "profiles": [
        {
          "source": "INSTORE",
          "firstName": "Tom",
          "lastName": "Sawyer"
        }
      ]
    },
    {
      "userId": 261506077,
      "matchedIdentifiers": [
        {
          "idType": "firstName",
          "idValue": "Tom",
          "source": "INSTORE",
          "accountId": ""
        }
      ],
      "profiles": [
        {
          "source": "INSTORE",
          "firstName": "Tom",
          "lastName": "Sawyer"
        }
      ]
    }
  ],
  "warnings": [],
  "errors": []
}

Allows fetching customers from all sources using query string. For example, you can fetch customers whose identifiers starting with 99455, or name that starts with ‘john’ and so on.

Resource Information

URI `/search?q={search keyword}‘
Authentication Yes
HTTP Method GET
Batch Support No

Request URL

{host}/v2/customers/search?q={search keyword}

Request Parameter

Parameter Description
q Enter the keyword based on which you want to fetch customers. It will fetch customers whose first name, last name, or registered identifiers start with keyword that you pass.

Fetch Customer ID

Sample Request


https://eu.api.capillarytech.com/v2/customers/lookup?source=INSTORE&identifierName=mobile&identifierValue=919111111111

Sample Response

# Entity is the unique id of the customer

{
"entity": 306,
"warnings":[]
}

Lets you fetch unique ID of a customer generated internally. This is required for customer related activities such as fetch customer details, update customer details, manage subscription details and other activities.

Resource Information

URI `/lookup?{query parameters}’
Authentication Yes
HTTP Method GET
Batch Support No

Request URL

{host}/v2/customers/lookup?source={SourceName}&accountId={accountId}&identifierName={IdentifierName}&identifierValue={IdentifierValue}

Request Query Parameters

Parameter Datatype Description
source* enum Specify the source from which you want to fetch the customer details. Values: FACEBOOK, WEB_ENGAGE, WECHAT, INSTORE, MARTJACK, TMALL, TAOBAO, JD, ECOMMERCE, WEBSITE, LINE, ALL.
accountId string Specify the account id of the specific source if the source has multiple accounts. accountId is required for sources with multiple accounts such as WeChat or Facebook.
identifierName* enum Identifier based on which you want to fetch the customer id. Values: mobile, email, externalId, cardnumber, wechat, martjackId,fbId.
identifierValue* string Pass the respective identifier value.

Error Codes

CODE DESCRIPTION
8015 No customer found with the given identifier.
8065 No customer found in the given source with the given identifier.
8045 Account id is not passed.
8013 Customer identifier is invalid. Also check if the parameter identifierName is passed correctly.
8011 Invalid source account passed.

Fetch Customer Details (by User ID)

Sample Request

https://eu.api.capillarytech.com/v2/customers/17742?source=WECHAT&accountId=22232

Sample Response

{
   "id": 17742,
   "profiles": [
       {
           "firstName": "Tom",
           "lastName": "Sawyer",
           "attribution": {
               "createDate": "2016-06-23T19:11:18+08:00",
               "createdBy": {
                   "code": "rr.till",
                   "description": "",
                   "name": "rr.till",
                   "type": "TILL"
               },
               "modifiedBy": {
                   "code": "rr.till",
                   "description": "",
                   "name": "rr.till",
                   "type": "TILL"
               },
               "modifiedDate": "2016-08-12T18:50:23+08:00"
           },
           "fields": {
               "Gender": "Male",
               "Favorite Color": "Green"
           },
           "identifiers": [
               {
                   "type": "line",
                   "value": "lineAS6"
               },
               {
                   "type": "cardNumber",
                   "value": "TTM001110000000002ZS",
                   "seriesId": 19,
                   "statusLabel": "ACTIVE"
               },
               {
                   "type": "email",
                   "value": "tom.sawyer@example.com"
               }
           ],
           "commChannels": [
               {
                   "type": "wechat",
                   "value": "ojOPTwFOX-aBmdRlE9MHptPjt2w19",
                   "primary": true,
                   "verified": true,
                   "meta": {
                       "residence": false,
                       "office": false
                   }
               }
           ],
           "source": "WECHAT",
           "userId": 17742,
           "conflictingProfileList": [
           ],
           "autoUpdateTime": "2016-08-12T18:50:23+08:00"
       }
   ],
   "loyaltyInfo": {
       "loyaltyType": "non_loyalty",
       "attributionV2": {
           "createDate": "2016-06-23T19:11:18+08:00",
           "createdBy": {
               "code": "rr.till",
               "name": "rr.till"
           },
           "modifiedBy": {
               "code": "rr.till",
               "name": "rr.till"
           },
           "modifiedDate": "2016-08-12T18:50:23+08:00"
       },
       "lifetimePurchases": 230
   },
   "segments": {
   },
     "extendedFields": {
        "city": "Bangalore",
        "gender": "Male"
    },
   "warnings": [
   ]
}

When embed=“points”

"pointsSummary": {
"adjusted": 0.0, 
"cumulativePurchases": 0.0, 
"currentSlab": "Platinum", 
"expired": 0.0, 
"lifetimePoints": 0.0, 
"loyaltyId": 51373283, 
"loyaltyPoints": 0.0, 
"nextSlab": "", 
"nextSlabDescription": "", 
"nextSlabSerialNumber": -1, 
"redeemed": 0.0, 
"returned": 0.0, 
"slabExpiryDate": "2116-12-07T23:59:59+05:30", 
"slabSNo": 3
}

When embed=“subscriptions”

...

"subscriptionInfo": {
        "subscriptions": [
            {
                "channel": "EMAIL",
                "priority": "TRANS",
                "type": "OPTIN"
            },
            {
                "channel": "SMS",
                "priority": "TRANS",
                "type": "OPTIN"
            },
            {
                "channel": "ANDROID",
                "priority": "TRANS",
                "type": "OPTIN"
            },
            {
                "channel": "IOS",
                "priority": "TRANS",
                "type": "OPTIN"
            },
            {
                "channel": "EMAIL",
                "priority": "BULK",
                "type": "OPTIN"
            },
            {
                "channel": "SMS",
                "priority": "BULK",
                "type": "OPTIN"
            },
            {
                "channel": "ANDROID",
                "priority": "BULK",
                "type": "OPTIN"
            },
            {
                "channel": "IOS",
                "priority": "BULK",
                "type": "OPTIN"
            }
        ],
...

When embed=mlp, you will see the details of each loyalty program of the customer.

...
"loyaltyProgramDetails": [
        {
            "redeemed": 8600,
            "expired": 100,
            "returned": 500,
            "adjusted": 0,
            "lifetimePoints": 10500,
            "loyaltyPoints": 1000,
            "cumulativePurchases": 103000,
            "loyaltyId": 52350728,  
            "currentSlab": "Silver",
            "nextSlab": "Gold",
            "nextSlabSerialNumber": 3,
            "nextSlabDescription": "Gold tier",
            "slabSNo": 2,
            "slabExpiryDate": "2118-12-29T23:59:59+05:30",
            "programId": 1219
        },
        {
            "redeemed": 100,
            "expired": 0,
            "returned": 10,
            "adjusted": 0,
            "lifetimePoints": 400,
            "loyaltyPoints": 300,
            "cumulativePurchases": 8800,
            "loyaltyId": 52350728,
            "currentSlab": "Tier1",
            "nextSlab": "Tier2",
            "nextSlabSerialNumber": -1,
            "nextSlabDescription": "",
            "slabSNo": 1,
            "slabExpiryDate": "2118-12-29T23:59:59+05:30",
            "programId": 1223
        }
    ],
...

embed=promotionalPoints, to see the summary of customer’s promotional points

...
"promotionalPoints": {
        "customerPromotionType": [
            {
                "points": 200.0,
                "issuedAt": {
                    "code": "store",
                    "name": "store 10"
                },
                "issuedOn": "2019-12-12T11:23:03+05:30",
                "expiryDate": "2020-12-31T23:59:59+05:30",
                "promotionSource": {
                    "promotionSourceId": -1,
                    "promotionSourceType": "GOODWILL"
                },
                "programId": 1016,
                "promotionName": "Goodwill Promotion"
            },
            {
                "points": 34.0,
                "issuedAt": {
                    "code": "store",
                    "name": "store 10"
                },
                "issuedOn": "2019-10-31T14:49:51+05:30",
                "expiryDate": "2020-10-31T23:59:59+05:30",
                "promotionSource": {
                    "promotionSourceId": -1,
                    "promotionSourceType": "GOODWILL"
                },
                "programId": 1016,
                "promotionName": "Goodwill Promotion"
            },
            {
                "points": 32.0,
                "issuedAt": {
                    "code": "store",
                    "name": "store 10"
                },
                "issuedOn": "2019-10-31T14:49:03+05:30",
                "expiryDate": "2020-10-31T23:59:59+05:30",
                "promotionSource": {
                    "promotionSourceId": -1,
                    "promotionSourceType": "GOODWILL"
                },
                "programId": 1016,
                "promotionName": "Goodwill Promotion"
            }
        ],
        "transactionPromotionType": [],
        "lineitemPromotionType": []
    },

...

Retrieves details of a specific customer such as:

Resource Information

URI `/{customerId}‘
Authentication Yes
HTTP Method GET
Batch Support No

Request URL

{host}/v2/customers/{customerId}?source={sourceName}&accountId={accountId}

To fetch customer details from a specific account of a source (source with multiple accounts), you need to provide the respective account id.

Additional Header

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

Request Query Parameters

Parameter Datatype Description
id* int Unique identifier of the customer that you want to fetch.
source* enum Pass the source from which you want to fetch details. Value: INSTORE, MARTJACK, WECHAT, ALL ( to fetch details from all sources. For sources with multiple accounts, you also need to pass the specific accountId.
accountId string For sources with multiple accounts, pass the specific accountId.
embed enum To include the details of a specific entity in response. Value: points, subscriptions, mlp (multi-loyalty program details), promotionalPoints, expirySchedules, expiredPoints. For example, embed=expiredPoints retrieves the summary of expired points of the customer.
Usage: {host}/v2/customers/{CustomerId}/source=INSTORE&&embed=points.

Error Codes

Code Description
8069 The customer is merged into another account.
8065 No customer found in the given source with the given identifier.
8015 No customer found with the given identifier.
8063 Unable to fetch segmentation details.
8062 Unable to fetch loyalty points.
8045 Account id is not passed.
8012 Invalid source passed.

Fetch Customer Loyalty Details

Sample Request

http://eu.api.capillarytech.com/v2/customers/29372667/loyaltyDetails

Sample Response

{
    "data": [
        {
            "redeemed": 40.11,
            "expired": 0.0,
            "returned": 0.0,
            "adjusted": 0.0,
            "lifetimePoints": 1050.0,
            "loyaltyPoints": 1009.89,
            "cumulativePurchases": 9500.0,
            "loyaltyId": 86637581,
            "currentSlab": "SILVER",
            "nextSlab": "GOLD",
            "nextSlabSerialNumber": 2,
            "nextSlabDescription": "GOLD",
            "slabSNo": 1,
            "slabExpiryDate": "2120-11-10T23:59:59+05:30",
            "programId": 622,
            "delayedPoints": 0.0,
            "delayedReturnedPoints": 250.0,
            "totalAvailablePoints": 1009.89,
            "totalReturnedPoints": 250.0,
            "linkedPartnerPrograms": [
                {
                    "partnerProgramId": 5,
                    "partnerProgramName": "1stProgram",
                    "partnerProgramDescription": "1stProgram",
                    "partnerTierNumber": 1,
                    "partnerTierName": "1stSlab",
                    "partnerTierExpiryDate": "2022-12-29T23:59:59+05:30",
                    "partnerMembershipId": "916215776456",
                    "partnerProgramType": "EXTERNAL",
                    "tierBased": true
                },
                {
                    "partnerProgramId": 11,
                    "partnerProgramName": "NoTierPartnerProgram",
                    "partnerProgramDescription": "NoTierPartnerProgram",
                    "partnerMembershipId": "916215776456",
                    "partnerProgramType": "EXTERNAL",
                    "tierBased": false
                }
            ]
        }
    ],
    "warnings": [],
    "errors": []
}

Retrieves the loyalty information of a customer across all loyalty programs of the org . You can also fetch details of a specific loyalty program.

Resource Information

URI /{customerId}/loyaltyDetails
Authentication Yes
HTTP Method GET
Batch Support No

Request URL

{host}/v2/customers/{customerId}/loyaltyDetails

Request Parameters

Parameter Description
customerId* It is the unique ID that is generated internally for a customer. Pass the unique id of a customer whose loyalty details you want to fetch
programId Pass the loyalty program ID to get details of that particular program (Applicable only if the org has multiple loyalty programs). Pass the id of the program that you want to fetch.

Update Subscription Details

Sample Request


https://eu.api.capillarytech.com/v2/customers/17742/subscriptions

Sample POST Request


{
    "communicationId": -1,
    "campaignId": -1,
    "reason": "Example reason",
    "scope": {
        "scope": "USER", 
        "subScope": "NONE"
    }, 
    "subscriptions": [
        {
            "channel": "EMAIL",
            "accountId": "",
            "priority": "BULK",
            "type": "OPTOUT",
            "orgUnitId": 200031782,
            "sourceName": "INSTORE"
        },
        {
            "channel": "MOBILE",
            "accountId": "",
            "priority": "BULK",
            "type": "OPTOUT",
            "orgUnitId": 200031782,
            "sourceName": "INSTORE"
        }, 
        {
            "channel": "EMAIL",
            "accountId": "",
            "priority": "TRANS",
            "type": "OPTIN",
            "orgUnitId": 200031782,
            "sourceName": "INSTORE"
        },
        {
            "channel": "MOBILE",
            "accountId": "123",
            "priority": "TRANS",
            "type": "OPTIN",
            "orgUnitId": 200031782,
            "sourceName": "WECHAT"
        }
    ]
}

Sample Response

{
  "scope": {
    "scopeId": 0,
    "scope": "USER",
    "subScope": "NONE",
    "setCreatedOn": false,
    "setPriority": false,
    "setScopeId": false,
    "setScope": true,
    "setSubScope": true
  },
  "subscriptions": [
    {
      "channel": "EMAIL",
      "accountId": "",
      "priority": "BULK",
      "type": "OPTOUT"
    },
    {
      "channel": "EMAIL",
      "accountId": "",
      "priority": "TRANS",
      "type": "OPTIN"
    },
    {
      "channel": "SMS",
      "accountId": "123",
      "priority": "TRANS",
      "type": "OPTIN"
    }
  ],
  "campaignId": -1,
  "communicationId": -1,
  "reason": "Sample reason",
  "warnings": []
}

Subscription represents communication channels to which a customer has subscribed. Capillary supports the following channels - mobile, email, wechat, whatsapp, ios, android, and line.

This API allows updating (opt-in or opt-out) subscription status of transactional and bulk messaging services for a customer.

Resource Information

URI /{customerId}/subscriptions
Authentication Yes
HTTP Method POST
Batch Support No

Request URL

{host}/v2/customers/{customerId}/subscriptions

Request Parameters

Parameter Description
customerId* Unique ID of the customer whose subscription details you want to modify
channel Pass the communication channel that you want to update. Value: mobile, email, wechat, whatsapp, ios, android, and line.
priority Type of service for which you want to modify the subscription details.TRANS for personalized messages and BULK for campaign or bulk messages
type OPTIN to subscribe and OPTOUT to unsubscribe.
orgUnitId long
sourceName Source in which the identifier is registered. Values: INSTORE, FACEBOOK, WEB_ENGAGE, WECHAT, INSTORE, MARTJACK, TMALL, TAOBAO, JD, ECOMMERCE, WEBSITE, LINE, MOBILE_APP.

Retrieve Subscription Details

Sample Request

https://eu.api.capillarytech.com/v2/customers/17742/subscriptions

Sample Response


{
   "subscriptions": [
       {
           "channel": "EMAIL",
           "priority": "TRANS",
           "type": "OPTIN"
       },
       {
           "channel": "SMS",
           "priority": "TRANS",
           "type": "OPTIN"
       },
       {
           "channel": "EMAIL",
           "priority": "BULK",
           "type": "OPTIN"
       },
       {
           "channel": "SMS",
           "priority": "BULK",
           "type": "OPTIN"
       }
   ],
   "campaignId": 0,
   "communicationId": 0,
   "warnings": [
   ]
}

Allows retrieving the subscription details of a customer to SMS, email and WeChat. The status will be OPTIN for subscribed and OPTOUT for unsubscribed.

Entry Description
URI /{customerId}/subscriptions
Rate Limited? Yes
Authentication Yes
HTTP Method GET
Batch Support No

Request URL

{host}/v2/customers/{customerId}/subscriptions

Request Query Parameters

Parameter Description
id* Pass the unique ID of the customer to fetch the subscription details

Get Points Transfer Summary of Customer

Retrieves points transfer summary of a customer. Points transfer summary consists of points that are transferred from the customer account to another customer’s account (Deduction) or points that are received from another customer’s account (Addition).

Sample Request

https://eu.api.capillarytech.com/v2/customers/343015431/pointsTransfers

Sample Response

{ 
   "data":[ 
      { 
         "pointsTransferDate":"2019-10-16 15:53:42",
         "pointsTransferred":15.0,
         "transferId":100,
         "transferType":"DEDUCTION",
         "transferredFrom":{ 
            "userId":343015431,
            "firstName":"Tom",
            "lastName":"Sawyer"
         },
         "transferredTo":{ 
            "userId":343015432,
            "firstName":"James",
            "lastName":"Thomas"
         },
         "notes":"",
         "programName":"Nightly_ApiAutoDefaultProgram"
      },
      { 
         "pointsTransferDate":"2019-10-26 10:23:42",
         "pointsTransferred":5.0,
         "transferId":100,
         "transferType":"ADDITION",
         "transferredFrom":{ 
            "userId":343015432,
            "firstName":"James",
            "lastName":"Thomas"
         },
         "transferredTo":{ 
            "userId":343015431,
            "firstName":"Tom",
            "lastName":"Sawyer"
         },
         "notes":"",
         "programName":"Nightly_ApiAutoDefaultProgram"
      }
   ],
   "warnings":[ 

   ],
   "errors":[ 

   ]
}

Resource Information

URI /{userId}/pointsTransfers
Rate Limited? No
Authentication Yes
HTTP Methods GET
Batch Support No

Request URL

{host}/v2/customers/{userId}/pointsTransfers

Request Query Parameters

Parameter Type Description
userId* int Unique ID of the customer whose points transfer summary needs to fetch.

Get Change Requests

Retrieves the summary of change in identifiers and other details such as email ID, mobile number, external ID, account merge, address change, mobile number reallocation, tier, and retro transactions.

Sample Request

http://us.api.capillarytech.com/v2/customers/368881003/retroRequest

Sample Response

{
    "pagination": {
        "limit": 10,
        "offset": 0,
        "total": 5
    },
    "data": [
        {
            "id": 5,
            "status": "REJECTED",
            "addedBy": {
                "id": 15091433,
                "code": "till.india1",
                "description": "",
                "name": "till.india1",
                "type": "TILL",
                "adminType": "GENERAL",
                "isActive": true,
                "isOuEnabled": false,
                "timeZoneId": 0,
                "currencyId": 0,
                "languageId": 0
            },
            "addedByParent": {
                "id": 15091431,
                "code": "store_india",
                "description": "",
                "name": "StoreIndia",
                "type": "STORE",
                "adminType": "GENERAL",
                "isActive": true,
                "isOuEnabled": false,
                "timeZoneId": 0,
                "currencyId": 23,
                "languageId": 148
            },
            "updatedBy": {
                "id": 8730028,
                "code": "Patel",
                "name": "Nayan Kumar",
                "type": "ADMIN_USER",
                "adminType": "GENERAL",
                "isActive": true,
                "isOuEnabled": false,
                "timeZoneId": 0,
                "currencyId": 0,
                "languageId": 0
            },
            "addedOn": "2015-07-22T15:48:15+05:30",
            "updatedOn": "2015-10-13T16:04:38+05:30",
            "userId": 9113108,
            "requestId": 116681,
            "baseType": "RETRO",
            "reason": "_memcare(\"Insufficient validation from requestor d",
            "comments": "操作已失败于服务器。错误讯",
            "transactionId": 2866,
            "warnings": [
            ],
            "reqAdd": true,
            "oneStep": false
        },
        {
            "id": 4,
            "status": "APPROVED",
            "addedBy": {
                "id": 15091433,
                "code": "till.india1",
                "description": "",
                "name": "till.india1",
                "type": "TILL",
                "adminType": "GENERAL",
                "isActive": true,
                "isOuEnabled": false,
                "timeZoneId": 0,
                "currencyId": 0,
                "languageId": 0
            },
            "addedByParent": {
                "id": 15091431,
                "code": "store_india",
                "description": "",
                "name": "StoreIndia",
                "type": "STORE",
                "adminType": "GENERAL",
                "isActive": true,
                "isOuEnabled": false,
                "timeZoneId": 0,
                "currencyId": 23,
                "languageId": 148
            },
            "updatedBy": {
                "id": 8730028,
                "code": "Patel",
                "name": "Nayan Kumar",
                "type": "ADMIN_USER",
                "adminType": "GENERAL",
                "isActive": true,
                "isOuEnabled": false,
                "timeZoneId": 0,
                "currencyId": 0,
                "languageId": 0
            },
            "addedOn": "2019-07-22T15:47:22+05:30",
            "updatedOn": "2019-10-13T16:12:54+05:30",
            "userId": 9113108,
            "requestId": 116679,
            "baseType": "RETRO",
            "reason": "",
            "comments": "",
            "transactionId": 2865,
            "warnings": [
            ],
            "reqAdd": true,
            "oneStep": false
        },
        {
            "id": 2,
            "status": "APPROVED",
            "addedBy": {
                "id": 15091433,
                "code": "till.india1",
                "description": "",
                "name": "till.india1",
                "type": "TILL",
                "adminType": "GENERAL",
                "isActive": true,
                "isOuEnabled": false,
                "timeZoneId": 0,
                "currencyId": 0,
                "languageId": 0
            },
            "addedByParent": {
                "id": 15091431,
                "code": "store_india",
                "description": "",
                "name": "StoreIndia",
                "type": "STORE",
                "adminType": "GENERAL",
                "isActive": true,
                "isOuEnabled": false,
                "timeZoneId": 0,
                "currencyId": 23,
                "languageId": 148
            },
            "updatedBy": {
                "id": 15091437,
                "code": "till.sg",
                "description": "",
                "name": "till.sg",
                "type": "TILL",
                "adminType": "GENERAL",
                "isActive": true,
                "isOuEnabled": false,
                "timeZoneId": 0,
                "currencyId": 23,
                "languageId": 148
            },
            "addedOn": "2019-07-22T14:20:56+05:30",
            "updatedOn": "2019-07-22T14:27:20+05:30",
            "userId": 9113108,
            "requestId": 116668,
            "baseType": "RETRO",
            "transactionId": 2862,
            "warnings": [
            ],
            "reqAdd": true,
            "oneStep": false
        }
    ],
    "warnings": [
    ],
    "errors": [
    ]
}

Resource Information

URI /{customerId}/retroRequest?{query parameters}
Rate Limited? Yes
Authentication Yes
Response Formats JSON
HTTP Method GET
Batch Support No

Request URL

{host}/v2/customers/{customerId}/retroRequest?{queryParameters}

Request Query Parameters

Parameter Type Description
changeType enum Lets you filter requests by type. Value: EMAIL (for email id changes), MOBILE (for mobile number change history), EXTERNAL_ID (for external ID change history), MERGE (for account merge history), ADDRESS (for address change history), MOBILE_REALLOC (for mobile reallocations), COUPON, POINTS, TIER (for tier change history), and RETRO (for retro transactions).
startDate string Filter results by date-range. Pass the start date in YYYY-MM-DD format.
endDate string Filter results by date-range. Pass the end date in YYYY-MM-DD format.
startId long Filter results by sequence ID (sequence in which a change happened). For example, get lists from startId 200
endId long Filter results by sequence ID (sequence in which a change happened). For example, get lists from startId 200 until endId 400.
offset long Number of rows that you want omit from showing.
limit int Pass the number of results that you want to see.

Get Identifier Change Requests

Retrieves the details of identifiers (mobile number/email ID/external ID)change requests. You can also fetch change requests of a specific identifier type using the query parameters.

Sample Request

https://eu.api.capillarytech.com/v2/customers/130238908/changeRequest?source=INSTORE

Sample Response

{
    "pagination": {
        "limit": 10,
        "offset": 0,
        "total": 1
    },
    "data": [
        {
            "id": 560739,
            "status": "APPROVED",
            "addedBy": {
                "id": 75030996,
                "code": "1552291147_",
                "description": "",
                "name": "Henry",
                "type": "ADMIN_USER",
                "adminType": "GENERAL",
                "isActive": true,
                "isOuEnabled": false,
                "timeZoneId": 0,
                "currencyId": 0,
                "languageId": 0
            },
            "updatedBy": {
                "id": 75030996,
                "code": "1552291147",
                "description": "",
                "name": "Henry",
                "type": "ADMIN_USER",
                "adminType": "GENERAL",
                "isActive": true,
                "isOuEnabled": false,
                "timeZoneId": 0,
                "currencyId": 0,
                "languageId": 0
            },
            "addedOn": "2020-02-12T09:58:41Z",
            "updatedOn": "2020-02-12T09:58:41Z",
            "userId": 130238908,
            "changeType": "EMAIL",
            "changeIdentifiers": {
                "add": [
                    {
                        "type": "EMAIL",
                        "value": "iwan.gold@example.com"
                    }
                ],
                "remove": [
                    {
                        "type": "EMAIL",
                        "value": "dore.gold@example
                        .com"
                    }
                ]
            },
            "comments": "auto approved by 75030996",
            "secUserId": 0,
            "oneStep": false
        }
    ],
    "warnings": [],
    "errors": []
}

Resource Information

URI /{customerId}/changeRequest
Authentication Yes
HTTP Method GET
Batch Support No

Request URL

`{host}/v2/customers/{customerId}/changeRequest?queryParams

Request Query Parameters

Parameter Datatype Description
customerId* long Unique ID of the customer to get the details of change requests.
offset int Fetches change requests > the offset number. Offset is the position of the lead in the db record. The value is assigned based on the sequence of creation. . For example, offset=10 retrieves all the leads from record number 11.
source enum Source in which want to fetch details. Values: INSTORE, FACEBOOK, WEB_ENGAGE, WECHAT, MARTJACK, TMALL, TAOBAO, JD, ECOMMERCE, WEBSITE, LINE, MOBILE_APP. For sources with multiple accounts such as WECHAT, FACEBOOK, MOBILE_APP, or LINE,
changeType enum Fetch details of a specific identifier change. Values: EMAIL, MOBILE, EXTERNAL_ID, MERGE, MOBILE_REALLOC, COUPON, POINTS, TIER, RETRO.
limit int Limit the number of results to retrieve.
sortBy enum Lets you sort the list by created date, createdon or last updated date, lastUpdatedOn.
sortOrder Sort the results in ascending, ASC or descending, DESC order of sortBy
startDate date-time Fetch change requests added on or after a specific date. Pass the date in YYYY-MM-DD format.
endDate date-time Fetch change requests added on or before a specific date. Pass the date in YYYY-MM-DD format.
startId long Fetch change requests greater than or equal to a specific request ID range.
endId long Fetch change requests less than or equal to a specific request ID range.

Get Customer Goodwill Requests

Retrieves the history of goodwill points of a customer.

Sample Request

http://api.capillary.co.in/v2/customers/343040815/goodwillRequest

Sample Response

{
    "pagination": {
        "limit": 10,
        "offset": 0,
        "total": 2
    },
    "data": [
        {
            "id": 43114,
            "addedBy": {
                "id": 15000449,
                "code": "1371622280_919866643044",
                "description": "",
                "name": "1371622280_Ashish",
                "type": "ADMIN_USER",
                "adminType": "GENERAL",
                "isActive": true,
                "isOuEnabled": false,
                "timeZoneId": 0,
                "currencyId": 0,
                "languageId": 0
            },
            "updatedBy": {
                "id": 15000449,
                "code": "1371622280_919866643044",
                "description": "",
                "name": "1371622280_Ashish",
                "type": "ADMIN_USER",
                "adminType": "GENERAL",
                "isActive": true,
                "isOuEnabled": false,
                "timeZoneId": 0,
                "currencyId": 0,
                "languageId": 0
            },
            "addedOn": "2019-11-04T15:18:23+05:30",
            "updatedOn": "2019-11-04T15:18:23+05:30",
            "userId": 343040815,
            "requestId": 770197,
            "goodwillType": "POINTS",
            "goodwillStatus": "APPROVED",
            "comments": "sample",
            "reason": " ",
            "approvedValue": "450",
            "updatedComments": "sample; AUTO_APPROVED",
            "oneStep": false
        },
        {
            "id": 43113,
            "enteredBy": {
                "id": 15000449,
                "code": "1371622280_919866643044",
                "description": "",
                "name": "1371622280_Ashish",
                "type": "ADMIN_USER",
                "adminType": "GENERAL",
                "isActive": true,
                "isOuEnabled": false,
                "timeZoneId": 0,
                "currencyId": 0,
                "languageId": 0
            },
            "enteredBy": {
                "id": 15000449,
                "code": "1371622280_919866643044",
                "description": "",
                "name": "1371622280_Ashish",
                "type": "ADMIN_USER",
                "adminType": "GENERAL",
                "isActive": true,
                "isOuEnabled": false,
                "timeZoneId": 0,
                "currencyId": 0,
                "languageId": 0
            },
            "addedOn": "2019-11-04T15:17:55+05:30",
            "updatedOn": "2019-11-04T15:17:55+05:30",
            "userId": 343040815,
            "requestId": 770196,
            "goodwillType": "POINTS",
            "goodwillStatus": "PENDING",
            "comments": "",
            "reason": " ",
            "oneStep": false
        }
    ],
    "warnings": [],
    "errors": []
}


Resource Information

URI /{customerId}/goodwillRequest
Authentication Yes
HTTP Method GET
Batch Support No

Request URL

`{host}/v2/customers/{customerId}/goodwillRequest

Request Query Parameters

Parameter Datatype Description
currencyId* long Pass the unique ID of the customer whose goodwill request details you want to fetch.
requestId long Unique id of the goodwill request that you want to fetch.
is_one_step_change boolean Pass true to fetch goodwill points or coupon requests that are issued instantly (one step issual).
programId string Get requests of a specific loyalty program. Pass the unique loyalty program ID.
autoApprove boolean Pass true to fetch requests that are auto-approved - without the involvement of the back-end team.

Get Customer Coupons (Basic)

Retrieves the history of a customer coupons with basic coupon details.

Sample Request

http://api.capillary.co.in/v2/customers/coupons?id=401031250

Sample Response

{
   "entity":{
      "pagination":{
         "limit":"100",
         "offset":"0",
         "total":4
      },
      "customers":[
         {
            "firstname":"Tom",
            "lastname":"Sawyer",
            "mobile":"918860000001",
            "id":401031250,
            "coupons":[
               {
                  "code":"KNRYHMRW",
                  "seriesId":363653,
                  "description":"NewCouponForAll",
                  "validTill":"2029-09-01T00:00:00+05:30",
                  "discountType":"ABS",
                  "discountValue":1000.0,
                  "discountUpto":0.0,
                  "redemptionCount":0,
                  "redemptionsLeft":1,
                  "id":399000028,
                  "createdDate":"2021-09-25T16:28:11+05:30",
                  "transactionNumber":"2147877652",
                  "issuedAt":{
                     "code":"storecode",
                     "name":"webstore1"
                  },
                  "redemptions":[

                  ]
               },
               {
                  "code":"7TF6TBQB",
                  "seriesId":363653,
                  "description":"NewCouponForAll",
                  "validTill":"2029-09-01T00:00:00+05:30",
                  "discountType":"ABS",
                  "discountValue":1000.0,
                  "discountUpto":0.0,
                  "redemptionCount":0,
                  "redemptionsLeft":1,
                  "id":399000029,
                  "createdDate":"2021-09-25T16:28:11+05:30",
                  "transactionNumber":"2147877652",
                  "issuedAt":{
                     "code":"storecode",
                     "name":"webstore1"
                  },
                  "redemptions":[

                  ]
               },
               {
                  "code":"6JAFX7ZF",
                  "seriesId":363653,
                  "description":"NewCouponForAll",
                  "validTill":"2029-09-01T00:00:00+05:30",
                  "discountType":"ABS",
                  "discountValue":1000.0,
                  "discountUpto":0.0,
                  "redemptionCount":0,
                  "redemptionsLeft":1,
                  "id":399000026,
                  "createdDate":"2021-09-25T16:25:25+05:30",
                  "transactionNumber":"2147877651",
                  "issuedAt":{
                     "code":"storecode",
                     "name":"webstore1"
                  },
                  "redemptions":[

                  ]
               },
               {
                  "code":"KZWMCYTR",
                  "seriesId":14162,
                  "description":"Mobile Push offer 1",
                  "validTill":"2022-03-20T00:00:00+05:30",
                  "discountType":"PERC",
                  "discountValue":10.0,
                  "discountUpto":0.0,
                  "redemptionCount":0,
                  "redemptionsLeft":1,
                  "id":397755229,
                  "createdDate":"2021-09-01T17:53:43+05:30",
                  "transactionNumber":"2147861881",
                  "issuedAt":{
                     "code":"storecode",
                     "name":"webstore1"
                  },
                  "redemptions":[

                  ]
               }
            ]
         }
      ]
   },
   "warnings":[

   ],
   "errors":[

   ],
   "success":true
}

Resource Information

URI /v2/customers/coupons?{queryParams}
HTTP Method GET
API Version v2
Batch Support Yes
Rate Limited Yes

Request Query Parameters

Parameter Datatype Description
mobile/email/externalId/id* string Any identifier of the customer to fetch coupons. For example, id=9876547.
status enum Filter results by coupon status. Value: Active, Redeemed, Unexpired, Unredeemed, Active_Redeemed (coupon is active but redeemed), Active_Unredeemed (coupon is active but not redeemed), Expired_Redeemed (coupon is expired but redeemed),and Expired_Unredeemed (coupon is expired and not redeemed).

Response Parameters

Parameter Datatype Description
pagination obj Pagination details of the results retrieved.
     limit int Limit of results. Usually the default limit 100.
     offset int Number of records ignored from the top. Default value:0.
     total int Total number of results retrieved.
customers array-obj Details of the customer and coupons.
     firstname string First name of the customer.
     lastname string Last name of the customer.
     mobile string Registered mobile number of the customer.
     id long Unique internal ID of the customer.
     coupons array-obj Details of customer coupons.
          code string Unique coupon code.
          seriesId long Series ID associated with the coupon.
          description string Description of the coupon series.
     validTill date-time Validity of the coupon in ISO 8601 format.
          discountType enum Type of the discount. Value: absolute (ABS), or percentage ().
          discountValue float Discount amount in the org currency.
          discountUpto float Amount capping on the discount for the coupon.
          redemptionCount int Number of times the coupon is redeemed.
          redemptionsLeft int Number of redemptions left for the coupon.
          id long
          createdDate date-time
          transactionNumber string Unique transaction number.
          issuedAt obj Details of the store entity associated with the coupon.
               code string Org entity code associated with the coupon.
               name string Name of the org entity associated with the coupon.
     redemptions array Redemption IDs of the coupon (if redeemed).

Get Customer Coupons (Detailed)

Retrieves the history of a customer coupons along with the meta information.

Sample Request

http://api.capillary.co.in/v2/customers/343040815/coupons

Sample Response


{
    "entity": [
        {
            "id": 33267197,
            "seriesId": 14162,
            "series": {
                "id": 14162,
                "orgId": 50074,
                "description": "Mobile Push offer 1",
                "discountCode": "MobilePush",
                "validTillDate": "2118-09-10T16:09:02+05:30",
                "validDaysFromCreation": 30,
                "expiryStrategyValue": 200,
                "maxCreate": 1000,
                "maxRedeem": -1,
                "isTransferrable": false,
                "anyUser": false,
                "sameUserMultipleRedeem": false,
                "isReferralExistingUsersAllowed": false,
                "isMultipleUseAllowed": false,
                "isValidationRequired": false,
                "isValidWithDiscountedItem": false,
                "createdBy": 4,
                "numIssued": 78,
                "numRedeemed": 6,
                "createdOn": "2018-09-10T14:45:06+05:30",
                "lastUsed": "2019-10-31T16:47:39+05:30",
                "seriesCode": "GM0V3HXC",
                "smsTemplate": "{{full_name}} Your Coupon code {{voucher}} Expires on {{valid_days_from_create}} {{optout}}",
                "isSMSDisabled": false,
                "isUpdateProductData": false,
                "info": "Mobile Push offer 1",
                "isMultipleVouchersPerUserAllowed": true,
                "doNotResendExistingVoucher": true,
                "mutualExclusiveSeriesIds": "[]",
                "storeIdsJson": "[-1]",
                "isDvsEnabled": false,
                "dvsExpiryDate": "2019-11-30T00:00:00+05:30",
                "priority": 0,
                "shortSMSTemplate": "Hello {{cust_name}}, your voucher code is {{voucher_code}}",
                "maxVouchersPerUser": -1,
                "minDaysBetweenVouchers": -1,
                "maxReferralsPerReferee": -1,
                "discountUpto": 0,
                "discountValue": 10,
                "dvsItems": "false",
                "redemptionRange": "{\"dom\":[\"-1\"],\"dow\":[\"-1\"],\"hours\":[\"-1\"]}",
                "minBillAmount": 0,
                "maxBillAmount": 9007199254740991,
                "redeemAtStore": "[-1]",
                "campaignId": -1,
                "tag": "Mobile Push offer 1",
                "maxRedemptionsInSeriesPerUser": -1,
                "minDaysBetweenRedemption": -1,
                "redemptionValidFrom": "1970-01-01T05:30:00+05:30",
                "sourceOrgId": -1,
                "issueToLoyalty": false,
                "redeemStoreType": "redeemable_stores",
                "offlineRedeemType": false,
                "isOldFlowEnabled": false,
                "isPreRedeemEventRequired": false,
                "brands": [],
                "products": [],
                "categories": [],
                "termsAndConditions": "T&C apply",
                "signalRedemptionEvent": true,
                "syncToClient": false,
                "showPinCode": false,
                "validRedemptionOrgEntityDetails": {
                    "concepts": [],
                    "zones": [],
                    "stores": [],
                    "tills": []
                },
                "seriesType": "LOYALTY",
                "clientHandlingType": "DISC_CODE",
                "expiryStrategyType": "DAYS",
                "discountOn": "BILL",
                "discountType": "PERC",
                "dvsExpiryDateFormat": "2019-11-30",
                "updateProductData": false,
                "validTilldateFormat": "2118-09-10",
                "redemptionValidFromFormat": "1970-01-01"
            },
            "code": "ER07BCJ8",
            "description": "Mobile Push offer 1",
            "createdDate": "2019-10-31T17:15:02+05:30",
            "validTill": "2020-05-18T23:59:59+05:30",
            "isRedeemed": false,
            "issuedTo": 343040815,
            "issuedBy": 50006796,
            "orgId": 50074,
            "refId": 0,
            "issuedAt": {
                "id": 50006795,
                "code": "storecode",
                "description": "webenagestore",
                "name": "webstore1",
                "type": "STORE",
                "adminType": "GENERAL",
                "isOrgUnit": false
            },
            "status": {
                "statusCode": {
                    "status": true,
                    "code": 700,
                    "message": "Coupon Resent"
                },
                "warnings": [],
                "warningsAsStatusCode": [],
                "code": 700,
                "success": true,
                "message": "Coupon Resent"
            },
            "couponDiscountType": "PERC",
            "issuedOn": "2019-10-31T17:15:02+05:30",
            "activeFrom": "2019-10-31T00:00:00+05:30",
            "redemptionsLeft": -1,
            "couponStatus": {
                "statusCode": {
                    "status": true,
                    "code": 200,
                    "message": "Success"
                },
                "warnings": [],
                "warningsAsStatusCode": [],
                "code": 200,
                "success": true,
                "message": "Success"
            },
            "redemptionInfo": [],
            "discountType": false,
            "discountValue": 10,
            "discountUpto": 0,
            "redeemed": false,
            "seriesName": "Mobile Push offer 1",
            "trimmedCode": "ER07BCJ8"
        },
        {
            "id": 33267195,
            "seriesId": 14162,
            "series": {
                "id": 14162,
                "orgId": 50074,
                "description": "Mobile Push offer 1",
                "discountCode": "MobilePush",
                "validTillDate": "2118-09-10T16:09:02+05:30",
                "validDaysFromCreation": 30,
                "expiryStrategyValue": 200,
                "maxCreate": 1000,
                "maxRedeem": -1,
                "isTransferrable": false,
                "anyUser": false,
                "sameUserMultipleRedeem": false,
                "isReferralExistingUsersAllowed": false,
                "isMultipleUseAllowed": false,
                "isValidationRequired": false,
                "isValidWithDiscountedItem": false,
                "createdBy": 4,
                "numIssued": 78,
                "numRedeemed": 6,
                "createdOn": "2018-09-10T14:45:06+05:30",
                "lastUsed": "2019-10-31T16:47:39+05:30",
                "seriesCode": "GM0V3HXC",
                "smsTemplate": "{{full_name}} Your Coupon code {{voucher}} Expires on {{valid_days_from_create}} {{optout}}",
                "isSMSDisabled": false,
                "isUpdateProductData": false,
                "info": "Mobile Push offer 1",
                "isMultipleVouchersPerUserAllowed": true,
                "doNotResendExistingVoucher": true,
                "mutualExclusiveSeriesIds": "[]",
                "storeIdsJson": "[-1]",
                "isDvsEnabled": false,
                "dvsExpiryDate": "2019-11-30T00:00:00+05:30",
                "priority": 0,
                "shortSMSTemplate": "Hello {{cust_name}}, your voucher code is {{voucher_code}}",
                "maxVouchersPerUser": -1,
                "minDaysBetweenVouchers": -1,
                "maxReferralsPerReferee": -1,
                "discountUpto": 0,
                "discountValue": 10,
                "dvsItems": "false",
                "redemptionRange": "{\"dom\":[\"-1\"],\"dow\":[\"-1\"],\"hours\":[\"-1\"]}",
                "minBillAmount": 0,
                "maxBillAmount": 9007199254740991,
                "redeemAtStore": "[-1]",
                "campaignId": -1,
                "tag": "Mobile Push offer 1",
                "maxRedemptionsInSeriesPerUser": -1,
                "minDaysBetweenRedemption": -1,
                "redemptionValidFrom": "1970-01-01T05:30:00+05:30",
                "sourceOrgId": -1,
                "issueToLoyalty": false,
                "redeemStoreType": "redeemable_stores",
                "offlineRedeemType": false,
                "isOldFlowEnabled": false,
                "isPreRedeemEventRequired": false,
                "brands": [],
                "products": [],
                "categories": [],
                "termsAndConditions": "T&C apply",
                "signalRedemptionEvent": true,
                "syncToClient": false,
                "showPinCode": false,
                "validRedemptionOrgEntityDetails": {
                    "concepts": [],
                    "zones": [],
                    "stores": [],
                    "tills": []
                },
                "seriesType": "LOYALTY",
                "clientHandlingType": "DISC_CODE",
                "expiryStrategyType": "DAYS",
                "discountOn": "BILL",
                "discountType": "PERC",
                "dvsExpiryDateFormat": "2019-11-30",
                "updateProductData": false,
                "validTilldateFormat": "2118-09-10",
                "redemptionValidFromFormat": "1970-01-01"
            },
            "code": "H306ORH2",
            "description": "Mobile Push offer 1",
            "createdDate": "2019-10-31T17:14:49+05:30",
            "validTill": "2020-05-18T23:59:59+05:30",
            "isRedeemed": false,
            "issuedTo": 343040815,
            "issuedBy": 50006796,
            "orgId": 50074,
            "refId": 0,
            "issuedAt": {
                "id": 50006795,
                "code": "storecode",
                "description": "webenagestore",
                "name": "webstore1",
                "type": "STORE",
                "adminType": "GENERAL",
                "isOrgUnit": false
            },
            "status": {
                "statusCode": {
                    "status": true,
                    "code": 700,
                    "message": "Coupon Resent"
                },
                "warnings": [],
                "warningsAsStatusCode": [],
                "code": 700,
                "success": true,
                "message": "Coupon Resent"
            },
            "couponDiscountType": "PERC",
            "issuedOn": "2019-10-31T17:14:49+05:30",
            "activeFrom": "2019-10-31T00:00:00+05:30",
            "redemptionsLeft": -1,
            "couponStatus": {
                "statusCode": {
                    "status": true,
                    "code": 200,
                    "message": "Success"
                },
                "warnings": [],
                "warningsAsStatusCode": [],
                "code": 200,
                "success": true,
                "message": "Success"
            },
            "redemptionInfo": [],
            "discountType": false,
            "discountValue": 10,
            "discountUpto": 0,
            "redeemed": false,
            "seriesName": "Mobile Push offer 1",
            "trimmedCode": "H306ORH2"
        }
    ],
    "warnings": [],
    "errors": [],
    "success": true
}

Resource Information

URI /{customerId}/coupons
Authentication Yes
HTTP Method GET
Batch Support No

Request URL

{host}/v2/customers/{customerId}/coupons

Request Query Parameters

Parameter Datatype Description
customerId* long Unique ID of the customer to fetch coupons.

Issue Card to an Existing Customer

Lets you issue card to a loyalty customer. To issue an external or manually generated card, you need to first add the card using /v2/card API. To issue auto-generated card, you first need to issue the card using card/generate API.

Sample Request

https://eu.api.capillarytech.com/v2/customers/161670039/changeIdentifier?source=INSTORE

Sample POST Request

{
  "add": [
    {
      "value": "GOLD00000000000001032021",
      "type": "cardnumber",
      "statusLabel": "ACTIVE"
    }
  ]
}

Sample Response

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

Resource Information

URI /{userId}/changeIdentifier?
Rate Limited? Yes (1000 per hour)
HTTP Methods POST
Batch Support Yes

Request URL

{host}/v2/customers/{userId}/changeIdentifier?source={source}&accountId={accountId}

Request Query Parameter

Parameter Datatype Description
userId* long Unique ID of the customer to issue card.
source* enum Source from which the card is issued. Value: INSTORE, FACEBOOK, WEB_ENGAGE, WECHAT, INSTORE, MARTJACK, TMALL, TAOBAO, JD, ECOMMERCE, WEBSITE, LINE, MOBILE_APP.
accountId** string Unique ID of the source account. Required for sources with multiple account IDs.

Request Body Parameters

Parameter Datatype Description
value* string Card number to issue or tag to the customer.
type* enum Pass cardnumber to issue card.
statusLabel* enum New status of the card. Value: ACTIVE.

Customer Lookup

It is an extension to normal customer APIs where instead of fetching or updating details using customer ID, you can use registered identfiers like mobile number, email ID, external ID, cardnumber and so on in /customer/lookup.

Update Customer Details (using identifier)

Lets you update customer details with mobile number, email ID or external ID.

Sample Request

https://eu.api.capillarytech.com/v2/customers/lookup?source=INSTORE&identifierName=mobile&identifierValue=919999000001

Sample PUT request

{  
   "profiles":[  
      {  
         "firstName":"Tom",
         "lastName":"Sawyer",
         "fields":{  
            "gender":"Male",
            "city":"Bangalore"
         },
         "identifiers":[  
            {  
               "type":"email",
               "value":"tom.sawyer@example.com"
            },
            {  
               "type":"wechat",
               "value":"wc_2"
            }
         ],
         "commChannels":[  
            {  
               "type":"email",
               "value":"tom.sawyer@example.com",
               "primary":"true",
               "verified":"false",
               "meta":{  
                  "residence":true
               }
            },
            {  
               "type":"wechat",
               "value":"wc_2",
               "primary":"true",
               "verified":"true",
               "meta":{  
                  "residence":true
               }
            }
         ],
         "source":"WECHAT",
         "accountId":"WeChat1234"
      }
   ],
   "loyaltyInfo":{  
      "loyaltyType":"loyalty"
   },
   "extendedFields":  
      {  
         "gender":"MALE",
         "city":"Bangalore"
      },
     "loyaltyProgramEnrollments":[{
     "programId":1016,
     "tierNumber": 234,
    "loyaltyPoints": 75,
    "tierExpiryDate": "2022-02-11T16:36:17+05:30",
    "pointsExpiryDate": "2022-02-11T16:36:17+05:30"
}]

}

Sample Response

{
    "createdId": 342963216,
    "warnings": [],
    "sideEffects": []
}

Resource Information

URI /lookup?identifierName={identifierName}&identifierValue={IdentifierValue}&{queryParams}
Authentication Yes
HTTP Method PUT
Batch Support No

Request URL

For sources with single accounts

{host}/v2/customers/lookup?source={sourceName}?&accountId={accountId}&identifierName={identifierName}&identifierValue={IdentifierValue}

Request Query Parameters

Parameter Datatype Description
identifierName* enum Identifier you use to update customer details. Values: mobile, email, externalId.
identifierValue* string The respective identifier value. For example if identifierName is email, then the identifierValue needs to be the email ID of the customer.
source* enum Specify the source in which you want to update the customer details - FACEBOOK, WEB_ENGAGE, WECHAT, INSTORE, MARTJACK, TMALL, TAOBAO, JD, ECOMMERCE, WEBSITE, LINE, MOBILE_APP. For sources with multiple accounts such as WECHAT, FACEBOOK, MOBILE_APP, or LINE, you also need to provide the respective account id.
accountId** string Account in which you want to update the customer details (Required only for sources with multiple accounts)
use_async boolean Pass true to run Loyalty activities in the background, side effects will not be returned in the API response. If false, API will wait for Loyalty activities to complete and then respond to the client with side effects in the API response.

Request Body Parameters

Parameter Datatype Description
loyaltyType enum Loyalty status of the customer. Value: loyalty, non_loyalty.
commChannels obj Communication channels of the customer.
type enum Type of the communication channel. Value: mobile, email, wechat, ios, android, line, mobilePush.
value string Based on the channel type enter the channel value. Example, mobile number is the value for type:mobile, firebase token for type:mobilePush. mobilePush is supported for sources mobile_app, Instore, Martjack, Ecommerce, and Website
primary boolean Whether the current identifier is the primary identifier of the customer (primary identifier as per the org’s configuration).
lastViewedDate date Date when the customer recently opened the app. Applicable for the channel 'mobilePush’.
verified boolean Whether the current identifier is verified or not. For example, through OTP.
profiles obj Profile information of the customer.
meta obj Additional information of the identifier.
Firstname string First name of the customer.
Lastname string Last name of the customer.
identifiers obj Identifiers of the customer that you want to add in type and value. Supported types: mobile, email, externalId, wechat,martjackId, fbId mobile, tmall_uname, cuid, ali_uname, jd_uname, vip_uname, and line.
profiles fields Custom field details (only that configured for the organization)
extendedFields obj Extended field details of the customer in key:value pairs. You can only pass extended fields that are enabled for your org with the respective datatypes for values.
fields obj Custom field details of the customer in key:value pairs.
loyaltyProgramEnrollments obj Lets you enroll new customers in the loyalty program.
programId int Unique ID of the loyalty program in which you want to enroll. You cannot update details if the customer is already enrolled in the loyalty program.
tierNumber int Sequence number of the tier that you want to allocate to the customer. For example, 1 for the lower tier, 2 for the next tier, and so on.
loyaltyPoints int Loyalty points to credit in customer’s account.
tierExpiryDate date-time Expiry date and time of the specified tier. Supported Format: YYYY-MM-DDTHH:MM:SS+/-(time-zone).
pointsExpiryDate date-time Expiry date and time of the points issued. Supported Format: YYYY-MM-DDTHH:MM:SS+/-(time-zone).

Update customer status

Lets you update status label of a customer.

Sample Request

https://eu.api.capillarytech.com/v2/customers/lookup/status?source=INSTORE&identifierName=mobile&identifierValue=919999000001

Sample PUT request

{
  "reason": "testing2",
  "createdOn": "2021-09-16T12:10:45Z",
  "label": "Active"
}

Sample Response

{
   "warnings": [],
    "error": []
}

Resource Information

URI /lookup/status?identifierName={identifierName}&identifierValue={IdentifierValue}&{queryParams}
Authentication Yes
HTTP Method PUT
Batch Support No

Request URL

For sources with single accounts

{host}/v2/customers/lookup/status?source={sourceName}?&accountId={accountId}&identifierName={identifierName}&identifierValue={IdentifierValue}

Request Query Parameters

Parameter Datatype Description
identifierName* enum Identifier you use to update customer details. Values: mobile, email, externalId.
identifierValue* string The respective identifier value. For example if identifierName is email, then the identifierValue needs to be the email ID of the customer.
source* enum Specify the source in which you want to update the customer details - FACEBOOK, WEB_ENGAGE, WECHAT, INSTORE, MARTJACK, TMALL, TAOBAO, JD, ECOMMERCE, WEBSITE, LINE, MOBILE_APP. For sources with multiple accounts such as WECHAT, FACEBOOK, MOBILE_APP, or LINE, you also need to provide the respective account id.
accountId** string Account in which you want to update the customer details (Required only for sources with multiple accounts)

Request Body Parameters

Parameter Datatype Description
reason* string Reason for the update.
createdOn date-time Date and time of the status update in ISO 8601 format - YYYY-MM-DDTHH:MM:SSZ.
label* string Predefined label name to update with.

Get Customer Loyalty Details

Sample Request

http://api.capillary.co.in/v2/customers/lookup/loyaltyDetails?source=INSTORE&identifierName=externalId&identifierValue=888555888555898855

Sample Response

{
    "data": [
        {
            "redeemed": 0.0,
            "expired": 0.0,
            "returned": 0.0,
            "adjusted": 0.0,
            "lifetimePoints": 0.0,
            "loyaltyPoints": 0.0,
            "cumulativePurchases": 24000.0,
            "loyaltyId": 143032714,
            "currentSlab": "Default",
            "nextSlab": "",
            "nextSlabSerialNumber": -1,
            "nextSlabDescription": "",
            "slabSNo": 1,
            "slabExpiryDate": "2121-02-18T23:59:59+05:30",
            "programId": 1414,
            "delayedPoints": 0.0,
            "delayedReturnedPoints": 0.0,
            "totalAvailablePoints": 0.0,
            "totalReturnedPoints": 0.0,
            "linkedPartnerPrograms": []
        },
        {
            "redeemed": 0.0,
            "expired": 0.0,
            "returned": 0.0,
            "adjusted": 0.0,
            "lifetimePoints": 0.0,
            "loyaltyPoints": 0.0,
            "cumulativePurchases": 0.0,
            "loyaltyId": 143032714,
            "currentSlab": "Base",
            "nextSlab": "bbstar",
            "nextSlabSerialNumber": 2,
            "nextSlabDescription": "bbstar",
            "slabSNo": 1,
            "slabExpiryDate": "2121-05-08T01:20:22+05:30",
            "programId": 1679,
            "delayedPoints": 0.0,
            "delayedReturnedPoints": 0.0,
            "totalAvailablePoints": 0.0,
            "totalReturnedPoints": 0.0,
            "linkedPartnerPrograms": []
        },
        {
            "redeemed": 0.0,
            "expired": 0.0,
            "returned": 0.0,
            "adjusted": 0.0,
            "lifetimePoints": 0.0,
            "loyaltyPoints": 0.0,
            "cumulativePurchases": 0.0,
            "loyaltyId": 143032714,
            "currentSlab": "CLiQPerQ",
            "nextSlab": "Ignore",
            "nextSlabSerialNumber": 2,
            "nextSlabDescription": "Ignore",
            "slabSNo": 1,
            "slabExpiryDate": "2121-05-08T01:46:18+05:30",
            "programId": 1680,
            "delayedPoints": 0.0,
            "delayedReturnedPoints": 0.0,
            "totalAvailablePoints": 0.0,
            "totalReturnedPoints": 0.0,
            "linkedPartnerPrograms": []
        }
    ],
    "warnings": [],
    "errors": []
}

Retrieves the loyalty information of a customer across all loyalty programs of the org . You can also fetch details of a specific loyalty program.

Resource Information

URI /lookup/loyaltyDetails?{queryParams}
Authentication Yes
HTTP Method GET
Batch Support No

Request URL

{host}/v2/customers/lookup/loyaltyDetails?{paramName}={paramValue}

Request Query Parameters

Parameter Type Description
source* enum Source from which you need to fetch customer details. 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).
accountId** string For sources with multiple accounts (such as MARTJACK, WECHAT), pass the respective account ID. Not applicable for INSTORE source.
identifierName* enum Pass any of the registered identifier name of the customer. Values: mobile, email, externalId, id, wechat,martjackId, fbId (Facebook ID), cardnumber, cardExternalId.
identifierValue* string Pass the respective identifier value. For example if identifierType is mobile, identifierValue is mobile number.

Fetch Customer Details (by Identifier)

Retrieves details of a customer by any of the identifiers (mobile number, email ID, external ID, or card number).

Sample Request

https://eu.api.capillarytech.com/v2/customers/lookup/customerDetails?source=WECHAT&accountId=22232&identifierName=mobile&identifierValue=919999000001&embed=mlp

Sample Response

{
   "id":481220846,
   "profiles":[
      {
         "firstName":"",
         "lastName":"",
         "attribution":{
            "createDate":"2021-02-18T20:31:15+05:30",
            "createdBy":{
               "id":12970395,
               "code":"sit.admin",
               "name":"sit.admin",
               "type":"TILL"
            },
            "modifiedBy":{
               "id":12970395,
               "code":"sit.admin",
               "name":"sit.admin",
               "type":"TILL"
            },
            "modifiedDate":"2021-02-22T13:27:29+05:30"
         },
         "fields":{
            "ihcl_active":"true",
            "tcp_active":"true",
            "tierup_airasia":"2"
         },
         "identifiers":[
            {
               "type":"externalId",
               "value":"888555888555898855"
            },
            {
               "type":"line",
               "value":"lineAS6"
            },
            {
               "type":"cardNumber",
               "value":"TTM001110000000002ZS",
               "seriesId":19,
               "statusLabel":"ACTIVE"
            },
            {
               "type":"mobile",
               "value":"919999000001"
            }
         ],
         "commChannels":[
            {
               "type":"mobile",
               "value":"919999000001",
               "primary":true,
               "verified":false,
               "meta":{
                  "residence":false,
                  "office":false
               },
               "attributes":{

               }
            }
         ],
         "source":"INSTORE",
         "userId":481220846,
         "accountId":"",
         "conflictingProfileList":[

         ],
         "autoUpdateTime":"2021-09-14T17:53:13+05:30",
         "identifiersAll":[
            {
               "type":"externalId",
               "value":"888555888555898855"
            }
         ]
      }
   ],
   "loyaltyInfo":{
      "loyaltyType":"loyalty",
      "attributionV2":{
         "createDate":"2021-02-18T20:31:15+05:30",
         "createdBy":{
            "id":12970395,
            "code":"sit.admin",
            "name":"sit.admin",
            "type":"TILL"
         },
         "modifiedBy":{
            "id":12970395,
            "code":"sit.admin",
            "name":"sit.admin",
            "type":"TILL"
         },
         "modifiedDate":"2021-02-22T13:27:29+05:30",
         "createdFromSource":"instore"
      },
      "lifetimePurchases":24000.0
   },
   "fraudDetails":{
      "markedBy":{

      },
      "modifiedOn":"2019-09-23T15:13:14+05:30",
      "status":"NOT_FRAUD"
   },
   "segments":{

   },
   "associatedWith":"sit.admin",
   "extendedFields":{
      "city":"Bangalore",
      "gender":"Male"
   },
   "loyaltyProgramDetails":[
      {
         "redeemed":0.0,
         "expired":0.0,
         "returned":0.0,
         "adjusted":0.0,
         "lifetimePoints":0.0,
         "loyaltyPoints":0.0,
         "cumulativePurchases":24000.0,
         "loyaltyId":143032714,
         "currentSlab":"Default",
         "nextSlab":"",
         "nextSlabSerialNumber":-1,
         "nextSlabDescription":"",
         "slabSNo":1,
         "slabExpiryDate":"2121-02-18T23:59:59+05:30",
         "programId":1414,
         "delayedPoints":0.0,
         "delayedReturnedPoints":0.0,
         "totalAvailablePoints":0.0,
         "totalReturnedPoints":0.0,
         "linkedPartnerPrograms":[

         ],
         "programTitle":"Tata Digital SITDefaultProgram",
         "programDescription":"Default program for Tata Digital SIT",
         "programPointsToCurrencyRatio":1.0
      },
      {
         "redeemed":0.0,
         "expired":0.0,
         "returned":0.0,
         "adjusted":0.0,
         "lifetimePoints":0.0,
         "loyaltyPoints":0.0,
         "cumulativePurchases":0.0,
         "loyaltyId":143032714,
         "currentSlab":"Copper*",
         "nextSlab":"Copper",
         "nextSlabSerialNumber":2,
         "nextSlabDescription":"Copper",
         "slabSNo":1,
         "slabExpiryDate":"2121-05-07T23:48:47+05:30",
         "programId":1422,
         "delayedPoints":0.0,
         "delayedReturnedPoints":0.0,
         "totalAvailablePoints":0.0,
         "totalReturnedPoints":0.0,
         "linkedPartnerPrograms":[

         ],
         "programTitle":"IHCL",
         "programDescription":"IHCL",
         "programPointsToCurrencyRatio":1.0
      },
      {
         "redeemed":0.0,
         "expired":0.0,
         "returned":0.0,
         "adjusted":0.0,
         "lifetimePoints":0.0,
         "loyaltyPoints":0.0,
         "cumulativePurchases":0.0,
         "loyaltyId":143032714,
         "currentSlab":"Privilege",
         "nextSlab":"Tier 2",
         "nextSlabSerialNumber":2,
         "nextSlabDescription":"Tier 2",
         "slabSNo":1,
         "slabExpiryDate":"2121-05-07T20:44:49+05:30",
         "programId":1423,
         "delayedPoints":0.0,
         "delayedReturnedPoints":0.0,
         "totalAvailablePoints":0.0,
         "totalReturnedPoints":0.0,
         "linkedPartnerPrograms":[

         ],
         "programTitle":"Croma",
         "programDescription":"Croma",
         "programPointsToCurrencyRatio":1.0
      },
      {
         "redeemed":0.0,
         "expired":0.0,
         "returned":0.0,
         "adjusted":0.0,
         "lifetimePoints":420.0,
         "loyaltyPoints":420.0,
         "cumulativePurchases":24000.0,
         "loyaltyId":143032714,
         "currentSlab":"Aviator",
         "nextSlab":"Explorer",
         "nextSlabSerialNumber":2,
         "nextSlabDescription":"Explorer",
         "slabSNo":1,
         "slabExpiryDate":"2121-03-10T23:59:59+05:30",
         "programId":1550,
         "delayedPoints":0.0,
         "delayedReturnedPoints":0.0,
         "totalAvailablePoints":420.0,
         "totalReturnedPoints":0.0,
         "linkedPartnerPrograms":[

         ],
         "programTitle":"AirAsia India",
         "programDescription":"AirAsia India",
         "programPointsToCurrencyRatio":1.0
      },
      {
         "redeemed":0.0,
         "expired":0.0,
         "returned":0.0,
         "adjusted":0.0,
         "lifetimePoints":0.0,
         "loyaltyPoints":0.0,
         "cumulativePurchases":0.0,
         "loyaltyId":143032714,
         "currentSlab":"Base",
         "nextSlab":"bbstar",
         "nextSlabSerialNumber":2,
         "nextSlabDescription":"bbstar",
         "slabSNo":1,
         "slabExpiryDate":"2121-05-08T01:20:22+05:30",
         "programId":1679,
         "delayedPoints":0.0,
         "delayedReturnedPoints":0.0,
         "totalAvailablePoints":0.0,
         "totalReturnedPoints":0.0,
         "linkedPartnerPrograms":[

         ],
         "programTitle":"bigbasket",
         "programDescription":"bigbasket",
         "programPointsToCurrencyRatio":1.0
      }
   ],
   "groupLoyaltyProgramDetails":[
      {
         "groupProgramId":1414,
         "title":"Tata Digital SITDefaultProgram",
         "description":"Default program for Tata Digital SIT",
         "programsList":[
            {
               "id":1414,
               "name":"Tata Digital SITDefaultProgram",
               "description":"Default program for Tata Digital SIT"
            },
            {
               "id":1422,
               "name":"IHCL",
               "description":"IHCL"
            },
            {
               "id":1423,
               "name":"Croma",
               "description":"Croma"
            },
            {
               "id":1424,
               "name":"Tata Westside Loyalty",
               "description":""
            },
            {
               "id":1497,
               "name":"Tata TataSky Loyalty",
               "description":"Tata TataSky Loyalty"
            },
            {
               "id":1550,
               "name":"AirAsia India",
               "description":"AirAsia India"
            },
            {
               "id":1568,
               "name":"Tata Ginger Loyalty",
               "description":""
            },
            {
               "id":1679,
               "name":"bigbasket",
               "description":"bigbasket"
            },
            {
               "id":1680,
               "name":"Tata CLiQ",
               "description":"Tata CLiQ"
            },
            {
               "id":1745,
               "name":"Playground (TataCliq)",
               "description":"This is an experimental Program"
            },
            {
               "id":1762,
               "name":"TML  Loyalty",
               "description":"TML  Loyalty"
            },
            {
               "id":1766,
               "name":"1mg",
               "description":"1mg"
            }
         ],
         "lifetimePoints":420.0,
         "loyaltyPoints":420.0,
         "promisedPoints":0.0,
         "pointsToCurrencyRatio":1.0
      }
   ],
   "cardDetails":[

   ],
   "warnings":[

   ]
}

Resource Information

URI `/lookup/customerDetails?{requestParams}‘
Authentication Yes
HTTP Method GET
Batch Support No

Request URL

{host}/v2/customers/lookup/customerDetails?source={source}&accountId={accountId}&identifierName={identifierName}&identifierValue={identifierValue}&embed={embedParameterName}

Request Query Parameters

Parameter Datatype Description
identifierName* enum Identifier type used to get customer details. Values: mobile, email, externalId, cardnumber, cardExternalId.
identifierValue* string Value of the identifierName passed. For example, identifierName=cardExternalId&identifierValue=cardUUID123
source* enum Source from which you want to fetch details. Value: INSTORE, MARTJACK, WECHAT, ALL. ( to fetch details from all sources. For sources with multiple accounts, you also need to pass the specific accountId.
accountId** string For sources with multiple accounts, pass the specific accountId.
embed enum To include the details of a specific entity in response. Value: points, subscriptions, mlp, promotionalPoints, expirySchedules, expiredPoints. For example, embed=expiredPoints retrieves the summary of expired points of the customer.
Usage: {host}/v2/customers/{CustomerId}/source=INSTORE&&embed=points.

Fetch Customer ID

Sample Request


https://eu.api.capillarytech.com/v2/customers/lookup?source=INSTORE&identifierName=mobile&identifierValue=919111111111

Sample Response

# Entity is the unique id of the customer

{
"entity": 306,
"warnings":[]
}

Lets you fetch unique ID of a customer generated internally. This is required for customer related activities such as fetch customer details, update customer details, manage subscription details and other activities.

Resource Information

URI `/lookup?{query parameters}’
Authentication Yes
HTTP Method GET
Batch Support No

Request URL

{host}/v2/customers/lookup?source={SourceName}&accountId={accountId}&identifierName={IdentifierName}&identifierValue={IdentifierValue}

Request Query Parameters

Parameter Datatype Description
source* enum Specify the source from which you want to fetch the customer details. Values: FACEBOOK, WEB_ENGAGE, WECHAT, INSTORE, MARTJACK, TMALL, TAOBAO, JD, ECOMMERCE, WEBSITE, LINE, ALL.
accountId string Specify the account id of the specific source if the source has multiple accounts. accountId is required for sources with multiple accounts such as WeChat or Facebook.
identifierName* enum Identifier based on which you want to fetch the customer id. Values: mobile, email, externalId, cardnumber, cardExternalId, wechat, martjackId,fbId.
identifierValue* string Pass the respective identifier value.

Error Codes

CODE DESCRIPTION
8015 No customer found with the given identifier.
8065 No customer found in the given source with the given identifier.
8045 Account id is not passed.
8013 Customer identifier is invalid. Also check if the parameter identifierName is passed correctly.
8011 Invalid source account passed.

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.
1060 Batch limit exceeded.
1062 Invalid Test & Control status.
1088 Unable to issue points. Please report to capillary support.
1099 Unable to fetch tracker data for the customer.
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.
91009 Retrieved survivor account for the requested merge victim.
91010 Downgrade strategy is not configured.
91020 Invalid TILL passed for registration.
91021 Invalid attribution TILL passed.
91022 Failed to update subscription for {x} channel and priority {y}.

Warning Codes

Code Description
1053 Preferred store specified is not found.
91001 Failed to get point details.
91002 Failed to get subscription details.
91003 Failed to validate.
91004 Failed to get segmentation details.
91005 {x} is primary identifier and cannot be updated.
91006 {x} update is not allowed.
91007 Failed to register. {x} already exists for some other user.
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 {x} length too long.
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.

Transaction

A transaction represents a purchase or return event.

Transactions are classified into the following types:

Add/Return Transaction (Bulk)

Lets you add or return one or more transactions to the Capillary system. It supports both loyalty and not-interested transactions.

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.

The transaction/add API lets you do the following.

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)

Sample Request

https://eu.intouch.capillarytech.com/v2/transactions/bulk

Sample POST Request (of Add Transaction)

[
   {
      "identifierType":"id",
      "identifierValue":"98662653",
      "source":"INSTORE",
      "accountId":"",
      "type":"REGULAR",
      "billNumber":"num-668288857749",
      "billingDate":"2021-09-05T20:01:51+05:30",
      "discount":"10.0",
      "billAmount":"4800.0",
      "note":"this is test",
      "grossAmount":"110",
      "deliveryStatus":"SHIPPED",
      "userGroup2Id":1949,
      "userGroup2PrimaryUserId":414936033,
      "userGroup2ExternalId": "",
      "paymentModes":[
         {
            "mode":"CardPayment",
            "value":"5100.0",
            "notes":"SPay",
            "attributes":{
               "card_type":"Visa"
            }
         },
         {
            "mode":"NetBanking",
            "value":"4800.0",
            "notes":"Net Banking"
         }
      ],
      "redemptions":{
         "pointsRedemptions":[
            123453,
            345673
         ],
         "couponRedemptions":[
            727272,
            237878
         ]
      },
      "extendedFields":{
         "ship_first_name":"Sam",
         "ship_last_name":"Sundar"
      },
      "customFields":{
         "booking_ota":"Website",
         "trans_cf_a":"abc"
      },
      "lineItemsV2":[
         {
            "itemCode":"sku_486741_2",
            "amount":100.5,
            "description":"sample description",
            "discount":0,
            "rate":100.5,
            "qty":1,
            "extendedFields":{
               "MetalRate":"22.02",
               "GrossWeight":"10.50"
            }
         },
         {
            "itemCode":"sku_486741_2",
            "amount":100.5,
            "description":"sample description",
            "discount":0,
            "rate":100.5,
            "qty":1,
            "extendedFields":{
               "MetalRate":"22.02",
               "GrossWeight":"10.50"
            }
         },
         {
            "itemCode":"sku_486741_3",
            "amount":100.5,
            "rate":100.5,
            "qty":1,
            "extendedFields":{
               "gender":"Male",
               "marital_status":"Married"
            },
            "customFields":{
               "cashierid":"jim2345",
               "city":"Bangalore"
            }
         },
         {
            "itemCode":"sku_486741_4",
            "amount":100.5,
            "rate":100.5,
            "qty":1,
            "extendedFields":{
               "MetalRate":"22.02",
               "GrossWeight":"10.50"
            }
         },
         {
            "itemCode":"sku_486741_5",
            "amount":100.5,
            "rate":100.5,
            "qty":1,
            "extendedFields":{
               "MetalRate":"22.02",
               "GrossWeight":"10.50"
            }
         },
         {
            "itemCode":"sku_486741_6",
            "amount":100.5,
            "rate":100.5,
            "qty":1,
            "extendedFields":{
               "MetalRate":"22.02",
               "GrossWeight":"10.50"
            }
         },
         {
            "itemCode":"sku_486741_7",
            "amount":100.5,
            "rate":100.5,
            "qty":1,
            "extendedFields":{
               "MetalRate":"22.02",
               "GrossWeight":"10.50"
            }
         },
         {
            "itemCode":"sku_486741_8",
            "amount":100.5,
            "discount":0,
            "rate":100.5,
            "qty":1,
            "extendedFields":{
               "MetalRate":"22.02",
               "GrossWeight":"10.50"
            }
         },
         {
            "itemCode":"sku_486741_9",
            "amount":100.5,
            "rate":100.5,
            "qty":1,
            "extendedFields":{
               "MetalRate":"22.02",
               "GrossWeight":"10.50"
            }
         },
         {
            "itemCode":"sku_486741_10",
            "amount":100.5,
            "rate":100.5,
            "qty":1,
            "extendedFields":{
               "MetalRate":"22.02",
               "GrossWeight":"10.50"
            }
         }
      ]
   },
   {
      "identifierType":"mobile",
      "identifierValue":"919740000000",
      "source":"INSTORE",
      "accountId":"",
      "type":"REGULAR",
      "billNumber":"num-668288857765",
      "discount":"10",
      "billAmount":"200",
      "note":"this is test",
      "grossAmount":"110",
      "deliveryStatus":"SHIPPED",
      "paymentModes":[
         {
            "attributes":{
               "BankNameAPI":"value_6555444"
            },
            "notes":"notes_6555444",
            "mode":"CHECKAPI",
            "value":"500"
         }
      ],
      "extendedFields":{
         "ship_first_name":"22.02",
         "ship_last_name":"10.50"
      },
      "customFields":{
         "trans_cf_a":"abc"
      },
      "lineItemsV2":[
         {
            "itemCode":"sku_486741_2",
            "amount":100.5,
            "rate":100.5,
            "qty":1,
            "extendedFields":{
               "MetalRate":"22.02",
               "GrossWeight":"10.50"
            }
         },
         {
            "itemCode":"sku_486741_2",
            "amount":100.5,
            "rate":100.5,
            "qty":1,
            "extendedFields":{
               "MetalRate":"22.02",
               "GrossWeight":"10.50"
            }
         },
         {
            "itemCode":"sku_486741_3",
            "amount":100.5,
            "rate":100.5,
            "qty":1,
            "extendedFields":{
               "MetalRate":"22.02",
               "GrossWeight":"10.50"
            }
         },
         {
            "itemCode":"sku_486741_4",
            "amount":100.5,
            "rate":100.5,
            "qty":1,
            "extendedFields":{
               "MetalRate":"22.02",
               "GrossWeight":"10.50"
            }
         },
         {
            "itemCode":"sku_486741_5",
            "amount":100.5,
            "rate":100.5,
            "qty":1,
            "extendedFields":{
               "MetalRate":"22.02",
               "GrossWeight":"10.50"
            }
         },
         {
            "itemCode":"sku_486741_6",
            "amount":100.5,
            "rate":100.5,
            "qty":1,
            "extendedFields":{
               "MetalRate":"22.02",
               "GrossWeight":"10.50"
            }
         },
         {
            "itemCode":"sku_486741_7",
            "amount":100.5,
            "rate":100.5,
            "qty":1,
            "extendedFields":{
               "MetalRate":"22.02",
               "GrossWeight":"10.50"
            }
         },
         {
            "itemCode":"sku_486741_8",
            "amount":100.5,
            "rate":100.5,
            "qty":1,
            "extendedFields":{
               "gender":"Male",
               "marital_status":"Married"
            },
            "customFields":{
               "cashierid":"jim2345",
               "city":"Bangalore"
            }
         },
         {
            "itemCode":"sku_486741_9",
            "amount":100.5,
            "rate":100.5,
            "qty":1,
            "extendedFields":{
               "MetalRate":"22.02",
               "GrossWeight":"10.50"
            }
         },
         {
            "itemCode":"sku_486741_10",
            "amount":100.5,
            "rate":100.5,
            "qty":1,
            "extendedFields":{
               "MetalRate":"22.02",
               "GrossWeight":"10.50"
            }
         }
      ],
      "loyaltyPromotionIdentifiers":[
         "ABC-12345",
         "Diwali_Promotion_2020",
         "New_Year_Promotion_2020"
      ],
      "promotionEvaluationId":"60f5713c4c5cb92ab2da320e",
      "appliedPromotionIdentifiers":[
         "eyJwcm9tb3Rpb25JZCI6IjYxMmU1YzVlNDEzM2I1NmFiZTBmMDczZSIsImRpc2NvdW50IjoiMTAwMC4wMDAwMDAiLCJhbW91bnQiOiIzMDAwLjAwMDAwMCIsImRpc2NvdW50QXBwbGllZFF0eSI6IjEiLCJwcm9tb3Rpb25BcHBsaWVkUXR5IjoiMy4wMDAwMDAiLCJyZWRlbXB0aW9uQ291bnQiOjEsInNrdSI6IkpOU1JFRzAyIiwidmVyc2lvbiI6InYxIn0=",
         "eyJwcm9tb3Rpb25JZCI6IjYxMmU1YzVlNDEzM2I1NmFiZTBmMDczZSIsImRpc2NvdW50IjoiMTAwMC4wMDAwMDAiLCJhbW91bnQiOiIzMDAwLjAwMDAwMCIsImRpc2NvdW50QXBwbGllZFF0eSI6IjEiLCJwcm9tb3Rpb25BcHBsaWVkUXR5IjoiMy4wMDAwMDAiLCJyZWRlbXB0aW9uQ291bnQiOjEsInNrdSI6IkpOU1JFRzAyIiwidmVyc2lvbiI6InYxIn1="
      ]
   }
]

Sample POST Request (Return Transaction)

[
  {
    "identifierType": "id",
    "identifierValue": "919035000000",
    "source": "INSTORE",
    "type": "RETURN",
    "returnType": "LINE_ITEM",
    "billNumber": "num-6682818",
    "billingDate": "2020-12-28T10:18:01.534Z",
    "discount": "10",
    "billAmount": "210",
    "paymentModes": [
      {
        "attributes": {
          "CASH": "200"
        }
      }
    ],
    "redemptions": {
      "pointsRedemptions": [
        123453,
        345673
      ],
      "couponRedemptions": [
        727272,
        237878
      ]
    },
    "extendedFields": {
      "ship_first_name": "22.02",
      "ship_last_name": "10.50"
    },
    "customFields": {
      "trans_cf_a": "abc"
    },
    "lineItemsV2": [
      {
        "itemCode": "sku_486741_2",
        "description": "ribon box",
        "amount": 50,
        "rate": 100,
        "qty": 1,
        "value": 100,
        "discount": 50
      },
      {
        "itemCode": "sku_486741_2",
        "description": "Lower",
        "amount": 100,
        "rate": 100,
        "qty": 1,
        "value": 100,
        "discount": 0
      },
      {
        "itemCode": "sku_486741_3",
        "description": "Upper T-shirt",
        "amount": 60,
        "rate": 100,
        "qty": 1,
        "value": 100,
        "discount": 40
      }
    ]
  },
]

Sample Response

{
  "response": [
    {
      "entityId": 360744866,
      "result": {
        "identifierType": "id",
        "identifierValue": "98662653",
        "source": "INSTORE",
        "accountId": "",
        "extendedFields": {
          "flight_count": 1
        },
        "deliveryStatus": "SHIPPED",
        "type": "REGULAR",
        "billAmount": 4808,
        "billNumber": "Test144e79c384598f5f9a265581d52a0a1471747957",
        "discount": 0,
        "grossAmount": 110.0,
        "note": "this is test",
        "redemptions":{
         "pointsRedemptions":[
            123453,
            345673
         ],
         "couponRedemptions":[
            727272,
            237878
         ]
      },
        "lineItemsV2": [
          {
            "amount": 8,
            "itemCode": "CGST",
            "qty": 1,
            "returnable": true,
            "returnableDays": -1,
            "comboDetails": [],
            "addOnDetails": [],
            "splitDetails": [],
            "extendedFields": {
              "GrossWeight": "10.50",
              "MetalRate": "22.02"
            }
          },
          {
            "amount": 334,
            "itemCode": "CONA",
            "qty": 1,
            "returnable": true,
            "returnableDays": -1,
            "comboDetails": [],
            "addOnDetails": [],
            "splitDetails": [],
            "extendedFields": {}
          },
          {
            "amount": 98,
            "itemCode": "SGST",
            "qty": 1,
            "returnable": true,
            "returnableDays": -1,
            "comboDetails": [],
            "addOnDetails": [],
            "splitDetails": [],
            "extendedFields": {}
          }
        ],
        "customFields": {
          "booking_ota": "Website",
          "conf_no": "508705538",
          "fare_class": "X",
          "flight_destination": "CCU",
          "flight_number": "550",
          "flight_source": "DEL",
          "seat_number": "27B",
          "trip_type": "1"
        },
        "notInterestedReason": "",
        "sideEffects": [
          {
            "entityType": "USER",
            "rawAwardedPoints": 480.8,
            "awardedPoints": 480,
            "type": "points"
          },
          {
            "id": 397760089,
            "entityType": "USER",
            "couponType": "PE",
            "couponCode": "2AWZSLSN",
            "validTill": "2029-09-01T23:59:59+05:30",
            "description": "NewCouponForAll",
            "discountCode": "NO_VALUE",
            "trimmedCouponCode": "2AWZSLSN",
            "type": "coupon"
          }
        ],
        "paymentModes": [
          {
            "mode": "NetBanking",
            "value": 4808,
            "notes": "Internet banking"
          },
          {
            "mode": "UPI",
            "value": 4808,
            "notes": "UPI Pay",
            "attributes": {
              "name": "BankNameAPI",
              "value": "value_6555444"
            }
          }
        ],
        "billingDate": "2021-07-05T14:10:00Z",
        "useDefaultFleetGroup": false
      },
      "errors": [],
      "warnings": [
        {}
      ]
    },
    {
      "entityId": 360744868,
      "result": {
        "identifierType": "id",
        "identifierValue": "98662653",
        "source": "INSTORE",
        "extendedFields": {},
        "deliveryStatus": "SHIPPED",
        "type": "REGULAR",
        "billAmount": 4808,
        "billNumber": "test244e79c384598f5f9a265581d652a010a14717465",
        "currency": "INR",
        "discount": 0,
        "lineItemsV2": [
          {
            "amount": 8,
            "itemCode": "CGST",
            "qty": 1,
            "returnable": true,
            "returnableDays": -1,
            "comboDetails": [],
            "addOnDetails": [],
            "splitDetails": [],
            "extendedFields": {}
          },
          {
            "amount": 98,
            "itemCode": "SGST",
            "qty": 1,
            "returnable": true,
            "returnableDays": -1,
            "comboDetails": [],
            "addOnDetails": [],
            "splitDetails": [],
            "extendedFields": {}
          }
        ],
        "customFields": {
          "booking_ota": "Website",
          "conf_no": "508705535",
          "fare_class": "X",
          "flight_destination": "CCU",
          "flight_number": "550",
          "flight_source": "DEL",
          "seat_number": "28B",
          "trip_type": "1"
        },
        "notInterestedReason": "",
        "sideEffects": [
          {
            "entityType": "USER",
            "rawAwardedPoints": 480.8,
            "awardedPoints": 480,
            "type": "points"
          }
        ],
        "paymentModes": [
          {
            "mode": "Card Payment",
            "value": 4808,
            "notes": "CardPay",
            "attributes": {
              "card_type": "Debit Card"
            }
          }
        ],
        "billingDate": "2021-07-05T14:10:00Z",
        "useDefaultFleetGroup": false
      },
      "errors": [
       {
            "status": false,
            "code": 8084,
            "message": "Customer details not sent"
        }
      ],
      "warnings": [
        {
         "status": false,
         "code": 91016,
         "message": "Extended field name gender is invalid."
        }
      ]
    }
  ],
  "totalCount": 2,
  "failureCount": 0
}

Resource Information

URI /v2/transactions/bulk
HTTP Method POST
API Version v2
Batch Support Yes
Rate Limited Yes

Request Header (Optional)

Header Description
X-CAP-DIRECT-REPLAY Pass true to add the call to the event execution queue (reply event) - in this case, transaction is added and other events will be executed later. Pass false to directly execute the event - you will get response along with other event details (side effects).
X-CAP-DIRECT-REPLAY Pass true to add the transaction but enable loyalty events to trigger at a later point of time. The events will be pushed to queue and will be executed.

Request URL

{host}/v2/transactions/bulk

Request Body Parameters

Parameter Datatype Description
identifierType* enum Pass any of the registered identifier name of the customer. Values: mobile, email, externalId, wechat,martjackId, or fbId (Facebook ID), id.
identifierValue* string Pass the respective identifier value. For example if identifierType is mobile, identifierValue is mobile number.
source* enum Pass the 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).
accountId string For sources with multiple accounts (such as MARTJACK, WECHAT), pass the respective account ID.
extendedFields obj Valid transaction level extended field details in name and value pairs.
currencyCode string ISO currency code of the transaction to add transaction with local currency. For example, INR for Indian Rupee, SGD for Singapore Dollar, EUR for Euro, IQD for Iraqi Dinar. Pass the currency code that are supported for your org (InTouch > Organization Setup) and ensure the currency conversion ratio is set using v2/currencyratio.
addWithLocalCurrency boolean Pass true to add a transaction in local currency.
deliveryStatus enum Delivery status of the item. Values: PLACED, PROCESSED, SHIPPED, DELIVERED, RETURNED. You can update the status using v1.1/transaction/update.
userGroup2Id int Unique ID of the user group to which the transaction needs to be associated with. Any one among the parameters with userGroup2 is required to associate the transaction with a group.
userGroup2PrimaryUserId long Unique user ID of the primary member of group to which the transaction needs to be associated with. Any one among the parameters with userGroup2 is required to associate the transaction with a group.
userGroup2ExternalId string Unique external ID of the user group to which the transaction needs to be associated with. Any one among the parameters with userGroup2 is required to associate the transaction with a group.
type* enum Type of transaction. Supported value: REGULAR for loyalty transactions. RETURN for return transactions. NOT_INTERESTED, RETURN,NOT_INTERESTED_RETURN.
notInterestedReason string Notes on why the customer is not interested to enroll into the loyalty (type=NOT_INTERESTED). Max characters supported - 255.
returnType** enum For a return transaction, pass the return type. Value: AMOUNT, FULL, LINE_ITEM, CANCELLED.
billAmount* double Net transaction amount.
billNumber* string Unique transaction number. For a return transaction, this is the original transaction number of the return item. In transaction add the uniqueness of the billNumber is either at till, store, or org, depends on the configuration. CONF_LOYALTY_BILL_NUMBER_UNIQUE_IN_DAYS set on InTouch Settings > System & Deployment > InTouch POS Configuration > Billing.
billingDate date-time Date and time of the transaction in the ISO 8601 format - YYYY-MM-DDTHH:MM:SSZ.
discount double Discount availed for the transaction or line item (discount amount).
grossAmount double Transaction amount before discount.
outlierStatus enum Transaction level outlier status. Values: NORMAL, INTERNAL, FRAUD, OUTLIER, TEST, DELETED, FAILED, OTHER. This overrides the outlier status of the configured outlier settings.
note string Additional information about the transaction.
lineItemsV2 obj Details of line-items.
     amount double Net line item amount. value-discount=amount
     description string One or two liner description of the line-item.
     discount int Discount received on the line item.
     itemCode string Unique code of the transaction line-item.
     qty double Quantity of the current line-item.
     rate double Price of each line-item.
     serial string Serial number of the line-item.
     value double Gross amount of the item. Usually, rate*qty=value.
     returnable boolean Pass true if the item can be returned post purchase.
     returnableDays int Maximum number of days the item is allowed to return.
     customFields obj Transaction or line-item level custom field details.
     imgUrl string URL of the product image.
     attributes obj Attributes of the product in name-value pairs.
     comboDetails obj Details of combo, bundle, or split items.
          itemCode string Unique line-item code.
          quantity double Quantity of the current combo item.
          description string One or two liner description of add-on, split, or combo item.
          rate double Price of the combo item.
          value double Item price excluding discount.
          comboType string Type of the combo. Value: COMBO_PARENT, COMBO_ITEM, ADD_ON_ITEM, SPLIT.
     addOnDetails obj Details of add-on item.
     splitDetails obj Details of split item.
     parentBillNumber string Actual transaction number of the return item. Applicable only for mixed transaction (involves both transaction and return).
     purchaseTime date-time Actual date and time of purchase in ISO 6801 format (ex: 2021-09-09T19:50:07+05:30).
     returnType enum Return type of the line item. Value: AMOUNT, FULL, LINE_ITEM. Not applicable if the transaction level returnType is FULL or AMOUNT.
     type enum Type of the line item. Value: REGULAR (for regular line item purchase), NOT_INTERESTED (for line item purchase with no customer tagging), RETURN (to return a regular line item ), NOT_INTERESTED_RETURN (to return a line item of no-interested transaction).
     appliedPromotionIdentifiers array Based 64 encoded format Cart or catalog promotions applied to the transaction.
It will have the details mentioned here {"promotionId":"612e5c5e4133b56abe0f073e","discount":"1000.000000","amount":"3000.000000","discountAppliedQty":"1","promotionAppliedQty":"3.000000","redemptionCount":1,"sku":"JNSREG02","version":"v1"}
     extendedFields obj Valid transaction line-item level extended field details.
customFields obj Details of transaction level or transaction line-item level custom fields.
attribution obj Mapping to tag the transaction to a different user or till (other than the current user)
     createDate date-time Date of the transaction in ISO 8601 standard format.
     createdBy obj User ID or store entity (like TILL ID, store ID) associated with the transaction.
          code string Unique code of the entity.
          type enum Type of the attribution entity. Value: ZONE, CONCEPT, STORE, TILL, STR_SERVER, ADMIN_USER, ASSOCIATE, RULE, OU.
purchaseTime date-time Actual date of transaction of the returning bill in Date and time of the transaction in ISO 8601 standard - YYYY-MM-DDTHH:MM:SSZ.
redemptions obj Details of points and coupon redemptions for the transaction.
     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, [727272, 237878]
paymentModes obj Payment details used for the transaction.
     mode string Mode of payment.
     value double Amount paid through the current mode.
     notes string Additional information related to the payment mode. Max characters - 250.
     attributes obj Attributes of the payment mode as name-value pairs.
promotionEvaluationId string Promotion evaluation code (cart/catalog) applied for the transaction.
appliedPromotionIdentifiers array Base 64 encoded string of Cart/catalog promotion identifiers that are applied to the transaction.
It will have the details mentioned here {"promotionId":"612e5c5e4133b56abe0f073e","discount":"1000.000000","amount":"3000.000000","discountAppliedQty":"1","promotionAppliedQty":"3.000000","redemptionCount":1,"sku":"JNSREG02","version":"v1"}
loyaltyPromotionIdentifiers array Identifier(s) of loyalty promotion(s) that you want to tag to the transaction.

Response Headers

Header Description
X-CAP-REQUEST-ID Unique API request ID generated. This is used for tracing and debugging purposes.
org_id Unique ID of the current org.
till Till code associated with the transaction.

Response Parameters

Parameter Datatype Description
entityId long Unique transaction ID generated.
billingDate date-time Date and time of the transaction in HH-MM-DDThh:mm:ssTZD

Add Transaction (Single)

Lets you add a new transaction or return an existing transaction. It supports both loyalty and not-interested transactions.

Sample Request

https://us.api.capillarytech.com/v2/transactions?source=instore&identifierValue=GOLD400000000000000022020&identifierName=cardnumber&rawSideEffects=true&accountId=

Sample POST Request (REGULAR)

{
  "type": "REGULAR",
  "billNumber": "num-1234",
  "discount": "10",
  "billAmount": "200",
  "note": "This is test",
  "grossAmount": "110",
  "deliveryStatus": "SHIPPED",
  "userGroup2Id":1949,
  "userGroup2PrimaryUserId":414936033,
  "userGroup2ExternalId": "",
    "paymentModes": [
        {
          "mode": "Card Payment",
          "value": 5104,
          "notes": "Sample notes",
          "attributes": {
             "card_type": "Visa"
           }
        }
    ], 
  "extendedFields": {
    "ship_first_name": "Ram",
    "ship_last_name": "Singh",
    "checkin_date":"2010-06-04 21:08:12",
    "checkout_date":"2010-06-05 21:08:12"
  },
  "customFields": {
    "paymentmode": "cash"
  },
  "lineItemsV2": [
    {
      "itemCode": "sku_234_2",
      "amount": 100.5,
      "rate": 100.5,
      "qty": 1.0,
      "extendedFields": {
        "MetalRate": "22.02",
        "GrossWeight": "10.50"
      }
    },
    {
      "itemCode": "sku_sdf_10",
      "amount": 100.5,
      "rate": 100.5,
      "qty": 1.0,
      "extendedFields": {
        "MetalRate": "22.02",
        "GrossWeight": "10.50"
      }
    }
  ],
  "promotionEvaluationId":"60f5713c4c5cb92ab2da320e", 
  "loyaltyPromotionIdentifiers":[
    "ABC-12345",
    "Diwali_Promotion_2020",
    "New_Year_Promotion_2020"
  ],
  "appliedPromotionIdentifiers": ["eyJwcm9tb3Rpb25JZCI6IjYxMmU1YzVlNDEzM2I1NmFiZTBmMDczZSIsImRpc2NvdW50IjoiMTAwMC4wMDAwMDAiLCJhbW91bnQiOiIzMDAwLjAwMDAwMCIsImRpc2NvdW50QXBwbGllZFF0eSI6IjEiLCJwcm9tb3Rpb25BcHBsaWVkUXR5IjoiMy4wMDAwMDAiLCJyZWRlbXB0aW9uQ291bnQiOjEsInNrdSI6IkpOU1JFRzAyIiwidmVyc2lvbiI6InYxIn0=", "eyJwcm9tb3Rpb25JZCI6IjYxMmU1YzVlNDEzM2I1NmFiZTBmMDczZSIsImRpc2NvdW50IjoiMTAwMC4wMDAwMDAiLCJhbW91bnQiOiIzMDAwLjAwMDAwMCIsImRpc2NvdW50QXBwbGllZFF0eSI6IjEiLCJwcm9tb3Rpb25BcHBsaWVkUXR5IjoiMy4wMDAwMDAiLCJyZWRlbXB0aW9uQ291bnQiOjEsInNrdSI6IkpOU1JFRzAyIiwidmVyc2lvbiI6InYxIn1="
   ]
}  

Sample POST Request (Mixed Transaction)

{
  "type": "REGULAR",
  "billNumber": "bill00076",
  "discount": "100",
  "billAmount": "1900",
  "note": "this is test",
  "grossAmount": "2000",
  "deliveryStatus": "DELIVERED",
  "userGroup2Id":98765,
  "userGroup2PrimaryUserId":"",
  "userGroup2ExternalId": "",
  "lineItemsV2": [
      {
        "amount": 1200,
        "parentBillNumber": "bill00075",
        "returnType":"LINE_ITEM",
        "type":"RETURN",
        "description": "blue large jeans",
        "discount": 0,
        "itemCode": "ITEMJEANS0005",
        "qty": 1,
        "rate": 1200,
        "serial": 1,
        "value": 1200,
        "returnable": false,
        "returnableDays": 0,
        "customFields": {},
        "imgUrl": ""
      },
      {
        "amount": 6570,
        "type":"REGULAR",
        "description": "blue large jeans",
        "discount": 0,
        "itemCode": "ITEMJEANS0ih05",
        "qty": 1,
        "rate": 1200,
        "serial": 1,
        "value": 1200,
        "returnable": false,
        "returnableDays": 0,
        "customFields": {},
        "imgUrl": ""
      }
    ],
  "promotionEvaluationId":"",
  "appliedPromotionIdentifiers":[""]
}

Sample Request (NOT_INTERESTED)

{
  "type": "NOT_INTERESTED",
  "billNumber": "bill12345",
  "purchaseTime": "",
  "discount": "100",
  "billAmount": "1900",
  "note": "this is test",
  "grossAmount": "2000",
  "deliveryStatus": "DELIVERED",
  "lineItemsV2": [
      {
        "amount": 1200000000,
        "parentBillNumber": "",
        "returnType":"",
        "type":"",
        "description": "blue large jeans",
        "discount": 0,
        "itemCode": "ITEMJEANS0005",
        "qty": 1,
        "rate": 1200,
        "serial": 1,
        "value": 1200,
        "returnable": false,
        "returnableDays": 0,
        "customFields": {},
        "imgUrl": ""
      },
      {
        "amount": 6570,
        "type":"",
        "description": "blue large jeans",
        "discount": 0,
        "itemCode": "ITEMJEANS0ih05",
        "qty": 1,
        "rate": 1200,
        "serial": 1,
        "value": 1200,
        "returnable": false,
        "returnableDays": 0,
        "customFields": {},
        "imgUrl": ""
      }
    ],
    "paymentModes": [
        {
        }
    ],
  "promotionEvaluationId":"",
  "appliedPromotionIdentifiers":[""]
}

Sample Response

{
    "createdId": 2147939409,
    "warnings": [],
    "errors": [],
    "sideEffects": [
        {
            "entityType": "USER",
            "rawAwardedPoints": 1700.000,
            "awardedPoints": 1700,
            "type": "points"
        },
        {
            "id": 399000028,
            "entityType": "USER",
            "couponType": "PE",
            "couponCode": "KNRYHMRW",
            "validTill": "2029-09-01T23:59:59+05:30",
            "description": "NewCouponForAll",
            "discountCode": "NO_VALUE",
            "trimmedCouponCode": "KNRYHMRW",
            "type": "coupon"
        }
    ],
    "rawSideEffects": [
        {
            "awardOn": "BILL",
            "awardStrategyId": "35637",
            "awardedOn": "23rd Sep, 2021",
            "awardedOnMillis": "1632397476258",
            "billNumber": "bill00017",
            "evaluatedEntity": "USER",
            "expiryDate": "24th Sep, 2021",
            "expiryDateMillis": "1632508199999",
            "expiryStrategyId": "79650",
            "lineItemId": "-1",
            "pointTypeId": "6463",
            "pointTypeIsRedeemable": "true",
            "pointTypeName": "Main",
            "points": "1500.000",
            "programId": "1016",
            "promoId": "-1",
            "promoIdentifier": "",
            "promoName": "",
            "sourceId": "2147876300",
            "sourceType": "Bill",
            "tenderCodeId": "-1",
            "type": "AWARD"
        },
        {
            "awardOn": "BILL",
            "awardStrategyId": "60025",
            "awardedOn": "23rd Sep, 2021",
            "awardedOnMillis": "1632397476258",
            "billNumber": "bill00017",
            "evaluatedEntity": "USER",
            "expiryDate": "23rd Sep, 2021",
            "expiryDateMillis": "1632421799999",
            "expiryStrategyId": "60024",
            "lineItemId": "-1",
            "pointTypeId": "6463",
            "pointTypeIsRedeemable": "true",
            "pointTypeName": "Main",
            "points": "200.000",
            "programId": "1016",
            "promoId": "-1",
            "promoIdentifier": "",
            "promoName": "",
            "sourceId": "2147876300",
            "sourceType": "Bill",
            "tenderCodeId": "-1",
            "type": "AWARD"
        },
        {
            "amount": "0.000",
            "delayInSec": "0",
            "emailDelayInSec": "0",
            "emailTemplateId": "0",
            "expiryDate": "1882981799000",
            "issueDate": "Thu Sep 23 17:14:37 IST 2021",
            "maxRedemptionDivisor": "0.000",
            "mobilePushDelayInSecs": "0",
            "orgId": "50074",
            "programId": "1016",
            "shortenUrlCheck": "0",
            "smsSenderId": "7022012384",
            "smsTemplate": "hi, please enjoy this offer: {{voucher_code}}",
            "sourceId": "2147876300",
            "sourceType": "Bill",
            "sourceTypeId": "1",
            "type": "PE_ISSUE_VOUCHER",
            "userId": "416670898",
            "voucherCode": "OKN8J3L6",
            "voucherId": "398995893",
            "voucherSeriesId": "363653",
            "weChatDelay": "0"
        },
        {
            "amount": "0.000",
            "delayInSec": "0",
            "emailDelayInSec": "0",
            "emailTemplateId": "0",
            "expiryDate": "1882981799000",
            "issueDate": "Thu Sep 23 17:14:37 IST 2021",
            "maxRedemptionDivisor": "0.000",
            "mobilePushDelayInSecs": "0",
            "orgId": "50074",
            "programId": "1016",
            "shortenUrlCheck": "0",
            "smsTemplate": "Hi, your coupon: {{voucher_code}}",
            "sourceId": "2147876300",
            "sourceType": "Bill",
            "sourceTypeId": "1",
            "type": "PE_ISSUE_VOUCHER",
            "userId": "416670898",
            "voucherCode": "0X7UFW20",
            "voucherId": "398995894",
            "voucherSeriesId": "363653",
            "weChatDelay": "0"
        }
    ]
    "customerInfo": {
        "firstName": "Tom",
        "lastName": "Sawyer"
    }
}

Resource Information

URI /v2/transactions?{queryParams}
HTTP Method POST
API Version v2
Batch Support Yes
Rate Limited Yes

Request Header (optional)

Header Description
X-CAP-DIRECT-REPLAY Pass true to add the call to the event execution queue (reply event) - in this case, transaction is added and other events will be executed later. Pass false to directly execute the event.

Request URL

{host}/v2/transactions?source={source}&identifierName={identifierName}&identifierValue={identifierValue}&accountId={accountId}

Request Query Parameters

Parameter Datatype Description
identifierName* enum Pass any of the registered identifier name of the customer. Values: mobile, email, externalId, id, wechat,martjackId, fbId (Facebook ID), cardnumber, cardExternalId.
identifierValue* string Pass the respective identifier value. For example if identifierType is mobile, identifierValue is mobile number.
source* enum Pass the 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).
accountId string For sources with multiple accounts (such as MARTJACK, WECHAT), pass the respective account ID. Not applicable for INSTORE source.
use_async boolean Pass true to run Loyalty activities in the background, side effects will not be returned in the API response. If false, API will wait for Loyalty activities to complete and then respond to the client with side effects in the API response.
rawSideEffects boolean Pass true to get complete details of incentives such as awardOn, expiryDate, strategyIds and so on. See rawSideEffects in response for more details.

Request Body Parameters

Parameter Datatype Description
extendedFields obj Valid transaction level extended field details in name and value pairs.
currencyCode string ISO currency code of the transaction to add transaction with local currency. For example, INR for Indian Rupee, SGD for Singapore Dollar, EUR for Euro, IQD for Iraqi Dinar. Pass the currency code that are supported for your org (InTouch > Organization Setup) and ensure the currency conversion ratio is set using v2/currencyratio.
addWithLocalCurrency boolean Pass true to add a transaction in local currency.
deliveryStatus enum Delivery status of the item. Values: PLACED, PROCESSED, SHIPPED, DELIVERED, RETURNED. You can update the status using v1.1/transaction/update.
userGroup2Id int External ID of the user group to be associated with the transaction. Any one among the parameters with userGroup2 is required to associate the transaction with a group.
userGroup2PrimaryUserId long ID of the primary user of the group to be associated with the transaction. Any one among the parameters with userGroup2 is required to associate the transaction with a group.
userGroup2ExternalId string External ID of the user group to be associated with the transaction. Any one among the parameters with userGroup2 is required to associate the transaction with a group.
type* enum Type of transaction. Supported value: REGULAR for loyalty transactions. RETURN for return transactions. NOT_INTERESTED, RETURN,NOT_INTERESTED_RETURN.
notInterestedReason string Notes on why the customer is not interested to enroll into the loyalty (type=NOT_INTERESTED). Max characters supported - 255.
returnType** enum For a return transaction, pass the return type. Value: AMOUNT, FULL, LINE_ITEM, CANCELLED.
billAmount* double Net transaction amount.
billNumber* string Unique transaction number for normal or mixed transactions and original transaction number for return transactions. The uniqueness either at till, store, or org, depends on the configuration CONF_LOYALTY_BILL_NUMBER_UNIQUE_IN_DAYS set on InTouch Settings > System & Deployment > InTouch POS Configuration > Billing.
billingDate date-time Date and time of the transaction in the ISO 8601 format - YYYY-MM-DDTHH:MM:SSZ.
discount double Discount availed for the transaction or line item (discount amount) .
grossAmount double Transaction amount before discount.
outlierStatus enum Transaction level outlier status. Values: NORMAL, INTERNAL, FRAUD, OUTLIER, TEST, DELETED, FAILED, OTHER. This overrides the outlier status of the configured outlier settings.
note string Additional information about the transaction.
lineItemsV2 obj Details of line-items.
     amount double Net line item amount. value-discount=amount.
     description string One or two liner description of the line-item.
     discount int Discount received on the line item.
     itemCode string Unique code of the transaction line-item.
     qty double Quantity of the current line-item.
     rate double Price of each line-item.
     serial string Serial number of the line-item.
     value double Gross amount of the item. Usually, rate*qty=value.
     returnable boolean Pass true if the item can be returned post purchase.
     returnableDays int Maximum number of days the item is allowed to return.
     customFields obj Transaction or line-item level custom field details.
     imgUrl string URL of the product image.
     attributes obj Attributes of the product in name-value pairs.
     comboDetails obj Details of combo, bundle, or split items.
          itemCode string Unique line-item code.
          quantity double Quantity of the current combo item.
          description string One or two liner description of add-on, split, or combo item.
          rate double Price of the combo item.
          value double Item price excluding discount.
          comboType string Type of the combo. Value: COMBO_PARENT, COMBO_ITEM, ADD_ON_ITEM, SPLIT.
     addOnDetails obj Details of add-on item.
     splitDetails obj Details of split item.
     parentBillNumber string Actual transaction number. Applicable only for mixed transaction (transaction that involves both purchaase and return - exchange).
     purchaseTime date-time Actual date of transaction of the return item in ISO 8601 format - YYYY-MM-DDTHH:MM:SSZ
     returnType enum Return type of the line item. Value: AMOUNT, FULL, LINE_ITEM.
     type enum Type of the line item. Value: REGULAR (for regular line item purchase), NOT_INTERESTED (for line item purchase with no customer tagging), RETURN (to return a regular line item ), NOT_INTERESTED_RETURN (to return a line item of no-interested transaction).
     appliedPromotionIdentifiers array Cart or catalog promotions applied to the transaction.
     extendedFields obj Valid transaction line-item level extended field details.
customFields obj Details of transaction level or transaction line-item level custom fields.
attribution obj Mapping to tag the transaction to a different user or till (other than the current user)
     createDate date-time Date of the transaction in ISO 8601 standard format.
     createdBy obj User ID or store entity (like TILL ID, store ID) associated with the transaction.
          code string Unique code of the entity.
          type enum Type of the attribution entity. Value: ZONE, CONCEPT, STORE, TILL, STR_SERVER, ADMIN_USER, ASSOCIATE, RULE, OU.
purchaseTime date-time Actual date of transaction of the returning bill in Date and time of the transaction in ISO 8601 standard - YYYY-MM-DDTHH:MM:SSZ.
redemptions obj Details of points and coupon redemptions for the transaction.
     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, [727272, 237878]
paymentModes obj Payment details used for the transaction.
     mode string Mode of payment.
     value double Amount paid through the current mode.
     notes string Additional information related to the payment mode. Max characters - 250.
     attributes obj Attributes of the payment mode as name-value pairs.
promotionEvaluationId string Promotion evaluation code (cart/catalog) applied for the transaction.
appliedPromotionIdentifiers array Base 64 encoded string of Cart/catalog promotion identifiers that are applied to the transaction.
It will have the details mentioned here {"promotionId":"612e5c5e4133b56abe0f073e","discount":"1000.000000","amount":"3000.000000","discountAppliedQty":"1","promotionAppliedQty":"3.000000","redemptionCount":1,"sku":"JNSREG02","version":"v1"}
loyaltyPromotionIdentifiers array Identifier(s) of loyalty promotion(s) that you want to tag to the transaction.

Response Headers

Header Description
X-CAP-REQUEST-ID Unique API request ID generated. This is used for tracing and debugging purposes.
org_id Unique ID of the current org.
till Till code associated with the transaction.

Get Transaction Details

Sample Request

https://eu.api.capillarytech.com/v2/transactions/38236823?type=REGULAR

Sample Response

{
   "useDefaultFleetGroup":false,
   "attribution":{
      "createDate":"2021-09-09T11:49:14+05:30",
      "createdBy":{
         "id":50006796,
         "code":"mobilepush.1",
         "description":"",
         "name":"mobilepush.1",
         "type":"TILL",
         "adminType":"GENERAL",
         "isActive":true,
         "isOuEnabled":false,
         "timeZoneId":191,
         "currencyId":216,
         "languageId":1
      },
      "modifiedBy":{

      },
      "modifiedDate":"2021-09-09T11:49:17+05:30"
   },
   "billDetails":{
      "amount":200.0,
      "billingStore":{
         "id":50006795,
         "code":"storecode",
         "description":"webenagestore",
         "name":"webstore1",
         "type":"STORE",
         "adminType":"GENERAL",
         "isActive":true,
         "isOuEnabled":false,
         "timeZoneId":191,
         "currencyId":216,
         "languageId":1
      },
      "billNumber":"num-6682855857799",
      "billingTime":"2021-09-09T11:49:14+05:30",
      "discount":10.0,
      "grossAmount":110.0,
      "note":"this is test",
      "returnDetails":{
         "canceled":false
      },
      "niReturnDetails":{

      },
      "invalidBill":false
   },
   "creditNote": {
        "amount": 1800.0,
        "notes": "Reason for credit",
        "number": "numbr9959104543",
        "validity": "2022-09-09",
        "updateAmount": false
    },
   "customFields":{
      "gender": "male"
   },
   "addWithLocalCurrency":false,
   "async":false,
   "useV2":false,
   "customerId":316726161,
   "id":2147866485,
   "lineItems":[
      {
         "id":2153881142,
         "customerId":0,
         "details":{
            "amount":100.5,
            "description":"",
            "discount":0.0,
            "itemCode":"sku_486741_2",
            "qty":1.0,
            "rate":100.5,
            "serial":0,
            "value":0.0,
            "returnable":true,
            "returnableDays":-1,
            "attributes":{

            },
            "extendedFields":{
                "paymentmode": "cash"
            },
            "attributesSet":[

            ]
         },
         "outlierStatus":"NORMAL",
         "returnDetails":{

         },
         "valid":true,
         "returnLineItemsDtos":[

         ],
         "niReturnLineItemsDtos":[

         ],
         "addonDetails":[

         ],
         "splitItemsDetails":[

         ],
         "niReturn":false
      },
      {
         "id":2153881151,
         "customerId":0,
         "details":{
            "amount":100.5,
            "description":"",
            "discount":0.0,
            "itemCode":"sku_486741_10",
            "qty":1.0,
            "rate":100.5,
            "serial":0,
            "value":0.0,
            "returnable":true,
            "returnableDays":-1,
            "attributes":{
               "POINTS_ELIGIBILITY":"Yes",
               "pathy_name":"",
               "product_form":""
            },
            "extendedFields":{

            },
            "attributesSet":[
               {
                  "product_form":""
               },
               {
                  "POINTS_ELIGIBILITY":"Yes"
               },
               {
                  "pathy_name":""
               }
            ]
         },
         "outlierStatus":"NORMAL",
         "returnDetails":{

         },
         "valid":true,
         "returnLineItemsDtos":[

         ],
         "niReturnLineItemsDtos":[

         ],
         "addonDetails":[

         ],
         "splitItemsDetails":[

         ],
         "niReturn":false
      }
   ],
   "outlierStatus":"NORMAL",
   "paymentModes": [
        {
            "amount": 1000.0,
            "attributes": [],
            "id": 24074480,
            "mode": "UPI",
            "notes": "",
            "orgPaymentModeId": 8976
        }
    ],
   "type":"REGULAR",
   "lifeTimePurchases":0,
   "ignorePoints":false,
   "extendedFields":{
      "boarding_status":"Boarded",
      "product_class":"EP"
   },
   "autoUpdateTime":"2021-09-09T11:49:17+05:30",
   "niReturnDetails":{

   },
   "basketSize":10.0,
   "returnDetails":{
      "canceled":false
   },
   "warnings":[

   ]
}

Retrieves the details of a specific transaction.

Resource Information

URI v2/transactions/{id}
HTTP Method GET
API Version v2
Rate Limited Yes
Batch Support NA

Request URL

{host}/v2/transactions/{id}?{queryParams}

Request Parameters

Parameter Datatype Description
id* (path) long Unique transaction id to fetch details.
type (query) enum Type of transaction to fetch. Value: REGULAR, RETURN, NOT_INTERESTED,NOT_INTERESTED_RETURN. Default value isREGULAR`.
tenders (query) boolean Pass true to retrieve payment mode details. Default value is false.
credit_notes boolean Pass true to retrieve credit notes details (added through v1.1 transaction/add). Default value is false.

Response Codes

Error Codes

Code Description
500 Unable to retrieve transaction.
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 passed. Only regular, return, not_interested, and not_interested_return 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.
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.
685 Field length too long.
686 Unable to add transaction.
687 Points activities are queued and will be updated later.
688 No matching line-item found for return.
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.
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.
8015 No customer found for the given identifiers.
8084 Unable to send customer details.
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.

Warnings

Code Description
625 Transaction number does not exist. If the config CONF_ALLOW_NOT_EXISTING_BILL_RETURNis enabled, the transaction is saved with a warning.
683 Failed to call new bill event EMF.
684 Failed EMF new bill DVS event.
687 Points activities are queued and will be updated later.
688 No line item found matching for return.
669 Invalid custom field.
710 Return bill event failed from EMF.
1105 Returnable days should be greater than -1.
9601 Unable to add line item.
9602 Unable to add credit note.
9603 Unable to add payment mode details.
9604 Unable to add custom fields.
9605 Base currency is not set for the org.
9606 Transaction currency is not passed.
9607 Payment mode (tender) is not found.
9608 Line item with item code {x} is marked as outlier.
9609 Invalid payment attribute value.
9610 New bill event is failed. Points are not awarded.
9611 Transaction is marked as outlier.
9612 Unable to save the credit notes
9613 Invalid payment attribute.
9614 Multiple loyalty transactions found to be returned.
9615 Return policy days are not defined.
9616 Single loyalty transaction found. Allowing regular return.

Earning

Get Transaction Earning

Retrieves the details of all points earned for a transaction.

Sample Request

https://us.api.capillarytech.com/v2/earning/167111742

Sample Response

{
   "useDefaultFleetGroup":false,
   "attribution":{
      "createDate":"2021-07-28T17:08:40+05:30",
      "createdBy":{
         "id":12995129,
         "code":"aa.website",
         "description":"",
         "name":"aa.website",
         "type":"TILL",
         "adminType":"GENERAL",
         "isActive":true,
         "isOuEnabled":false,
         "timeZoneId":-1,
         "currencyId":-1,
         "languageId":-1
      },
      "modifiedBy":{

      },
      "modifiedDate":"2021-07-28T17:08:41+05:30"
   },
   "billDetails":{
      "amount":8000.0,
      "billingStore":{
         "id":12995128,
         "code":"aa.website",
         "description":"",
         "name":"AirAsia",
         "type":"STORE",
         "adminType":"GENERAL",
         "isActive":true,
         "isOuEnabled":false,
         "timeZoneId":-1,
         "currencyId":-1,
         "languageId":-1
      },
      "billNumber":"0101611121021-aa2",
      "billingTime":"2021-07-28T17:08:40+05:30",
      "discount":0.0,
      "grossAmount":0.0,
      "note":"",
      "returnDetails":{
         "canceled":false
      },
      "niReturnDetails":{

      },
      "invalidBill":false,
      "pointsEarningEntities":{
         "entityId":481191985,
         "entityType":"customer",
         "billPoints":[
            {
               "programId":1414,
               "currentPointsSummary":{
                  "availablePoints":0,
                  "expiredPoints":0,
                  "redeemedPoints":0,
                  "promisedPoints":0,
                  "returnedPromisedPoints":0,
                  "returnedPoints":0,
                  "promisedPointsConverted":0
               },
               "issuedPointsSummary":{
                  "redeemablePointsIssued":0,
                  "promisedPointsIssued":0
               },
               "currentPointsBreakup":{
                  "regularPointsInfo":null,
                  "promotionalPointsInfo":null
               }
            },
            {
               "programId":1550,
               "currentPointsSummary":{
                  "availablePoints":0,
                  "expiredPoints":0,
                  "redeemedPoints":0,
                  "promisedPoints":0,
                  "returnedPromisedPoints":0,
                  "returnedPoints":0,
                  "promisedPointsConverted":0
               },
               "issuedPointsSummary":{
                  "redeemablePointsIssued":0,
                  "promisedPointsIssued":0
               },
               "currentPointsBreakup":{
                  "regularPointsInfo":null,
                  "promotionalPointsInfo":null
               }
            }
         ]
      }
   },
   "customFields":{
      "flight_destination":"DEL",
      "flight_source":"BOM"
   },
   "addWithLocalCurrency":false,
   "async":false,
   "useV2":false,
   "customerId":481191985,
   "id":167111742,
   "lineItems":[
      {
         "id":502374973,
         "customerId":481191985,
         "details":{
            "amount":4000.0,
            "description":"",
            "discount":0.0,
            "itemCode":"PBAC",
            "qty":1.0,
            "rate":4000.0,
            "serial":0,
            "value":0.0,
            "returnable":true,
            "returnableDays":-1,
            "attributes":{
               "POINTS_ELIGIBILITY":"Yes",
               "pathy_name":"",
               "product_form":""
            },
            "extendedFields":{
               "charge_type":"0"
            },
            "attributesSet":[
               {
                  "product_form":""
               },
               {
                  "POINTS_ELIGIBILITY":"Yes"
               },
               {
                  "pathy_name":""
               }
            ]
         },
         "outlierStatus":"NORMAL",
         "returnDetails":{

         },
         "valid":true,
         "returnLineItemsDtos":[

         ],
         "niReturnLineItemsDtos":[

         ],
         "addonDetails":[

         ],
         "splitItemsDetails":[

         ],
         "pointsEarningEntities":{
            "entityId":481191985,
            "entityType":"customer",
            "lineItemPoints":[
               {
                  "programId":1414,
                  "currentPointsSummary":{
                     "availablePoints":0,
                     "expiredPoints":0,
                     "redeemedPoints":0,
                     "promisedPoints":0,
                     "returnedPromisedPoints":0,
                     "returnedPoints":0,
                     "promisedPointsConverted":0
                  },
                  "issuedPointsSummary":{
                     "redeemablePointsIssued":0,
                     "promisedPointsIssued":0
                  },
                  "currentPointsBreakup":{
                     "regularPointsInfo":null,
                     "promotionalPointsInfo":null
                  }
               },
               {
                  "programId":1550,
                  "currentPointsSummary":{
                     "availablePoints":320.000,
                     "expiredPoints":0,
                     "redeemedPoints":0,
                     "promisedPoints":0,
                     "returnedPromisedPoints":0,
                     "returnedPoints":0,
                     "promisedPointsConverted":0
                  },
                  "issuedPointsSummary":{
                     "redeemablePointsIssued":320.000,
                     "promisedPointsIssued":0
                  },
                  "currentPointsBreakup":{
                     "regularPointsInfo":{
                        "availablePointsInfo":[
                           {
                              "points":320.000,
                              "expiryDate":"2022-08-31T23:59:59+05:30",
                              "expiryType":"rolling",
                              "actionSourceDetails":[
                                 {
                                    "actionId":27229,
                                    "sourceType":"lineItem",
                                    "actionType":"BILL_POINTS_ACTION",
                                    "actionPointsDetail":[
                                       {
                                          "points":320.000,
                                          "sourceValue":4000.000,
                                          "sourceIdentifiers":[
                                             {
                                                "key":"tracker",
                                                "value":"AirAsiaSpends2"
                                             }
                                          ]
                                       }
                                    ]
                                 }
                              ]
                           }
                        ],
                        "promisedPointsInfo":null
                     },
                     "promotionalPointsInfo":null
                  }
               }
            ]
         },
         "niReturn":false
      },
      {
         "id":502374974,
         "customerId":481191985,
         "details":{
            "amount":4000.0,
            "description":"",
            "discount":0.0,
            "itemCode":"FAREPRICE",
            "qty":1.0,
            "rate":4000.0,
            "serial":0,
            "value":0.0,
            "returnable":true,
            "returnableDays":-1,
            "attributes":{
               "POINTS_ELIGIBILITY":"Yes",
               "pathy_name":"",
               "product_form":""
            },
            "extendedFields":{
               "charge_type":"0"
            },
            "attributesSet":[
               {
                  "product_form":""
               },
               {
                  "POINTS_ELIGIBILITY":"Yes"
               },
               {
                  "pathy_name":""
               }
            ]
         },
         "outlierStatus":"NORMAL",
         "returnDetails":{

         },
         "valid":true,
         "returnLineItemsDtos":[

         ],
         "niReturnLineItemsDtos":[

         ],
         "addonDetails":[

         ],
         "splitItemsDetails":[

         ],
         "pointsEarningEntities":{
            "entityId":481191985,
            "entityType":"customer",
            "lineItemPoints":[
               {
                  "programId":1414,
                  "currentPointsSummary":{
                     "availablePoints":0,
                     "expiredPoints":0,
                     "redeemedPoints":0,
                     "promisedPoints":0,
                     "returnedPromisedPoints":0,
                     "returnedPoints":0,
                     "promisedPointsConverted":0
                  },
                  "issuedPointsSummary":{
                     "redeemablePointsIssued":0,
                     "promisedPointsIssued":0
                  },
                  "currentPointsBreakup":{
                     "regularPointsInfo":null,
                     "promotionalPointsInfo":null
                  }
               },
               {
                  "programId":1550,
                  "currentPointsSummary":{
                     "availablePoints":160.000,
                     "expiredPoints":0,
                     "redeemedPoints":0,
                     "promisedPoints":0,
                     "returnedPromisedPoints":0,
                     "returnedPoints":0,
                     "promisedPointsConverted":0
                  },
                  "issuedPointsSummary":{
                     "redeemablePointsIssued":160.000,
                     "promisedPointsIssued":0
                  },
                  "currentPointsBreakup":{
                     "regularPointsInfo":{
                        "availablePointsInfo":[
                           {
                              "points":160.000,
                              "expiryDate":"2022-08-31T23:59:59+05:30",
                              "expiryType":"rolling",
                              "actionSourceDetails":[
                                 {
                                    "actionId":27229,
                                    "sourceType":"lineItem",
                                    "actionType":"BILL_POINTS_ACTION",
                                    "actionPointsDetail":[
                                       {
                                          "points":160.000,
                                          "sourceValue":2000.000,
                                          "sourceIdentifiers":[
                                             {
                                                "key":"tracker",
                                                "value":"AirAsiaSpends2"
                                             }
                                          ]
                                       }
                                    ]
                                 }
                              ]
                           }
                        ],
                        "promisedPointsInfo":null
                     },
                     "promotionalPointsInfo":null
                  }
               }
            ]
         },
         "niReturn":false
      }
   ],
   "outlierStatus":"NORMAL",
   "type":"REGULAR",
   "warnings":[

   ],
   "lifeTimePurchases":0,
   "ignorePoints":false,
   "extendedFields":{
      "boarding_status":"Boarded",
      "flight_count":1,
      "product_class":"EP"
   },
   "autoUpdateTime":"2021-07-28T17:08:41+05:30",
   "niReturnDetails":{

   },
   "basketSize":2.0,
   "returnDetails":{
      "canceled":false
   },
   "warnings":[

   ]
}

Resource Information

URI /earning/{transactionId}
Rate Limited? Yes
Authentication Yes
HTTP Method GET
Batch Support No

Request URL

https://{host}/v2/earning/{transactionId}

Customer Labels

Customer labels are used for tagging customers based on their activities or loyalty histories. Tags are used in loyalty, campaigns and Essential Insights. You can add new labels and tag labels to customers using APIs of organization and customers mentioned here.

Add Labels

Lets you add a new customer tag to the organization. You cannot add tags beyond the limit set for the org.

Sample Request

https://api.us.capillarytech.com/v2/organization/labels

Sample POST Request

{
  "orgLabels": [
    {
      "name": "Premium",
      "description": "Customers whose purchase value is more than $4000"
    },
    {
      "name": "GadgetFreak",
      "description": "Interested in gadgets and new technology"
    }
  ]
}

Sample Response

{
    "entity": 1779,
    "warnings": []
}

Resource Information

URI organization/labels
Rate Limited? No
Authentication Yes
HTTP Methods POST
Batch Support No

Request URL

https://{host}/v2/organization/labels

Request Body Parameters

Parameter Datatype Description
name* string Name of the tag or labels.
description* string Brief description about the tag.

Get Org Labels

Retrieves all customers labels created for that specific org.

Sample Request

https://eu.api.capillarytech.com/v2/organization/labels

Sample Response

{
    "data": [
        {
            "id": 2,
            "orgId": 1779,
            "description": "Loves new trends and collections in fashion",
            "lastUpdatedBy": 15000449,
            "name": "Fashion",
            "active": true
        },
        {
            "id": 8,
            "orgId": 1779,
            "description": "High loyal customer with spending more than $13000",
            "lastUpdatedBy": 15000449,
            "name": "Premium",
            "active": true
        },
        {
            "id": 1,
            "orgId": 1779,
            "description": "Loves new gadgets and technology",
            "lastUpdatedBy": 15000449,
            "name": "GadgetFreak",
            "active": true
        },
        {
            "id": 3,
            "orgId": 1779,
            "description": "汉语",
            "lastUpdatedBy": 15000449,
            "name": "汉语",
            "active": true
        }
    ],
    "warnings": [],
    "errors": []
}

Resource Information

URI organization/labels
Rate Limited? No
Authentication Yes
HTTP Methods GET
Batch Support No

Request URL

https://{host}/v2/organization/labels

Tag Customers (to Labels)

Lets you tag a customer to one or more customer labels or remove an existing label.

Sample Request

https://eu.api.capillarytech.com/v2/customers/249598560/changeLabels

Sample POST Request

{
  "add": [
     {
       "labelName": "GadgetFreak"
    },
    {
       "labelName": "Premium"
    }
  ],
  "remove":[
  {
      "labelName": "book"
   }
 ]
}

Sample Response

{
    "entity": 249598560,
    "warnings": []
}

Resource Information

URI customers/{userId}/changeLabels
Rate Limited? No
Authentication Yes
HTTP Methods POST
Batch Support No

Request URL

https://{host}/v2/customers/{userId}/changeLabels

Request Parameters

Parameter Type Description
userId* Path Unique id of the user that you want to add customer label
labelName* Body Label name that you want to tag to the customer

Fetch Labels of a Customer

Retrieves the list of labels tagged to a customer.

Sample Request

https://eu.api.capillarytech.com/v2/customers/249598560/labels

Sample Response

{
    "data": [
        {
            "id": 5,
            "orgId": 0,
            "addedBy": 15147364,
            "labelId": 3,
            "userId": 249598560,
            "labelName": "GadgetFreak",
            "deleted": false
        }
    ],
    "warnings": [],
    "errors": []
}

Resource Information

URI /customers/{userId}/labels
Rate Limited? No
Authentication Yes
Response Formats JSON
HTTP Methods GET
Batch Support No

Request URL

https://{host}/v2/customers/{userId}/labels

Request Path Parameters

Parameter Description
userId* Unique id of the customer for which you want to fetch tagged labels

Search Customers by Labels

Retrieves the list of customers who are tagged to a specific label. You can also search by partial label name. By default you will see a maximum of 10 records.

Sample Request

https://eu.api.capillarytech.com/v2/customers/labels/search?q=premium

Sample Response

{
    "pagination": {
        "limit": 10,
        "offset": 0,
        "total": 2
    },
    "data": [
        {
            "userId": 316481804,
            "customerLabels": [
                {
                    "orgId": 0,
                    "labelId": 3,
                    "userId": 316481804,
                    "labelName": "book"
                }
            ]
        },
        {
            "userId": 249598560,
            "customerLabels": [
                {
                    "orgId": 0,
                    "labelId": 3,
                    "userId": 249598560,
                    "labelName": "book"
                }
            ]
        }
    ],
    "warnings": [],
    "errors": []
}

Resource Information

URI /customers/labels/search?q={LabelName}
Rate Limited? No
Authentication Yes
HTTP Methods GET
Batch Support No

Request URL

https://{host}/v2/customers/labels/search?q={LabelName}

Request Query Parameters

Parameter Description
q* Specify the label name by which you want to fetch customers. You can also pass partial string. For example pre to fetch customers in all labels that starts with pre.

OTP

This section consists of APIs related to OTPs that are used to validate customers for registration or points/coupon redemption.

The functionality of OTPs depends on the configuration set on InTouch

Generate OTP

Sample Request

https://us.api.capillarytech.com/v2/otp/generate

Sample POST Request

{
   "entityType":"email",
   "entityValue":"tom.sawyer@example.com",
   "action":"REGISTRATION",
   "template":"Hi user.Your OTP for validation is {{ validation_code }}.Enjoy",
   "emailTemplate":{
      "subject":"Validation Code",
      "body":"Dear Customer, The validation code for your request is: {{ validation_code }}. You will also receive the validation code by SMS on your registered mobile number shortly."
   },
   "channels":[
      {
         "type":"SMS",
         "value":"9191919191"
      },
      {
         "type":"EMAIL",
         "value":"tom.sawyer@example.com"
      },
      {
         "type":"PHONE",
         "value":"9191919191"
      }
   ]
}

Sample Response


# Success Response
{
    "createdId": 10,
    "warnings": []
}


# Failure Response
{
    "errors": [
        {
            "status": false,
            "code": 600,
            "message": "\"Invalid or Null action passed\""
        },
        {
            "status": false,
            "code": 602,
            "message": "\"Invalid or Null entity value passed\""
        }
    ]
}

Issues validation code (OTP) to the customer’s mobile number and/or email id for redeeming points/coupons, and registration.

Resource Information

URI otp/generate
Rate Limited? Yes
HTTP Method POST
Batch Support No

Request URL

https://{host}/v2/otp/generate

Request Body Parameters

Parameter Datatype Description
entityType* enum Specify MOBILE to identify customer by mobile number, or EMAIL to identify customer by email id.
entityValue* string Specify the registered mobile number or email id of the customer based on the entityType passed.
action* enum Choose the action for which the OTP has to be issued. Values: COUPON (for coupon redemption), POINTS (for points redemption), REGISTRATION, USERGROUP, SUBSCRIPTION, GENERIC (for other purposes), POINTSTRANSFER, CUSTOMER_STATUS_UPDATE, CUSTOMER_IDENTIFIER_CHANGE, CUSTOMER_ISSUE_LINK_CARD.
template string Message template to send OTP through SMS.
emailTemplate obj Email template to send OTP on email.
     subject string Subject of the email.
     body string Body of the email.
channels* array-obj Details of channel(s) through which you want to issue OTP.
     type* enum Channel on which OTP has to be generated. Value: EMAIL, SMS, MOBILE or PHONE (phone call), BOTH (to send OTP both on MOBILE and EMAIL ). You can use Phone to generate OTP through a voice call to the specified number.
     value string Value of the specified identifier type.

Response Parameters

Parameter Datatype Description
createdId long Unique internal reference ID generated for the current request.

Validate OTP

Sample Request

https://us.api.capillarytech.com/v2/otp/validate

Sample POST Request

{
   "entityType":"email",
   "entityValue":"tom.sawyer@example.com",
   "code":"A2WX11I",
   "action":"GENERIC"
}

Sample Success Response


{
    "entity": true,
    "warnings": []
}


Sample Failure Response


{ 
  "entity": false, 
  "warnings":[] 
}

Lets you authenticate customer by validating the OTP sent to the customer through SMS or email and proceed with the necessary action such as redeeming points/coupons, and registering customer.

Resource Information

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

Request URL

https://{host}/v2/otp/validate

Request Body Parameters

Parameter Datatype Description
entityType* enum Specify MOBILE to identify customer by mobile number or EMAIL to identify customer by email id.
entityValue* string Specify the registered mobile number or email id of the customer based on the entityType passed.
code* string Pass the validation code received by the customer.
action* enum Specify the action to be performed on successful validation. Values: COUPON (for coupon redemption), POINTS (for points redemption), REGISTRATION, USERGROUP, SUBSCRIPTION, GENERIC (for other purposes).

Response Parameters

Parameter Datatype Description
entity boolean The value will betrue if the OTP validation is successful, false if the validation fails.

Get OTP

Sample Request

https://us.api.capillarytech.com/v2/otp?source=WECHAT&accountId=WECHAT-API1&identifierName=mobile&identifierValue=8799361139&threshold=60&scope=POINTS

Sample Response

{
   "orgId":966,
   "userId":313302314,
   "code":"538AD87",
   "validUpto":"2017-08-07T21:44:20+05:30",
   "warnings":[

   ]
}

Allows fetching recent OTP issued to a customer. For now, OTP is issued for redeeming points/coupons and customer registration. If there is more than one valid OTP available for the customer, this API fetches the recently issued OTP.

Resource Information

URI /otp
Rate Limited? Yes (10 OTPs per user per day)
Authentication Yes
HTTP Method GET
Batch Support No

Request URL

https://{host}/v2/otp?source={source}&accountId={account}&{identifierName}={value}&scope={POINTS/COUPONS}

Request Path Parameters

Parameter Datatype Description
identifierName* enum Pass any of the registered identifier type of the customer. Values: mobile, email, external_id, wechat.
identifierValue* string Specify the value of the specified identifierType
source enum Source in which the customer is registered.
accountId string Account ID of the source such as WeChat and Facebook. Required for sources with multiple accounts.
threshold long Specify the validity of the OTP (in seconds) that you want to fetch.
scope* enum Specify the scope of the issued OTP. Values: COUPON (for coupon redemption), POINTS (for points redemption), REGISTRATION, USERGROUP, SUBSCRIPTION, GENERIC (for other purposes).

Response Parameters

Parameter Datatype Description
orgId long Unique ID of the org (the current org) from which the OTP is generated.
userId long Unique ID of the customer to whom the OTP is sent.
code string The OTP, or validation code, sent to the customer.
validUpto date-time The validity of the OTP in YYYY:MM:DDTHH:MM:SS+[Time Zone]

Response Codes

Success Code

Code Description
610 OTP is validated successfully.

Error Codes

Code Description
429 Rate limit exceeded. A maximum of 10 OTPs can be generated for an user per day. However, the limit can be changed if required.
600 Invalid or null action passed.
601 Invalid or null entity_type passed.
602 Invalid or null entity_value passed.
603 Invalid or null communication channel value passed.
604 No OTP passed.
605 OTP is either invalid, expired, or null.
606 Unable to generate OTP at the moment.
874 Unable to generate validation code (OTP).
875 Unable to generate validation code (OTP).
876 OTP Validation Failed
9001 No valid OTP found.

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 V2 coupon entity just allows you to:

For any other coupon related APIs, please use v1.1 APIs.

Redeem Coupons

Sample Request

http://eu.api.capillarytech.com/v2/coupon/redeem 

Sample POST Request

{
   "billAmount":"2000",
   "transactionNumber":"numbr9227550121",
   "user":{
      "mobile":"9177121900000"
   },
   "redemptionTime":"2019-04-04 11:49:59",
   "redemptionRequestList":[
      {
         "code":"9NUF8THR"
      }
   ]
}

Sample Response

{
    "redemption": [
        {
            "id": 33138363,
            "warnings": [],
            "appendedErrorMessage": "",
            "code": "JL07UAZ3",
            "discountCode": "MobilePush",
            "seriesCode": 14162,
            "isAbsolute": false,
            "couponValue": 10.0
        }
    ],
    "redemptionStatus": {
        "status": true,
        "code": 700,
        "message": "Coupon processing successful"
    },
    "customer": {
        "id": 342963216,
        "profiles": [
            {
                "firstName": "Tom",
                "lastName": "Sawyer",
                "fields": {},
                "identifiers": [
                    {
                        "type": "mobile",
                        "value": "919999000000"
                    }
                ],
                "commChannels": [],
                "userId": 342963216,
                "accountId": "",
                "autoUpdateTime": "2019-10-31T17:41:25+05:30"
            }
        ]
    },
    "warnings": []
}

This API allows you to redeem active coupons of a loyalty customer. You can pass multiple coupons at once.

Resource Information

URI coupon/redeem
Authentication Yes
HTTP Method POST
Batch Support Yes

Request URL

http://{host}/v2/coupon/redeem

Request Body Parameters

Parameter Datatype Description
billAmount* float Transaction amount of the bill.
transactionNumber* string Transaction number against which the coupon needs to be redeemed
user* enum Specify any identifier of the user who wants to redeem coupons. Values: mobile, email, externalId
redemptionTime date-time Date and time when the coupon has to be redeemed in YYYY-MM-DD HH:MM:SS format.
code* string Coupon code to be redeemed.

Check if Coupon is Redeemable

Sample Request

http://us.intouch.capillarytech.com/v2/coupon/is_redeemable?mobile=917601000000&code=6B88U6ED,V080OLI6&details=false

Sample Response

{
   "customer":{
      "id":325666373,
      "profiles":[
         {
            "accountId":"",
            "autoUpdateTime":"2019-04-04T11:47:28+05:30",
            "commChannels":[

            ],
            "fields":{

            },
            "firstName":"firstName_667095",
            "identifiers":[
               {
                  "type":"email",
                  "value":"autoemail7601667095@gmail.com"
               },
               {
                  "type":"externalId",
                  "value":"ext_id7601667095"
               },
               {
                  "type":"mobile",
                  "value":"917601667095"
               }
            ],
            "lastName":"lastName_667095",
            "userId":325666373
         }
      ]
   },
   "redemption":[
      {
         "appendedErrorMessage":"",
         "code":"6B88U6ED",
         "isAbsolute":false,
         "isRedeemable":true,
         "numberOfRedemptionsByUser":0,
         "redemptionsLeft":-1,
         "warnings":[

         ]
      },
      {
         "appendedErrorMessage":"",
         "code":"V080OLI6",
         "isAbsolute":false,
         "isRedeemable":true,
         "numberOfRedemptionsByUser":0,
         "redemptionsLeft":-1,
         "warnings":[

         ]
      }
   ],
   "redemptionStatus":{
      "code":700,
      "message":"Coupon isRedeem successful",
      "status":true
   },
   "warnings":[

   ]
}

Lets you check whether a set of coupons can be redeemed or not.

Resource Information

URI /is_redeemable?{customerIdentifier}&code={value1},{value2}...&details={true/extended}
HTTP Method GET
API Version v2
Batch Support Yes

Request URL

http://{host}/v2/coupon/is_redeemable?{customerIdentifier}&code={value1},{value2}...&details={true/extended}

Request Query Parameters

Parameter Datatype Description
user* obj Pass the identifier of the customer to check if his/her coupon is redeemable.
mobile/email/externalId/id* string Pass any of the identifiers of the customer.
code* string Pass the coupon code that you want to check for redemption. You can also pass multiple coupon codes separating each with a comma ,
details boolean Pass =true to retrieve the details of the coupon series.
details=extended - Retrieves the details of coupon configurations (set on campaign) of that specific coupon series.

Reactivate Redeemed Coupon

Sample Request

http://eu.api.capillarytech.com/v2/coupon/reactivate

Sample POST Request

{
 "redemptionIds": [
   83146
 ]
}

Sample Response

{
   "warnings": [],
   "errors": [],
   "success": true
}

Resource Information

URI /reactivate
HTTP Method POST
API Version v2
Batch Support Yes

Request URL

http://{host}/v2/coupon/reactivate

Request Body Parameters

Parameter Datatype Description
redemptionIds* array Pass the redemption id to reactivate. To reactivate multiple redeemed coupons, pass each value in a separate line with comma separated values.

Create coupon Series

Lets you create a new coupon series for the org.

Sample Request

https://eu.api.capillarytech.com/v2/coupon/series

Sample POST Request

{
    "CouponSeriesV2": {
        "customPropertyMap": {
            "key1": "custom property 1",
            "key2": "val2",
            "standard_terms_and_conditions" : "terms and condtion"
        },
        "description": "DIWALI 10% OFF",
        "discountCode": "XYZ123",
        "validTillDate": "2021-05-10T00:00:00+05:30",
        "expiryStrategyValue": 1,
        "maxCreate": -1,
        "maxRedeem": -1,
        "anyUser": false,
        "sameUserMultipleRedeem": false,
        "isReferralExistingUsersAllowed": false,
        "isMultipleUseAllowed": false,
        "isValidWithDiscountedItem": true,
        "smsTemplate" : "Hi {{first_name}} {{last_name}} your voucher code {{voucher}}is valid {{valid_days_from_create}}. {{fullname}} {{offer_name}}",
        "isSMSDisabled": false,
        "info": "Evil coupon",
        "isMultipleVouchersPerUserAllowed": true,
        "doNotResendExistingVoucher": true,
        "mutualExclusiveSeriesIds": "[]",
        "maxVouchersPerUser": 11,
        "minDaysBetweenVouchers": 23,
        "discountValue": 500,
        "redemptionRange": "{\"dom\" : [1], \"dow\": [1], \"hours\": [1]}",
        "minBillAmount": 100,
        "maxBillAmount": 20000,
        "maxRedemptionsInSeriesPerUser": 122,
        "minDaysBetweenRedemption": 962,
        "redemptionValidFrom": "2020-11-18T00:00:00+05:30",
        "productInfo": [
        ],
        "redemptionOrgEntityDetails": [
        ],
        "targetUserDetails": {
            "validMaxUserTransactionLimit": 1,
            "validUserRegistrationStartTime": 0,
            "validUserRegistrationEndTime": 10000
        },
        "redemptionValidAfterDays": 22,
        "alphaNumeric": true,
        "randomCodeLength": 10,
        "resendMessageEnabled": true,
        "clientHandlingType": "DISC_CODE",
        "expiryStrategyType": "SERIES_EXPIRY",
        "discountType": "ABS"
    }
}

Sample Response

{
    "id": 86066,
    "orgId": 100458,
    "description": "DIWALI 10% OFF",
    "discountCode": "XYZ123",
    "validTillDate": "2021-05-09T00:00:00Z",
    "validDaysFromCreation": 30,
    "expiryStrategyValue": 1,
    "maxCreate": -1,
    "maxRedeem": -1,
    "isTransferrable": false,
    "anyUser": false,
    "sameUserMultipleRedeem": false,
    "isReferralExistingUsersAllowed": false,
    "isMultipleUseAllowed": false,
    "isValidationRequired": false,
    "isValidWithDiscountedItem": true,
    "createdBy": 75040399,
    "numIssued": 0,
    "numRedeemed": 0,
    "createdOn": "2021-05-13T11:11:42Z",
    "lastUsed": "2021-05-13T11:11:41Z",
    "seriesCode": "453163F75E8C4A2EAA2E",
    "smsTemplate": "Hi {{first_name}} {{last_name}} your voucher code {{voucher}}is valid {{valid_days_from_create}}. {{fullname}} {{offer_name}}",
    "isSMSDisabled": false,
    "info": "Evil coupon",
    "isMultipleVouchersPerUserAllowed": true,
    "doNotResendExistingVoucher": true,
    "mutualExclusiveSeriesIds": "[]",
    "storeIdsJson": "[-1]",
    "isDvsEnabled": false,
    "dvsExpiryDate": "2021-05-13T00:00:00Z",
    "priority": 0,
    "shortSMSTemplate": "Hello {{cust_name}}, your voucher code is {{voucher_code}}",
    "maxVouchersPerUser": 11,
    "minDaysBetweenVouchers": 23,
    "maxReferralsPerReferee": -1,
    "discountUpto": 0,
    "discountValue": 500,
    "dvsItems": "items",
    "redemptionRange": "{\"dom\" : [1], \"dow\": [1], \"hours\": [1]}",
    "minBillAmount": 100,
    "maxBillAmount": 20000,
    "redeemAtStore": "[-1]",
    "campaignId": -1,
    "tag": "DIWALI 10% OFF",
    "maxRedemptionsInSeriesPerUser": 122,
    "minDaysBetweenRedemption": 962,
    "redemptionValidFrom": "2020-11-17T00:00:00Z",
    "sourceOrgId": -1,
    "issueToLoyalty": false,
    "redeemStoreType": "redeemable_stores",
    "offlineRedeemType": false,
    "isOldFlowEnabled": false,
    "isPreRedeemEventRequired": false,
    "termsAndConditions": "T&C",
    "signalRedemptionEvent": false,
    "syncToClient": false,
    "showPinCode": false,
    "targetUserDetails": {
        "validMaxUserTransactionLimit": 1,
        "validUserRegistrationStartTime": 0,
        "validUserRegistrationEndTime": 10000
    },
    "numUploadedNonIssued": 0,
    "numUploadedTotal": 0,
    "redemptionValidAfterDays": 22,
    "ownedBy": "NONE",
    "ownerId": -1,
    "ownerValidity": 0,
    "alphaNumeric": true,
    "shortCodeLength": 0,
    "randomCodeLength": 10,
    "fixedExpiryDate": 1620518400000,
    "numTotal": 0,
    "latestIssualTime": 0,
    "latestRedemptionTime": 0,
    "resendMessageEnabled": true,
    "seriesType": "UNDEFINED",
    "clientHandlingType": "DISC_CODE",
    "expiryStrategyType": "SERIES_EXPIRY",
    "discountOn": "BILL",
    "discountType": "ABS",
    "updateProductData": false,
    "externalIssual": false,
    "warnings": []
}

Resource Information

URI coupon/series
HTTP Method POST
API Version v2
Batch Support No

​ ​ ​

Request URL

​ ​ https://{host}/v2/coupon/series

Request Body Parameters

Parameter Datatype Description
customPropertyMap obj
description string Brief description of the card series.
discountCode string Discount code
validTillDate date-time Validity of the card series in UTC timestamp. Format: YYYY-MM-DDTHH:MM:SS+/-(time-zone).
expiryStrategyValue int
maxCreate int
maxRedeem int Limit number of coupons to redeem.
isTransferrable boolean Pass true if the recipient can transfer the coupon to someone else.
anyUser boolean Pass true if any customer can redeem the coupon, pass false only if the customer who received the coupon can only redeem it.
sameUserMultipleRedeem boolean Pass true to allow users to redeem the coupon multiple times.
isReferralExistingUsersAllowed boolean
isMultipleUseAllowed boolean
isValidationRequired boolean
isValidWithDiscountedItem boolean
createdBy long Unique ID of the admin who created the coupon series.
numIssued int Number of coupons to be issued from the coupon series.
numRedeemed int Number of coupons to be redeemed from the coupon series.
createdOn date-time Date and time of series creation in `YYYY-MM-DDThh:mm:ssZ",
lastUsed date-time
seriesCode string Unique alpha-numeric code of the coupon series.
smsTemplate string Message to be sent to issue a coupon from the series. Use predefined tags in the message wherever required. For example, first_name, last_name, voucher (for voucher code) and so on.
isSMSDisabled boolean Pass true to disable sending coupon related SMS to audience.
info string
isMultipleVouchersPerUserAllowed boolean
doNotResendExistingVoucher
mutualExclusiveSeriesIds
storeIdsJson
isDvsEnabled boolean
dvsExpiryDate date-time Date and time of
priority int
shortSMSTemplate string Short message to send to users. Pass voucher_code to insert coupon code in the message.
maxVouchersPerUser
minDaysBetweenVouchers
maxReferralsPerReferee
discountUpto
discountValue
dvsItems
redemptionRange "{\"dom\" : [1], \"dow\": [1], \"hours\": [1]}"
minBillAmount double Minimum transaction amount for which the coupon redemption is applicable.
maxBillAmount double Maximum transaction amount for which the coupon redemption is applicable.
redeemAtStore array
campaignId long Unique ID of the campaign associated with the series.
tag string
maxRedemptionsInSeriesPerUser int
minDaysBetweenRedemption int
redemptionValidFrom date-time
issueToLoyalty boolean
redeemStoreType enum redeemable_stores",
offlineRedeemType boolean
isOldFlowEnabled boolean
isPreRedeemEventRequired boolean
termsAndConditions string
signalRedemptionEvent boolean
syncToClient boolean
showPinCode boolean

Update coupon Series

Lets you update an existing coupon series.

Sample Request

https://eu.api.capillarytech.com/v2/coupon/series/

Sample POST Request

{
  "customPropertyMap": {},
  "id": 0,
  "additionalDescription": "string",
  "orgId": 0,
  "description": "string",
  "discountCode": "string",
  "validTillDate": "2021-05-24T09:18:59.261Z",
  "validDaysFromCreation": 0,
  "expiryStrategyValue": 0,
  "maxCreate": 0,
  "maxRedeem": 0,
  "isTransferrable": false,
  "anyUser": false,
  "sameUserMultipleRedeem": false,
  "isReferralExistingUsersAllowed": false,
  "isMultipleUseAllowed": false,
  "isValidationRequired": false,
  "isValidWithDiscountedItem": false,
  "createdBy": 0,
  "numIssued": 0,
  "numRedeemed": 0,
  "createdOn": "2021-05-24T09:18:59.261Z",
  "lastUsed": "2021-05-24T09:18:59.261Z",
  "seriesCode": "string",
  "smsTemplate": "string",
  "isSMSDisabled": false,
  "info": "string",
  "isMultipleVouchersPerUserAllowed": false,
  "doNotResendExistingVoucher": false,
  "mutualExclusiveSeriesIds": "string",
  "storeIdsJson": "string",
  "isDvsEnabled": false,
  "dvsExpiryDate": "2021-05-24T09:18:59.261Z",
  "priority": 0,
  "shortSMSTemplate": "string",
  "maxVouchersPerUser": 0,
  "minDaysBetweenVouchers": 0,
  "maxReferralsPerReferee": 0,
  "discountUpto": 0,
  "discountValue": 0,
  "dvsItems": "string",
  "redemptionRange": "string",
  "minBillAmount": 0,
  "maxBillAmount": 0,
  "redeemAtStore": "string",
  "campaignId": 0,
  "tag": "string",
  "maxRedemptionsInSeriesPerUser": 0,
  "minDaysBetweenRedemption": 0,
  "redemptionValidFrom": "2021-05-24T09:18:59.261Z",
  "sourceOrgId": 0,
  "issueToLoyalty": false,
  "redeemStoreType": "string",
  "offlineRedeemType": false,
  "isOldFlowEnabled": false,
  "isPreRedeemEventRequired": false,
  "productInfo": [
    {
      "productType": "string",
      "productIds": [
        0
      ]
    }
  ],
  "termsAndConditions": "string",
  "signalRedemptionEvent": false,
  "syncToClient": false,
  "showPinCode": false,
  "purpose": "string",
  "metadata": "string",
  "couponSeriesAudience": [
    {
      "audienceId": 0,
      "audienceName": "string",
      "customerCount": 0,
      "audienceGroupVersionId": 0
    }
  ],
  "redemptionOrgEntityDetails": [
    {
      "redemptionOrgEntityType": "string",
      "orgEntityId": 0
    }
  ],
  "targetUserDetails": {
    "validMaxUserTransactionLimit": 0,
    "validUserRegistrationStartTime": 0,
    "validUserRegistrationEndTime": 0
  },
  "couponUploadInfo": [
    {
      "jobId": 0,
      "uploadStatus": "string",
      "createdOn": 0,
      "updatedOn": 0,
      "errorFileUrl": "string",
      "successFileUrl": "string",
      "uploadedFileUrl": "string",
      "totalUploadedCount": 0,
      "actualRowCount": 0,
      "errorCount": 0,
      "uploadedFileName": "string",
      "audienceGroupId": 0,
      "audienceGroupVersionId": 0
    }
  ],
  "numUploadedNonIssued": 0,
  "numUploadedTotal": 0,
  "redemptionValidAfterDays": 0,
  "ownedBy": "string",
  "ownerId": 0,
  "redemptionOrgEntityType": "string",
  "ownerValidity": 0,
  "alphaNumeric": false,
  "shortCodeLength": 0,
  "randomCodeLength": 0,
  "fixedExpiryDate": 0,
  "numTotal": 0,
  "latestIssualTime": 0,
  "latestRedemptionTime": 0,
  "genericCode": "string",
  "resendMessageEnabled": false,
  "campaignName": "string",
  "seriesType": "string",
  "clientHandlingType": "string",
  "expiryStrategyType": "string",
  "discountOn": "string",
  "discountType": "string",
  "externalIssual": false,
  "updateProductData": false
}

Resource Information

URI coupon/series/{id}
HTTP Method PUT
API Version v2
Batch Support No

​ ​ ​

Request URL

​ ​ https://{host}/v2/coupon/series

Request Body Parameters

Parameter Datatype Description

Issue Coupon to Customer (Single)

Lets you issue a coupon from a coupon series to a customer.

Sample Request

https://eu.api.capillarytech.com/v2/coupon/issue

Sample POST Request

{
"seriesId":12313,
"customer":

{ 
    "id":126080386, 
    "mobile":"", 
    "externalId":"", 
    "email":"" 
}
}

Sample Response

{
    "code": "MGU9Y4PM",
    "seriesId": 12313,
    "description": "10 units",
    "discountCode": "NO_VALUE",
    "validTill": "2119-07-10T00:00:00Z",
    "discountType": "ABS",
    "discountValue": 10.0,
    "discountUpto": 0.0,
    "discountOn": "BILL",
    "detailedInfo": "10 units",
    "customer": {
        "id": 126080386,
        "profiles": [
            {
                "firstName": "test",
                "lastName": "test",
                "fields": {},
                "identifiers": [
                    {
                        "type": "mobile",
                        "value": "917500000005"
                    },
                    {
                        "type": "email",
                        "value": "tom.sawyer@example.com"
                    }
                ],
                "commChannels": [],
                "userId": 126080386,
                "accountId": "",
                "autoUpdateTime": "2021-05-12T15:06:57Z",
                "identifiersAll": [
                    {
                        "type": "mobile",
                        "value": "917500000005"
                    },
                    {
                        "type": "email",
                        "value": "tom.sawyer@example.com"
                    }
                ]
            }
        ]
    },
    "redemptionCount": 0,
    "id": 0,
    "warnings": []
}

Resource Information

URI coupon/issue
HTTP Method POST
API Version v2
Batch Support No
Rate Limited? No

​ ​ ​

Request URL

​ ​ https://{host}/v2/coupon/issue

Request Body Parameters

Parameter Datatype Description
seriesId* array Pass coupon series ID (offerIds from which you want to issue coupon.
customer* obj Details of customer to whom the coupons need to send.
id** long Unique ID of the customer.
mobile** string Unique mobile number of the customer.
email** string Unique email ID of the customer.
externalId** string Unique external ID of the customer.

Issue Coupons to Customer (Bulk)

Lets you issue coupons from one or more coupon series to a customer.

Sample Request

https://eu.api.capillarytech.com/v2/coupon/bulk/issue?source=INSTORE

Sample POST Request

{
"seriesIds" :[84093,12313],

"customer":

  { 
   "id":"126080386"
  }
}

Sample Response

{
    "response": [
        {
            "entityId": 12313,
            "result": {
                "code": "L8H04VOZ",
                "seriesId": 12313,
                "description": "10 units",
                "discountCode": "NO_VALUE",
                "validTill": "2119-07-10T00:00:00Z",
                "discountType": "ABS",
                "discountValue": 10.0,
                "discountUpto": 0.0,
                "discountOn": "BILL",
                "detailedInfo": "10 units",
                "redemptionCount": 0,
                "id": 0
            },
            "errors": [],
            "warnings": []
        },
        {
            "entityId": 84093,
            "result": {
                "code": "U6ER8MJ5",
                "seriesId": 84093,
                "description": "Test Marvel",
                "discountCode": "NO_VALUE",
                "validTill": "2021-05-31T00:00:00Z",
                "discountType": "ABS",
                "discountValue": 100.0,
                "discountUpto": 0.0,
                "discountOn": "BILL",
                "detailedInfo": "Test Marvel",
                "redemptionCount": 0,
                "id": 0
            },
            "errors": [],
            "warnings": []
        }
    ],
    "totalCount": 2,
    "failureCount": 0
}

Resource Information

URI coupon/bulk/issue?source={source}&accountId={accountId}
HTTP Method POST
API Version Yes
Batch Support No

​ ​ ​

Request URL

​ ​ https://{host}/v2/coupon?{paramName}={paramValue}

Request Query Parameters

Parameter Datatype Description
source* enum Registered source of the customer.
accountId** string Account ID for sources with multiple accounts. Required for multi-source accounts.

Request Body Parameters

Parameter Datatype Description
seriesIds* array Pass coupon series IDs (offerIds) from which you want to issue coupons.
customer* obj Details of customer to whom the coupons need to send.
id** long Unique ID of the customer.
mobile** string Unique mobile number of the customer.
email** string Unique email ID of the customer.
externalId** string Unique external ID of the customer.

Redeem Coupon (Single)

Lets you redeem a customer’s coupon against transaction.

Sample Request

https://eu.api.capillarytech.com/v2/coupon/redeem

Sample POST Request

{
  "redemptionRequestList": [

    {
      "code": "MGU9Y4PM"
    }
  ],
  "user": {
    "mobile": "917575757575"
  },
  "transactionNumber": "ZDCsdss",
  "billAmount": "2000",
  "redemptionTime": "2020-06-12"
}

Sample Response

{
    "redemption": [
        {
            "id": 369455787,
            "currencyInput": false,
            "localToBaseCurrencyExchangeRate": 0,
            "warnings": [],
            "appendedErrorMessage": "",
            "code": "MGU9Y4PM",
            "discountCode": "NO_VALUE",
            "seriesCode": 12313,
            "isAbsolute": true,
            "couponValue": 10.0,
            "redemptionStatus": {
                "statusCode": {
                    "status": true,
                    "message": "Coupon processing successful",
                    "code": 700
                },
                "warnings": [],
                "warningsAsStatusCode": [],
                "message": "Coupon processing successful",
                "code": 700,
                "success": true
            },
            "discountType": "ABS",
            "discountValue": 10,
            "discountUpto": 0
        }
    ],
    "redemptionStatus": {
        "status": true,
        "message": "Coupon processing successful",
        "code": 700
    },
    "customer": {
        "id": 126080386,
        "profiles": [
            {
                "firstName": "test",
                "lastName": "test",
                "fields": {},
                "identifiers": [
                    {
                        "type": "mobile",
                        "value": "917500000000"
                    },
                    {
                        "type": "email",
                        "value": "tom.sawyer@test.com"
                    }
                ],
                "commChannels": [],
                "userId": 126080386,
                "accountId": "",
                "autoUpdateTime": "2021-05-12T15:18:01Z",
                "identifiersAll": [
                    {
                        "type": "mobile",
                        "value": "917500000000"
                    },
                    {
                        "type": "email",
                        "value": "tom.sawyer@test.com"
                    }
                ]
            }
        ]
    },
    "warnings": []
}

Resource Information

URI coupon/redeem
HTTP Method POST
API Version v2
Batch Support No
Rate Limited? No

​ ​ ​

Request URL

https://{host}/v2/coupon/redeem

Request Body Parameters

Parameter Datatype Description
redemptionRequestList obj Coupon details to redeem.
code string Coupon code to redeem.
redemptionTime date-time Date and time of redemption in YYYY-MM-DD HH:MM:SS format.
transactionNumber string Transaction number for which the coupon(s) needs to be redeemed.
billAmount* double Transaction amount for which the coupon is redeemed.
user* obj Details of the customer that redeems the coupon(s).
id** long Unique ID of the customer.
mobile** string Unique mobile number of the customer.
email** string Unique email ID of the customer.
externalId** string Unique external ID of the customer.

Redeem Customer Coupons (Bulk)

Lets you redeem one or more coupons of a customer.

Sample Request

https://eu.api.capillarytech.com/v2/coupon/bulk/redeem?source=INSTORE

Sample POST Request

{
  "redemptionRequestList": [
    {
      "code": "U6ER8MJ5"
    },
    {
      "code": "U6ER8MH9"
    }
  ],
  "redemptionTime": "2021-05-12 19:18:30",
  "transactionNumber": "numbr9435064964",
  "user": {
    "id": 126080386
  },
  "billAmount": "2000"
}

Sample Response

{
    "response": [
        {
            "entityId": 369454015,
            "result": {
                "id": 369454015,
                "currencyInput": false,
                "localToBaseCurrencyExchangeRate": 0,
                "warnings": [],
                "appendedErrorMessage": "",
                "code": "U6ER8MJ5",
                "discountCode": "NO_VALUE",
                "seriesCode": 84093,
                "isAbsolute": true,
                "couponValue": 100.0,
                "redemptionStatus": {
                    "statusCode": {
                        "status": true,
                        "message": "Coupon processing successful",
                        "code": 700
                    },
                    "warnings": [],
                    "warningsAsStatusCode": [],
                    "message": "Coupon processing successful",
                    "code": 700,
                    "success": true
                },
                "discountType": "ABS",
                "discountValue": 100,
                "discountUpto": 0
            },
            "errors": []
        }
    ],
    "totalCount": 1,
    "failureCount": 0
}

Resource Information

URI coupon/bulk/redeem?source={source}&accountId={accountId}
HTTP Method POST
API Version v2
Batch Support Yes (coupons)
Rate Limited? No

​ ​ ​

Request URL

https://{host}/v2/coupon/bulk/redeem?{paramName}={paramValue}

Request Query Parameters

source* enum
accountId** string

Request Body Parameters

Parameter Datatype Description
redemptionRequestList obj List of coupons to redeem.
code string Coupon code to redeem.
redemptionTime date-time Date and time of redemption in YYYY-MM-DD HH:MM:SS format.
transactionNumber string Transaction number for which the coupon(s) needs to be redeemed.
billAmount* double Transaction amount for which the coupon is redeemed.
user* obj Details of the customer that redeems the coupon(s).
id** long Unique ID of the customer.
mobile** string Unique mobile number of the customer.
email** string Unique email ID of the customer.
externalId** string Unique external ID of the customer.

Get Coupon Details

Retrieves the details of one or more coupons.

Sample Request

https://eu.api.capillarytech.com/v2/coupon?issuedToIds=126080386&issuedToIds=108573800

Sample Response

{
    "data": [
        {
            "code": "1R7IOF17",
            "seriesId": 84093,
            "description": "Test Marvel",
            "discountCode": "NO_VALUE",
            "validTill": "2021-05-31T00:00:00Z",
            "discountType": "ABS",
            "discountValue": 100.0,
            "discountUpto": 0.0,
            "discountOn": "BILL",
            "detailedInfo": "Test Marvel"
        },
        {
            "code": "RNPQCPXI",
            "seriesId": 84093,
            "description": "Test Marvel",
            "discountCode": "NO_VALUE",
            "validTill": "2021-05-31T00:00:00Z",
            "discountType": "ABS",
            "discountValue": 100.0,
            "discountUpto": 0.0,
            "discountOn": "BILL",
            "detailedInfo": "Test Marvel"
        },
        {
            "code": "Z0452RAQ",
            "seriesId": 84093,
            "description": "Test Marvel",
            "discountCode": "NO_VALUE",
            "validTill": "2021-05-31T00:00:00Z",
            "discountType": "ABS",
            "discountValue": 100.0,
            "discountUpto": 0.0,
            "discountOn": "BILL",
            "detailedInfo": "Test Marvel"
        },
        {
            "code": "L6O2E1Q7",
            "seriesId": 84093,
            "description": "Test Marvel",
            "discountCode": "NO_VALUE",
            "validTill": "2021-05-31T00:00:00Z",
            "discountType": "ABS",
            "discountValue": 100.0,
            "discountUpto": 0.0,
            "discountOn": "BILL",
            "detailedInfo": "Test Marvel"
        },
        {
            "code": "HZXK4CFS",
            "seriesId": 12646,
            "description": "Welcome ",
            "discountCode": "NO_VALUE",
            "validTill": "2119-09-09T00:00:00Z",
            "discountType": "PERC",
            "discountValue": 15.0,
            "discountUpto": 0.0,
            "discountOn": "BILL",
            "detailedInfo": "Welcome "
        }
    ],
    "warnings": [],
    "errors": []
}

Resource Information

URI /coupon?{paramName}={paramValue}
HTTP Method GET
API Version v2
Batch Support Yes
Rate Limited? No

Request URL

https://{host}/v2/coupon?{paramName}={paramValue}

Request Query Parameters

Parameter Datatype Description
issuedToIds** array Fetch coupons issued to specific customers. Pass customer IDs to fetch. Example: ?issuedToIds=126080386&issuedToIds=108573800
couponIds** array Fetch coupon details by coupon IDs. Example: ?couponIds=126080386&issuedToIds=108573800.
couponCodes** array Fetch coupon details by coupon codes.

Get Coupon Series Details

Retrieves the details of one or more coupon series.

Sample Request

https://eu.api.capillarytech.com/v2/coupon/series?ids=18426

Sample Response

{
    "entity": [
        {
            "id": 18426,
            "orgId": 100458,
            "description": "Test Offer 20",
            "discountCode": "NO_VALUE",
            "validTillDate": "2120-02-11T10:23:17Z",
            "validDaysFromCreation": 30,
            "expiryStrategyValue": 1,
            "maxCreate": -1,
            "maxRedeem": -1,
            "isTransferrable": false,
            "anyUser": false,
            "sameUserMultipleRedeem": false,
            "isReferralExistingUsersAllowed": false,
            "isMultipleUseAllowed": false,
            "isValidationRequired": false,
            "isValidWithDiscountedItem": false,
            "createdBy": 75016470,
            "numIssued": 48847,
            "numRedeemed": 1,
            "createdOn": "2020-02-11T10:24:01Z",
            "lastUsed": "2020-02-11T10:24:01Z",
            "seriesCode": "6LQG2MOU",
            "smsTemplate": "Summer19",
            "isSMSDisabled": false,
            "info": "Test Offer 20",
            "isMultipleVouchersPerUserAllowed": false,
            "doNotResendExistingVoucher": true,
            "mutualExclusiveSeriesIds": "[]",
            "storeIdsJson": "[-1]",
            "isDvsEnabled": false,
            "dvsExpiryDate": "2020-03-12T00:00:00Z",
            "priority": 0,
            "shortSMSTemplate": "Hello {{cust_name}}, your voucher code is {{voucher_code}}",
            "maxVouchersPerUser": 1,
            "minDaysBetweenVouchers": -1,
            "maxReferralsPerReferee": -1,
            "discountUpto": 0,
            "discountValue": 20,
            "dvsItems": "false",
            "redemptionRange": "{\"dom\":[\"-1\"],\"dow\":[\"-1\"],\"hours\":[\"-1\"]}",
            "minBillAmount": 0,
            "maxBillAmount": 9007199254740991,
            "redeemAtStore": "[-1]",
            "campaignId": -1,
            "tag": "Test Offer 20",
            "maxRedemptionsInSeriesPerUser": -1,
            "minDaysBetweenRedemption": -1,
            "redemptionValidFrom": "1970-01-01T00:00:00Z",
            "sourceOrgId": -1,
            "issueToLoyalty": false,
            "redeemStoreType": "redeemable_stores",
            "offlineRedeemType": false,
            "isOldFlowEnabled": false,
            "isPreRedeemEventRequired": false,
            "termsAndConditions": "T&C apply",
            "signalRedemptionEvent": true,
            "syncToClient": false,
            "showPinCode": false,
            "numUploadedNonIssued": 0,
            "numUploadedTotal": 0,
            "redemptionValidAfterDays": 0,
            "ownedBy": "LOYALTY",
            "ownerId": 469,
            "ownerValidity": 4737090197000,
            "alphaNumeric": true,
            "shortCodeLength": 0,
            "randomCodeLength": 8,
            "fixedExpiryDate": 0,
            "numTotal": -1,
            "latestIssualTime": 1587993924000,
            "latestRedemptionTime": 1581513319000,
            "resendMessageEnabled": true,
            "seriesType": "LOYALTY",
            "clientHandlingType": "DISC_CODE",
            "expiryStrategyType": "SERIES_EXPIRY",
            "discountOn": "BILL",
            "discountType": "PERC",
            "externalIssual": false,
            "updateProductData": false
        }
    ],
    "warnings": []
}

Resource Information

URI /coupon/series?ids={offerId}
HTTP Method GET
API Version v2
Batch Support Yes

​ ​

Request URL

https://{host}/v2/coupon/series?ids={offerId}

Request Query Parameters

Parameter Datatype Description
ids* array Unique offer IDs that you want to fetch. Example: ?ids=18426&ids=84516

Coupon Upload

These are not CRM or v2 APIs. Hence, please note that there are changes in all the API details including host and headers.

host1

Upload Coupons (Batch)

Lets you upload coupons of a specific coupon series in bulk.

Sample Request

curl -X POST \
  https://eu.intouch.capillarytech.com/coupon/api/v1/upload/file/311025 \
  -H 'Content-Type: application/json' \
  -H 'Postman-Token: 3056825f-5e0d-411e-a83d-e6ce0e6da3d2' \
  -H 'cache-control: no-cache' \
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -H 'x-cap-api-oauth-token: eyJraWQiOiJrMSIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJDYXBpbGxhcnkiLCJleHAiOjE2MDE5ODY1NzUsImp0aSI6IllzQndtY20xbEh6OGlYNzQ4djI4QXciLCJpYXQiOjE2MDE5ODI5NzUsInN1YiI6IlRFU1RfQ09VUE9OUyIsImNsaWVudF9pZCI6NzgsIm9yZ19pZCI6NTAxMjgsInRva2VuX3VzZSI6InRva2VuX2FjY2VzcyIsImNsaWVudF9rZXkiOiJHY3dmdUFlaEVDOE02NmNBN1RWR05OQ1E0IiwiZGVmYXVsdF90aWxsIjo1MDAwNzM5Miwic2NvcGVzIjoiW3tcInBlcm1pc3Npb25cIjpcIlJFQURXUklURVwiLFwiZW50aXR5SWRcIjoxLFwicmVzb3VyY2VzXCI6W1wiLip2MS4xL2N1c3RvbWVyLy4qXCJdfSx7XCJwZXJtaXNzaW9uXCI6XCJSRUFEV1JJVEVcIixcImVudGl0eUlkXCI6MixcInJlc291cmNlc1wiOltcIi4qdjEuMS90cmFuc2FjdGlvbi8uKlwiXX0se1wicGVybWlzc2lvblwiOlwiUkVBRFdSSVRFXCIsXCJlbnRpdHlJZFwiOjMsXCJyZXNvdXJjZXNcIjpbXCIuKnYxLjEvcG9pbnRzLy4qXCJdfSx7XCJwZXJtaXNzaW9uXCI6XCJSRUFEV1JJVEVcIixcImVudGl0eUlkXCI6NCxcInJlc291cmNlc1wiOltcIi4qXCJdfV0ifQ.YVjVaOWDK_3G_B7TjPyy-QMNGpHbjev7Z_vmOCn07dJZ5sGeQcwUbYBi4RHdeNruggH7SyEKngBRAyFGot3ha3JkdJC1IV9ux6L6xwwfgqthavj6MTV0LhMEy6tRM06LEFtYrN5CuCllJ6yM3hUc25ZZKxyEGxYMflAt65TpK-A3EJDpo8RxrY-XHAitwL_R4m6kSZ2_rxyDC2qyRv6rdkjoLRzZ7urcPTOn37EGIe0TByFRa3LSPpywlMjkTX1wcFSW1z_2XgydfoqGfBAkf8Ng4db9gEr_pP96btnRm6fvoEg0RXdfsflp_LEsWUcExPFEiQvuC5wbo0TXHLOsgA' \
  -F 'file=@/Users/rajshekar.sv/Downloads/couponCode (10).csv' \
  -F customerIdentifier=USER_ID \
  -F customerIdentifierColumn=0

Sample Response

{
   "success":true,
   "status":200,
   "result":{
      "orgId":0,
      "couponSeriesId":123,
      "uploadJobStatuses":[
         {
            "jobId":1,
            "uploadStatus":"STARTED",
            "createdOn":"1601835836973",
            "updatedOn":"1601835836973",
            "errorFileUrl":null,
            "successFileUrl":null,
            "uploadedFileUrl":"couponCode_1601835836573_123.csv",
            "totalUploadedCount":0,
            "actualRowCount":0,
            "errorCount":0,
            "uploadTableName":null,
            "uploadedFileName":"couponCode.csv",
            "audienceGroupId":0,
            "audienceGroupVersionId":0
         }
      ],
      "fileName":"couponCode_1601835836573_123.csv"
   }
}

Resource Information

URI /coupon/api/v1/upload/file/{couponSeriedId}
Authentication Yes (oAuth)
HTTP Method POST
Batch Support No

Request URL

{host1}/coupon/api/v1/upload/file/{couponSeriedId}

Header Required

Header Description
Content-Type* multipart/form-data
x-cap-api-oauth-token Generated authentication token

Request Query Parameters

Parameter Datatype Description
couponSeriesId* long Unique ID of the coupon series for which you need to upload coupons.

Request Body Parameters

Parameter Datatype Description
file* string Name of the CSV file with customer and coupon details.
Sample file content:
File content sample for uploading the coupon code is as follows
customer_identifier,coupon code
value 1,ABCDEF1
value 2,ABCDEF2
value 3,ABCDEF3
File content sample for uploading customer identifier:
customerIdentifier
value 1
value 2
value 3
File content sample for uploading customer tagged coupons is as follows
customerIdentifier,coupon code
value 1,ABCDEF1
value 2,ABCDEF2
value 3,ABCDEF3
customerIdentifier* enum Customer identifier type used in the CSV file. Values: MOBILE, EXTERNAL_ID, EMAIL, USER_ID, NOT_TAGGED.
Use NOT_TAGGED as the identifier to upload only coupon codes.
customerIdentifierColumn string Column ID of the customer identifier in the uploaded CSV file.
For example,
If the first column of the file contains customer identification data, then the value of customerIdentifierColumn will be 0.
If the second column of the file contains customer identification data, then the value of customerIdentifierColumn will be 1.

Upload Redeemed Coupons

This API lets you bulk upload coupons that are redeemed for a coupon series. This API exposes an endpoint by which coupons that are redeemed externally can be imported into the Capillary CRM system.

Sample Request

curl -i -X POST 
https://crm-nightly-new.cc.capillarytech.com/coupon/api/v1/upload/redeemFile/253234 -H 'Content-Type: multipart/form-data' 
-H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZCI6WyI0Il0sIm9yZ0lEIjowLCJleHAiOjE2MDM4OTIxNTYsImlhdCI6MTYwMzgwNTc1NiwiaXNzIjoiY2FwaWxsYXJ5dGVjaC5jb20iLCJhdWQiOiJjYXBpbGxhcnksaW50b3VjaCxhcnlhLHJlb24sYXBwcyIsInNvdXJjZSI6IldFQkFQUCJ9.APtFDqTh7Yf26lzhmwFm4OwPQBo24E_MTNl6CcnIr9A' 
-F file=@couponCode.csv 
-F customerIdentifier=USER_ID 
-F couponIdentifier=COUPON_ID 
-F uploadHeaders='{"redeemedAt": 1, "billNumber": 5, "couponCode": 3, "userId": 2, "billId": 4, "redeemedDateInMillis": 0, "details": 6}'

Sample Response

{
   "success":true,
   "status":200,
   "result":{
      "orgId":9619,
      "couponSeriesId":953234,
      "redeemUploadJobStatuses":[
         {
            "jobId":9137,
            "uploadRedeemedCouponStatus":"QUEUED",
            "createdOn":"1603263535389",
            "updatedOn":"1603263535389",
            "errorFileUrl":null,
            "successFileUrl":null,
            "uploadedFileUrl":"couponCode_9603263533789_253294.csv",
            "totalUploadedCount":0,
            "actualRowCount":0,
            "errorCount":0,
            "uploadTableName":null,
            "uploadedFileName":"couponCode_9603263533789_253294.csv"
         }
      ],
      "fileName":"couponCode_9603263533789_253294.csv"
   }
}

Resource Information

URI /coupon/api/v1/upload/redeemFile/{couponSeriesId}
Authentication oAuth
HTTP Method POST
Batch Support No

Request URL

{host1}/coupon/api/v1/upload/redeemFile/{couponSeriesId}

Header Required

Header Description
Content-Type* multipart/form-data
x-cap-api-oauth-token Generated authentication token

Request Query Parameters

Parameter Datatype Description
couponSeriesId* long Unique ID of the coupon series for which you need to upload redeemed coupons.

Request Body Parameters

Parameter Datatype Description
customerIdentifier* enum Unique identifier of the customer to update redeemed coupons. Values: MOBILE, EXTERNAL_ID, EMAIL, USER_ID.
couponIdentifier* enum Coupon identifier used. Value: COUPON_ID, COUPON_CODE.
file* file The CSV file that contains information of redeemed coupons. Each row in CSV file can contain following fields(columns marked with * are mandatory).

- Customer identifier* : Field used to identify the customer, it can be userId, mobile, email or externalId. (userId will have more preference over the other customer identifiers, in case of multiple values)
- Coupon identifier* : Field used to identify the redeemed coupon, It can be couponId, couponCode. (couponId has more preference over couponCode in case of multiple values)
- Redeemed date in milliseconds* : Coupon redeemed time in Epoch
- Redeemed at* : Coupon redeemed till’s Id
- Bill Id : Transaction Id
- Bill Number : Transaction Number Details.

Sample file content:
- File content sample 1:
       redeemed date in millis, redeemed at, user id, coupon id, bill id, bill number, details
        1603128622000,50015497,23599838,23456,1603128596000
       luci_auto_15039.
- File content sample 2:
       redeemed date in millis, redeemed at, mobile, coupon code ,bill id, bill number, details
       1603128622000,50015497,9876543210,ABCDEF1,1603128596000
       luci_auto_15039
uploadHeaders* int The sequence (starts from 0) of the columns in the attached csv file. This field accepts stringified JSON.
Key name for columns are as follows:

Key name for the columns are as follows
- Customer identifier* : Key name for this field varies according to the customerIdentifier param.
       MOBILE : mobile
       EXTERNAL_ID: externalId
       EMAIL: email
       USER_ID: userId
- Coupon identifier* : Key name for this field varies according to the couponIdentifier param.
       COUPON_ID: couponId
       COUPON_CODE: couponCode
- Redeemed date in milliseconds* : redeemedDateInMillis
- Redeemed at* : redeemedAt
- Bill Id : billId
- Bill Number : billNumber
- Details : details

For the above file samples, the uploadHeaders will be -
       Sample 1 - {‘redeemedDateInMillis’: 0, ‘redeemedAt’: 1, ‘billNumber’: 5, ‘couponId’: 3,
       ‘userId’: 2, ‘billId’: 4, ‘details’: 6}
       Sample 2 - {‘redeemedDateInMillis’: 0, ‘redeemedAt’: 1, ‘billNumber’: 5, ‘couponCode’: 3,
       mobile: 2, ‘billId’: 4, ‘details’: 6}
Details string Any additional details or notes to capture for redeemed coupon upload.

Get Status of Uploaded Coupons

Retrieves the status of a coupon upload job.

Sample Request

curl -i -X GET 
https://eu.intouch.capillarytech.com/coupon/api/v1/upload/getUploadStatus/253234 
-H 'Content-Type: application/json' 
-H 'x-cap-api-oauth-token: 

eyJraWQiOiJrMSIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJDYXBpbGxhcnkiLCJleHAiOjE2MDMyNjQ4NzksImp0aSI6IlBEV0JLRXZCTFh0VUZEdnhvbkFoNFEiLCJpYXQiOjE2MDMyNjQyNzksInN1YiI6InJlZGVtcHRpb24gaW1wb3J0IGNvdXBvbnMiLCJjbGllbnRfaWQiOjEyNjEsIm9yZ19pZCI6MTYxOSwidG9rZW5fdXNlIjoidG9rZW5fYWNjZXNzIiwiY2xpZW50X2tleSI6IldUMFQzcFdpU1JOTGFvdFBrbWFiWGR3VVgiLCJkZWZhdWx0X3RpbGwiOjE1MTQ3MTEwLCJzY29wZXMiOiJbe1wicGVybWlzc2lvblwiOlwiUkVBRFdSSVRFXCIsXCJlbnRpdHlJZFwiOjEsXCJyZXNvdXJjZXNcIjpbXCIuKnYxLjEvY3VzdG9tZXIvLipcIl19LHtcInBlcm1pc3Npb25cIjpcIlJFQURXUklURVwiLFwiZW50aXR5SWRcIjoyLFwicmVzb3VyY2VzXCI6W1wiLip2MS4xL3RyYW5zYWN0aW9uLy4qXCJdfSx7XCJwZXJtaXNzaW9uXCI6XCJSRUFEV1JJVEVcIixcImVudGl0eUlkXCI6MyxcInJlc291cmNlc1wiOltcIi4qdjEuMS9wb2ludHMvLipcIl19LHtcInBlcm1pc3Npb25cIjpcIlJFQURXUklURVwiLFwiZW50aXR5SWRcIjo0LFwicmVzb3VyY2VzXCI6W1wiLipcIl19XSJ9.xZuDQbcoekA7NsRZnNYTo1eIzjMeATccbmiR9lUdTeLZjRo453GqiBhezIfafw6GBYaDkOrJcjJCRscJt2cSlUUi8jw2z1QIuJLYIS2kQ_BFvuOUuc0p3olgyEjPdRNK3gqdD9gfQSK92_o05xLSOM205nBUeFrgaFUjuU30XcxfXOe6J7e61tOMAyxH-7ESAycOO4lo78iaSWpjio33n0rW4ngJ6PwrZQxN14JIrNkOit_r8CuZtqOTwYpF7SbZY9JG1wmYu4MT08J00neUS7j-QU9cgUaJAkd8pzoi6HhaZfpIjPaf3rSvB6doWmofyhDQc0jtVZK1iQqTovSOBg'

Sample Response

{
   "success":true,
   "status":200,
   "result":{
      "orgId":2345,
      "couponSeriesId":253543,
      "uploadJobStatuses":[
         {
            "jobId":93477,
            "uploadStatus":"FINISHED",
            "createdOn":"1603101625000",
            "updatedOn":"1603101632000",
            "errorFileUrl":"error_1619_2532342020_10_19_15_30_32",
            "successFileUrl":null,
            "uploadedFileUrl":"couponCode_1603101623721_253234.csv",
            "totalUploadedCount":3,
            "actualRowCount":3,
            "errorCount":3,
            "uploadTableName":"temp_1619_20201019_153531582",
            "uploadedFileName":"couponCode.csv",
            "audienceGroupId":0,
            "audienceGroupVersionId":0
         }
      ]
   }
}

Resource Information

URI coupon/api/v1/upload/getUploadStatus/{couponSeriesId}
HTTP Method GET
Authentication OAuth
API Version v1
Batch Support No

Request Header

Content-Type application/json
x-cap-api-oauth-token Generated authentication token

Request URL

https://{host}/coupon/api/v1/upload/getUploadStatus/{couponSeriesId}

Request Query Parameters

Parameter Datatype Description
couponSeriesId* long The ID of coupon series for which you want to get the status.

Get Status of Redeemed Coupons

Retrieves the status of the uploaded coupon redeem job a coupon series.

Sample Request

curl -i -X GET 
https://crm-nightly-new.cc.capillarytech.com/coupon/api/v1/upload/getUploadRedeemedCouponStatus/253234 
-H 'Content-Type: application/json' 
-H 'x-cap-api-oauth-token: eyJraWQiOiJrMSIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJDYXBpbGxhcnkiLCJleHAiOjE2MDMyNjM5MjQsImp0aSI6InlRQmxQS2pvVlhJRmZiM2xjNk9SU2ciLCJpYXQiOjE2MDMyNjMzMjQsInN1YiI6InJlZGVtcHRpb24gaW1wb3J0IGNvdXBvbnMiLCJjbGllbnRfaWQiOjEyNjEsIm9yZ19pZCI6MTYxOSwidG9rZW5fdXNlIjoidG9rZW5fYWNjZXNzIiwiY2xpZW50X2tleSI6IldUMFQzcFdpU1JOTGFvdFBrbWFiWGR3VVgiLCJkZWZhdWx0X3RpbGwiOjE1MTQ3MTEwLCJzY29wZXMiOiJbe1wicGVybWlzc2lvblwiOlwiUkVBRFdSSVRFXCIsXCJlbnRpdHlJZFwiOjEsXCJyZXNvdXJjZXNcIjpbXCIuKnYxLjEvY3VzdG9tZXIvLipcIl19LHtcInBlcm1pc3Npb25cIjpcIlJFQURXUklURVwiLFwiZW50aXR5SWRcIjoyLFwicmVzb3VyY2VzXCI6W1wiLip2MS4xL3RyYW5zYWN0aW9uLy4qXCJdfSx7XCJwZXJtaXNzaW9uXCI6XCJSRUFEV1JJVEVcIixcImVudGl0eUlkXCI6MyxcInJlc291cmNlc1wiOltcIi4qdjEuMS9wb2ludHMvLipcIl19LHtcInBlcm1pc3Npb25cIjpcIlJFQURXUklURVwiLFwiZW50aXR5SWRcIjo0LFwicmVzb3VyY2VzXCI6W1wiLipcIl19XSJ9.plHd64-7bxkse3BIAUR1rz_SjoeeITDcKe675LQOd1okIxggdwP3Tv3Wt7z72Z7O3TiLpzHT_k5lGenuW3Ds7enNfzt3yNRnAPCWpVN-yHXwSQDulJErcGd6iWDId_tKEjy2Ihgy5_a7ZZTDMUiItjqOyaScQZuP-6E4R7YpXSKMNK8_sQdud8SvXNe-oGE9Hgq3yNljMpPzUKtsNIis_Gd__qNxuAZPdOX1mikf1qfK0q-TOmOK7ZDmcl9WCV4IoSQvo7-gNd81rL6qXxtQsMkvixjq_HIq6I2zGuT6s06ZlYD3fe1Sx3p4jUAzpj6ygP-E67nxewaOaiLKW4xLOA'

Sample Response

{
   "success":true,
   "status":200,
   "result":{
      "orgId":9838,
      "couponSeriesId":909234,
      "redeemUploadJobStatuses":[
         {
            "jobId":4455,
            "uploadRedeemedCouponStatus":"COMPLETED",
            "createdOn":"1603132200000",
            "updatedOn":"1603132200000",
            "errorFileUrl":"error_redemption_upload_1619_2532342020_10_20_14_17_00",
            "successFileUrl":null,
            "uploadedFileUrl":"couponCode_1603183613031_253234.csv",
            "totalUploadedCount":1,
            "actualRowCount":1,
            "errorCount":1,
            "uploadTableName":"temp_redemption_upload_1619_20201020_141700172",
            "uploadedFileName":"couponCode_1603183613081_259234.csv"
         },
         {
            "jobId":4456,
            "uploadRedeemedCouponStatus":"COMPLETED",
            "createdOn":"1603132200000",
            "updatedOn":"1603132200000",
            "errorFileUrl":"error_redemption_upload_1619_2532342020_10_20_17_33_14",
            "successFileUrl":null,
            "uploadedFileUrl":"couponCode_1603195385330_253234.csv",
            "totalUploadedCount":1,
            "actualRowCount":1,
            "errorCount":1,
            "uploadTableName":"temp_redemption_upload_1619_20201020_173313820",
            "uploadedFileName":"couponCode_1603195345330_253564.csv"
         },
         {
            "jobId":4457,
            "uploadRedeemedCouponStatus":"COMPLETED",
            "createdOn":"1603218600000",
            "updatedOn":"1603218600000",
            "errorFileUrl":"error_redemption_upload_1619_2532342020_10_21_12_29_00",
            "successFileUrl":null,
            "uploadedFileUrl":"couponCode_1603263533789_253234.csv",
            "totalUploadedCount":1,
            "actualRowCount":1,
            "errorCount":1,
            "uploadTableName":"temp_redemption_upload_1619_20201021_122859950",
            "uploadedFileName":"couponCode_1603263533789_253234.csv"
         }
      ]
   }
}

Resource Information

URI /coupon/api/v1/upload/getUploadRedeemedCouponStatus/{couponSeriesId}
HTTP Method GET
Authentication OAuth
API Version v1
Batch Support No

Headers Required

Header Value
Content-Type* application/json
x-cap-api-oauth-token* Generated authentication token

Request URL

https://{host}/coupon/api/v1/upload/getUploadRedeemedCouponStatus/{couponSeriesId}

Request Parameters

Parameter Datatype Description
couponSeriesId* int The ID of coupon series for which the user wants to know the redeem status.

Response Codes

Error Codes

Code Description
400 Incorrect or invalid input.
500 Unable to post or retrieve details.

Points

Points represent loyalty points issued to customers through Loyalty+, Engage+, GoodWill (Member Care), or Data Import. Customers can redeem the points within the validity period and can also transfer their points to other loyalty customers.

Check if Points Transferrable (Customer)

Checks if specific points of a customer can be transferred to an other customer. You can also issue OTP that is used to authenticate customer to transfer points (pointsTransfer API).

Sample Request

https://eu.api.capillarytech.com/v2/points/isTransferrable

Sample POST Request

{
  "pointsTobeTransferred": 10,
  "groupProgramTransfer": "false",
  "notes": "Sample notes",
  “programId”: 141,
  "fromCustomerIdentifier": {
    "type": "MOBILE",
    "value": "7799497290"
  },
  "toCustomerIdentifier": {
    "type": "ID",
    "value": "342953257"
  },
  "issueOtp": true
}

Sample Response

{ 
   "data":[ 
      { 
         "pointsTobeTransferred":10,
         "transferFrom":{ 
            "id":32429961,
            "profiles":[ 
               { 
                  "firstName":"Tom",
                  "lastName":"Sawyer",
                  "attribution":{ 
                     "createDate":"2018-03-05T15:52:47+05:30",
                     "createdBy":{ 
                        "id":15041276,
                        "code":"org2.till1",
                        "name":"org2.till1",
                        "type":"TILL"
                     },
                     "modifiedBy":{ 
                        "id":15041276,
                        "code":"org2.till1",
                        "name":"org2.till1",
                        "type":"TILL"
                     },
                     "modifiedDate":"2019-08-14T12:48:31+05:30"
                  },
                  "fields":{ 

                  },
                  "identifiers":[ 
                     { 
                        "type":"mobile",
                        "value":"919111111111"
                     }
                  ],
                  "commChannels":[ 
                     { 
                        "type":"mobile",
                        "value":"919111111111",
                        "primary":true,
                        "verified":false,
                        "meta":{ 
                           "residence":false,
                           "office":false
                        },
                        "attributes":{ 

                        }
                     }
                  ],
                  "source":"INSTORE",
                  "userId":32429961,
                  "accountId":"",
                  "conflictingProfileList":[ 

                  ],
                  "autoUpdateTime":"2019-09-24T02:29:31+05:30"
               }
            ],
            "loyaltyInfo":{ 
               "loyaltyType":"loyalty",
               "attributionV2":{ 
                  "createDate":"2018-03-05T15:52:47+05:30",
                  "createdBy":{ 
                     "id":15041276,
                     "code":"org2.till1",
                     "name":"org2.till1",
                     "type":"TILL"
                  },
                  "modifiedBy":{ 
                     "id":15041276,
                     "code":"org2.till1",
                     "name":"org2.till1",
                     "type":"TILL"
                  },
                  "modifiedDate":"2019-08-14T12:48:31+05:30"
               }
            },
            "segments":{ 

            },
            "extendedFields":{ 

            }
         },
         "transferTo":{ 
            "id":342953257,
            "profiles":[ 
               { 
                  "firstName":"autofn_9294476894",
                  "lastName":"autoln_9294476894",
                  "attribution":{ 
                     "createDate":"2019-09-18T16:40:10+05:30",
                     "createdBy":{ 
                        "id":15041276,
                        "code":"org2.till1",
                        "name":"org2.till1",
                        "type":"TILL"
                     },
                     "modifiedBy":{ 
                        "id":15041276,
                        "code":"org2.till1",
                        "name":"org2.till1",
                        "type":"TILL"
                     },
                     "modifiedDate":"2019-09-18T16:40:10+05:30"
                  },
                  "fields":{ 

                  },
                  "identifiers":[ 
                     { 
                        "type":"email",
                        "value":"james.f@example.com"
                     },
                     { 
                        "type":"mobile",
                        "value":"919294111111"
                     },
                     { 
                        "type":"externalId",
                        "value":"ext_id92944768"
                     }
                  ],
                  "commChannels":[ 
                     { 
                        "type":"email",
                        "value":"james.f@example.com",
                        "primary":true,
                        "verified":false,
                        "meta":{ 
                           "residence":false,
                           "office":false
                        },
                        "attributes":{ 

                        }
                     },
                     { 
                        "type":"mobile",
                        "value":"919294476894",
                        "primary":true,
                        "verified":false,
                        "meta":{ 
                           "residence":false,
                           "office":false
                        },
                        "attributes":{ 

                        }
                     }
                  ],
                  "source":"INSTORE",
                  "userId":342953257,
                  "accountId":"",
                  "conflictingProfileList":[ 

                  ],
                  "autoUpdateTime":"2019-09-24T02:29:31+05:30"
               }
            ],
            "loyaltyInfo":{ 
               "loyaltyType":"loyalty",
               "attributionV2":{ 
                  "createDate":"2019-09-18T16:40:10+05:30",
                  "createdBy":{ 
                     "id":15041276,
                     "code":"org2.till1",
                     "name":"org2.till1",
                     "type":"TILL"
                  },
                  "modifiedBy":{ 
                     "id":15041276,
                     "code":"org2.till1",
                     "name":"org2.till1",
                     "type":"TILL"
                  },
                  "modifiedDate":"2019-09-18T16:40:10+05:30"
               }
            },
            "segments":{ 

            },
            "extendedFields":{ 

            }
         },
         "transferrable":true
      }
   ],
   "warnings":[ 

   ],
   "errors":[ 

   ]
}

Resource Information

URI /isTransferrable
Rate Limited? No
Authentication Yes
HTTP Methods POST
Batch Support No

Request URL

https://{host}/v2/points/isTransferrable

Request Body Parameters

Parameter Type Description
programId** long Program ID from which points has to be transferred. Applicable for multi-program orgs.
notes string Any information to store for the current transfer activity.
pointsTobeTransferred* int Number of points that customer wants to transfer.
fromCustomerIdentifier* obj Details of source customer - customer that wants to transfer points.
toCustomerIdentifier* obj Details of destination customer - customer to whom the points have to be transferred.
type* enum Customer identifier type. Values: ID (user id of the customer), MOBILE, EXTERNAL_ID, EMAIL.
value* string The value of the specified identifier.
issueOtp** Boolean Sends OTP to the fromCustomer if the specified points are transferrable. Use this to issue OTP (used to authenticate fromCustomer to transfer points) if isPointsTransferrable is successful. If false (default value) then no OTP is generated. However, you cannot transfer points without OTP. You need to only pass issueOtp as true to transfer points.

Check if Points Transferrable (Group)

Checks if specific points from one account can be transferred to another account (group to customer, customer to a group, or one group to another).

Sample Request

https://eu.api.capillarytech.com/v2/points/userGroup2/isTransferrable

Sample POST Request

{
    "pointsTobeTransferred": 10.5,
    "notes": "notes123",
    "programId": 765,
    "transferredBy": {
        "identifierType": "mobile",
        "identifierValue": "915410000000",
        "source": "WECHAT",
        "accountId": "WECHAT-SN"
    },
    "toEntity": {
        "type": "CUSTOMER",
        "identifierType": "mobile",
        "identifierValue": "918410000000",
        "accountId": "WECHAT-SN",
        "source": "WECHAT"
    },
    "fromEntity": {
        "type": "USERGROUP2",
        "identifierType": "id",
        "identifierValue": "1981"
    }
}

Sample Response

{
   "data":[
      {
         "pointsTobeTransferred":10.0,
         "transferrable":true
      }
   ],
   "warnings":[

   ],
   "errors":[

   ]
}

Resource Information

URI /userGroup2/isTransferrable
Rate Limited? No
Authentication Yes
HTTP Methods POST
Batch Support No

Request URL

https://{host}/v2/points/userGroup2/isTransferrable

Request Body Parameters

Parameter Type Description
pointsTobeTransferred* int Number of points to be transferred.
notes string Notes to add to the transfer activity.
programId** int Loyalty program ID from which points has to be transferred. Applicable for multi-program orgs. Considers the default program ID if not passed.
transferredBy* obj Details of the user who is transferring points. The user should have permission to transfer points.
toEntity* obj Details of the destination account (customer or group) - to which the points need to be transferred.
fromEntity* obj Details of the source account (group or customer) from which the points need to be transferred.
     type* enum Type of the entry. Value: CUSTOMER, USERGROUP2.
     identifierType* enum Identifier type to identify customer or group. Supported values for customer: mobile, email, externalId, cardnumber, wechat, martjackId, fbId.
Supported values for group: id, externalId.
     identifierValue* string Value of the specified identifierType.
     accountId string Account ID for sources with multiple account IDs.
     source** enum Source in which the customer account is available. Value: FACEBOOK, WEB_ENGAGE, WECHAT, INSTORE, MARTJACK, TMALL, TAOBAO, JD, ECOMMERCE, WEBSITE, LINE, MOBILE_APP. Required for customer entity.

Reverse Redeemed Points

Lets you reverse a set of points that are redeemed in a transaction. For example, you can use this API to reverse points redeemed for a transaction if the transaction is returned.

Prerequisites:

The following configurations are required for points/reverse API

Sample Request

https://eu.api.capillarytech.com/v2/points/reverse

Sample POST Request

{
"redemptionId":"54ZNkA",
"pointsToBeReversed": 10,
"identifier":
    {
    "type":"mobile",
    "value":"919740000000"
    }
}

Sample Response

{
    "redemptionId": "54ZNkA",
    "pointsToBeReversed": 20.0,
    "orgId": 100458,
    "identifier": {
        "type": "mobile",
        "value": "919740000000"
    },
    "customerId": 98662653,
    "pointsReversed": 20.0,
    "reversalId": "5wyOZM",
    "warnings": []
}  

Resource Information

URI /reverse
Rate Limited? No
Authentication Yes
HTTP Methods POST
Batch Support No

Request URL

https://{host}/v2/points/reverse

Request Body Parameters

Parameter Type Description
redemptionId* long Unique reference ID generated for redeeming the points.
Identifier obj Customer details associated to the redemption.
type* enum Pass any of the registered identifiers of the customer. Supported values: mobile, email, externalId.
value* string Pass the respective identifier value. This should match with the identifier tagged to the redemption id
pointsToBeReversed int The number of points be reversed.

Transfer Points (Customer to Customer)

Transfers points from one customer account to another customer account by validating the OTP issued for the points transfer.

Sample Request

https://eu.api.capillarytech.com/v2/points/transfer

Sample POST Request

{ 
   "pointsTobeTransferred":123,
   "groupProgramTransfer": "false",
   "programId": 141,
   "notes": "Transferred on 16th July 2021",
   "fromCustomerIdentifier":{ 
      "type":"MOBILE",
      "value":"7799000000"
   },
   "toCustomerIdentifier":{ 
      "type":"ID",
      "value":"342953257"
   },
   "code":"X12Y3Z"
}

Sample Response

{ 
   "data":[ 
      { 
         "pointsTransferDate":"2021-07-16 15:53:42",
         "pointsTransferred":15.0,
         "transferId":100,
         "transferType":"DEDUCTION",
         "transferredFrom":{ 
            "userId":343015431,
            "firstName":"Tom",
            "lastName":"Sawyer"
         },
         "transferredTo":{ 
            "userId":342953257,
            "firstName":"James",
            "lastName":"Thomas"
         },
         "notes":"Transfer points to James",
         "programName":"Nightly_ApiAutoDefaultProgram"
      }
      ]
}

Resource Information

URI /transfer
Rate Limited? No
Authentication Yes
HTTP Methods POST
Batch Support No