Back to top

Annex Cloud API - v3

The Annex Cloud API allows one to read, write and update data into and out of the Annex Cloud platform.

PRIOR TO USING THIS API, YOU MUST AGREE TO OUR TERMS OF USE

To develop your application, for base URLs use staging environment: https://s15.stage.socialannex.net/api/3.0 and to deploy your applications use production environment: https://s15.socialannex.net/api/3.0

Introduction

This section describes the general rules and guidelines applicable across all public APIs.

Date Format

All TIMESTAMPs should be formatted based on RFC 3339 specifications, specifically to this format: yyyy-MM-dd'T'HH:mm:ssZ

Ex: 2015-04-12T14:01:44-0700


Range header support(Not Implemented)

All collections/lists support Range header to fetch partial lists (HTTP 206)

  • Request Header
Range:items=25-34
  • Response Header
Content-Range:items 25-34/40

Error Handling

The common HTTP Response Status Codes are used and below error object

  • Response
{
        "errorCode": "AC1001",
        "errorMessage": "Oops! Something went wrong"
    }

ErrorCode and ErrorMessage

  • AC1001 : Oops! Something went wrong

  • AC1002 : Request Not Authorized

  • AC1003 : Method Not Allowed

  • AC1004 : Missing Parameters

  • AC1005 : No data found

  • AC1006 : Data already exists

  • AC1007 : Invalid Parameters

  • AC1008 : User is blocked

  • AC1009 : Opt out user

  • AC1010 : Duplicate order ID

Authentication

APIs related to authentication are described here

Creating Client Access Token

It will be better if you use the library from here https://jwt.io/.

JWT (JSON Web Token) need to be created by consumer application using below claimset.

Header

  • alg : Algorithm used for JWT i.e. HS256

  • typ : Token type i.e. JWT

Payload

  • sub

    • Data Type: String
    • Client company name: as agreed during integration discussion (the value could actually be anything won’t affect execution result)
  • exp

    • Data type: Number / String
    • Token expiry timestamp in UTC (show timestamp in seconds in number, for example, 2019/09/16 22:50:28 -> 1568674228)
  • site_id

    • Data Type: Number / String
    • Annex Cloud site ID assigned to client
  • hmac

    • Data Type: String
    • This will be HMACSHA256 for json object using a shared secret. JSON object will be one of the following
      • payload for POST/PATCH APIs
      • URL params for GET APIs
    • For POST/PATCH request
      • transfer payload into json format & parse special character => str_json
        • In php we use “json_encode” function which not only format payload to JSON but also escape non-ASCII characters (for example, Chinese characters “零一”) into ASCII escape sequences (“零一” => “\u96f6\u4e00”)
        • Please note that if you have non-ASCII characters in payload but skipped escape process, JWT authentication might fail
      • base64 encode str_json => encoded_payload
      • use the same secret key to encrypt encoded_payload with sha256 => encrypted_payload
      • base64 encode encrypted_payload => hmac value

    PHP code example to generate a hmac for POST/PATCH:

{
        //POST
        //Create User & Opt-in User API
        $payload = [     
                    "id" => '2',
                    "email" => '[email protected]',
                    "firstName" => 'Abrar',
                    "lastName" => 'Khan'
        ];
 
        $payload = json_encode($payload);
        $payload = base64_encode($payload);
        $hmac= base64_encode(hash_hmac('sha256',$payload, $key, true));        
    }

- For GET request:
    - There’s at most 1 param in Annex Cloud GET requests. So take it and transfer into json format & => str\_json
        - In php we use “json\_encode” function which not only format payload to JSON but also escape non-ASCII characters (for example, Chinese characters “零一”) into ASCII escape sequences (“零一” => “\u96f6\u4e00”)
        - Please note that if you have non-ASCII characters in payload but skipped escape process, JWT authentication might fail
    - follow the exact same step 2-4 as POST request above to generate hmac value.


PHP code example to generate a hmac for GEST:

    {
        // Get User Details API
        // GET /users/{id}
        // id = manojit9@gmail.com
        $payloadUserGet = '[email protected]';
        $payload = json_encode($payloadUserGet);
    }

- Pls note, when you send out the http POST/PATCH requests, the request body must be IDENTICAL to the raw payload you used to encode and encrypted into hmac. Mismatching will cause “401 Unauthorized” error.

Signature

  • JWT need to be signed using a shared secret.

  • HMACSHA256(base64urlencoded (JWT_Header) + “.” + base64urlencoded(JWT_Payload), sharedsecret)

JWT_ccess_token:

base64urlencoded(JWT_Header).base64urlencoded(JWT_Payload).JWT_Signature

Using Client Access Token

To use the public APIs, you will need to add the Authorization, X-AnnexCloud-Site and Content-Type headers to your requests. Replace JWT_access_token with the actual value of token

Authorization: Bearer JWT_access_token
X-AnnexCloud-Site: <site_id>
Content-Type: application/json

Users

APIs related to Users are described in this section

User Creation

Create a User
POST/users

This API is used to create the user in the database and add that particular user to the loyalty program.

INPUT Parameter Parameter Description Parameter Type
id (Mandatory) Enter the user’s unique id. string
email Enter the user’s email address. (Require a valid email address, in case of “Invalid Parameters” error) string
firstName Enter the user’s first name. string
lastName Enter the user’s last name. string
optInStatus Pass the opt-in status as YES for opt in and NO for opt out. By default, it will be YES. string
status Pass the user status as ACTIVE (default) or INACTIVE string
phone Enter the user’s phone number. string
birthDate Enter the user’s birthdate. date (yyyy-mm-dd)
anniversaryDate Enter the anniversary date which is either birthday or loyalty program joining date. date (yyyy-mm-dd)
userProfileImageUrl Enter the user’s profile image url string
extendedAttribute Enter the attribute keys and their values apart from the ones which are mentioned above. (according to client’s request) string
OUTPUT fields Field Description
id Return the unique id.
email Returns the email address of the user.
firstName Returns the first name of the user.
lastName Returns the last name of the user.
optInStatus Return the opt-in status of the user.
status Returns the status of the user if the user is active or inactive. By default it will be active, and can be changed to inactive if the client requests.
phone Returns the phone number of the user.
birthDate Returns the birthdate of the user in yyyy-MM-dd format.
anniversaryDate Returns the anniversary date of the user in yyyy-MM-dd format.
userProfileImageUrl Returns the url of the user’s profile image only if this parameter is passed while creating the user.
createDate Returns the date & time in yyyy-MM-dd’T’HH:mm:ssZ format on which the user was created.
updateDate Returns the date & time in yyyy-MM-dd’T’HH:mm:ssZ format on which the user was updated.
extendedAttribute Displays the extra user attributes which are added as per the client’s request.
errorCode Display only when the API request fails, this will denote the type of error.
errorMessage Displays the reason why the API request has been failed.

Example URI

POST .../users
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "[email protected]",
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "zipCode": "90002",
  "optInStatus": "YES",
  "status": "ACTIVE",
  "phone": "123-123-4567",
  "birthDate": "2018-04-01",
  "anniversaryDate": "2018-04-01",
  "createDate": "2018-04-01T00:00:00-0700",
  "updateDate": "2018-04-01T00:00:00-0700",
  "extendedAttribute": {
    "KEY1": "VALUE1",
    "KEY2": "VALUE2"
  }
}
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "[email protected]",
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "zipCode": "90002",
  "optInStatus": "YES",
  "status": "ACTIVE",
  "phone": "123-123-4567",
  "birthDate": "2018-04-01",
  "anniversaryDate": "2018-04-01",
  "createDate": "2018-04-01T00:00:00-0700",
  "updateDate": "2018-04-01T00:00:00-0700"
}
Response  401
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
    "errorCode": "AC1001",
    "errorMessage": "Oops! Something went wrong.",

}

View & Update User Details

View User Details
GET/users/{id}

OUTPUT field Field Description
id Return the unique id.
email Returns the email address of the user.
firstName Returns the first name of the user.
lastName Returns the last name of the user.
optInStatus Return the opt-in status of the user.
status Returns the status of the user if the user is active or inactive. By default it will be active, and can be changed to inactive if the client requests.
phone Returns the phone number of the user.
birthDate Returns the birthdate of the user in yyyy-MM-dd format.
anniversaryDate Returns the anniversary date of the user in yyyy-MM-dd format.
userProfileImageUrl Returns the url of the user’s profile image only if this parameter is passed while creating the user.
createDate Returns the date & time in yyyy-MM-dd’T’HH:mm:ssZ format on which the user was created.
updateDate Returns the date & time in yyyy-MM-dd’T’HH:mm:ssZ format on which the user was updated.
totalSpendCurrency Displays the total currency spent by the user.
extendedAttribute Displays the extra user attributes which are added as per the client’s request.
errorCode Display only when the API request fails, this will denote the type of error.
errorMessage Displays the reason why the API request has been failed.

Example URI

GET .../users/[email protected]
URI Parameters
HideShow
id
string (required) Example: [email protected]

ID of the user.

Response  200
HideShow
Body
{
  "id": "[email protected]",
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "zipCode": "90002",
  "optInStatus": "YES",
  "status": "ACTIVE",
  "phone": "123-123-4567",
  "birthDate": "2018-04-01",
  "anniversaryDate": "2018-04-01",
  "userProfileImageUrl": "https://www.socialannex.com/public/manageoptionsdesign16/images/product_landing/loyalty-hover.png",
  "createDate": "2018-04-01T00:00:00-0700",
  "updateDate": "2018-04-01T00:00:00-0700",
  "totalSpendCurrency": "150",
  "extendedAttribute": {
    "KEY1": "VALUE1",
    "KEY2": "VALUE2"
  }
}
Response  401
Response  400
HideShow
Body
{
    "errorCode": "AC1001",
    "errorMessage": "Oops! Something went wrong.",

}

Update User Details
PATCH/users/{id}

Method URL
PATCH /users/{id}
INPUT Parameter Parameter Description Parameter Type
id (Mandatory) Enter the user’s unique id. string
email Enter the user’s email address. (Require a valid email address, in case of “Invalid Parameters” error) string
updateId Pass the user’s new unique id (Optional but can’t be identical to id) string
firstName Enter the user’s first name. string
lastName Enter the user’s last name. string
optInStatus Pass the opt-in status as YES for opt in and NO for opt out. By default, it will be YES. string
status Pass the user status as ACTIVE (default) or INACTIVE string
phone Enter the user’s phone number. string
birthDate Enter the user’s birthdate. date (yyyy-mm-dd)
anniversaryDate Enter the anniversary date which is either birthdate or loyalty program joining date. date (yyyy-mm-dd)
userProfileImageUrl Enter the user’s profile image url string
extendedAttribute Enter the attribute keys and their values apart from the ones which are mentioned above. (according to client’s request) string
OUTPUT fields Field Description
id Return the unique id.
email Returns the email address of the user.
firstName Returns the first name of the user.
lastName Returns the last name of the user.
optInStatus Return the opt-in status of the user.
status Returns the status of the user if the user is active or inactive. By default it will be active, and can be changed to inactive if the client requests.
phone Returns the phone number of the user.
birthDate Returns the birthdate of the user in yyyy-MM-dd format.
anniversaryDate Returns the anniversary date of the user in yyyy-MM-dd format.
userProfileImageUrl Returns the url of the user’s profile image only if this parameter is passed while creating the user.
createDate Returns the date & time in yyyy-MM-dd’T’HH:mm:ssZ format on which the user was created.
updateDate Returns the date & time in yyyy-MM-dd’T’HH:mm:ssZ format on which the user was updated.
extendedAttribute Displays the extra user attributes which are added as per the client’s request.
errorCode Display only when the API request fails, this will denote the type of error.
errorMessage Displays the reason why the API request has been failed.

Example URI

PATCH .../users/[email protected]
URI Parameters
HideShow
id
string (required) Example: [email protected]

id of the user.

Request
HideShow
Headers
Content-Type: application/json
Body
{
    "id": "[email protected]",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "zipCode": "90002",
    "optInStatus": "YES",
    "status": "ACTIVE",
    "phone": ""123-123-4567",
    "birthDate": "2018-04-01",
    "anniversaryDate": "2018-04-01",
    "userProfileImageUrl": "https://www.socialannex.com/public/manageoptionsdesign16/images/product_landing/loyalty-hover.png",
    "extendedAttribute": {"KEY1": "VALUE1", "KEY2": "VALUE2"}
}
Response  200
HideShow
Body
{
    "id": "[email protected]",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "zipCode": "90002",
    "optInStatus": "YES",
    "status": "ACTIVE",
    "phone": ""123-123-4567",
    "birthDate": "2018-04-01",
    "anniversaryDate": "2018-04-01",
    "userProfileImageUrl": "https://www.socialannex.com/public/manageoptionsdesign16/images/product_landing/loyalty-hover.png",
    "createDate": "2020-03-10T18:40:18+0000",
    "updateDate": "2020-03-10T18:40:18+0000,
    "extendedAttribute": {"KEY1": "VALUE1", "KEY2": "VALUE2"}
}
Response  401
Response  400
HideShow
Body
{
    "errorCode": "AC1001",
    "errorMessage": "Oops! Something went wrong.",

}

User Activity API

Get User Activities
GET/users/{id}/activity

OUTPUT field Field Description
activityDetail actionId - Returns unique action identifier (in the SA system) used to identify user action/event.

customId - Displays the custom Id for the activity. When an activity has limitation, for example, 4x/year, each time you can assign a different customId

rewardId - Returns unique reward identifier (in the SA system) used to identify the reward.

activity - Returns the name of the activity.

credit/debit - Return the number of points credited or debited from the user’s account.

displayText - Returns the display text of the activity.

createDate - Returns the date in yyyy-mm-dd & time on which the points are awarded to the user.

expireDate - Returns the date in yyyy-mm-dd & time on which the points will expire.

pointStatus - Displays the point status as Hold, Redeemed, Release, etc.

holdPointReleaseDate - Displays the date on which hold points would be released
pages Displays the number of pages present in the user activity response. Every page will contain 10 activities performed by the user. If there are more than 10 activities then the response will be of more than 1 page.
currentPage Displays the current page number. If there are 2 pages of response then to access the response on the 2nd page, pass the following URL: http://s15.socialannex.net/api/3.0/users/[email protected]/activity?page=2
totalActivitiesCount Display total number of activities
errorCode Display only when the API request fails, this will denote the type of error.
errorMessage Displays the reason why the API request has been failed.

Example URI

GET .../users/[email protected]/activity
URI Parameters
HideShow
id
string (required) Example: [email protected]

ID of the user.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "activityDetail": 
    [
        {
            "actionId": "105",
            "customId": "xxxx",
            "activity": "CREDIT",
            "credit": "100",
            "displayText": "Join Rewards Program",
            "createDate": "2018-08-08T07:35:01+0000",
            "expireDate": "2019-08-08T23:59:59+0000"
        },
        {
            "rewardId": "24",
            "activity": "DEBIT",
            "debit": "100",
            "displayText": "$5 coupon",
            "createDate": "2018-08-08T07:55:30+0000"
        },
        {
            "actionId": "100",
            "activity": "CREDIT",
            "credit": "100",
            "pointStatus": "Released",
            "displayText": "Manual Credit/Debit",
            "createDate": "2019-04-23T12:14:29+0000",
            "expireDate": "2019-08-08T23:59:59+0000"
        },
        {
            "actionId": "109",
            "activity": "CREDIT",
            "credit": "50",
            "pointStatus": "Released",
            "displayText": "Purchase",
            "orderId": "TESTORDER04",
            "createDate": "2018-08-13T05:48:46+0000",
            "expireDate": "2019-08-15T23:59:59+0000"
        },
        {
            "actionId": "109",
            "activity": "CREDIT",
            "credit": "50",
            "pointStatus": "Hold", // "Released, "Redeem" , "Return", "Cancel", "Custom deduction
            "displayText": "Purchase",
            "orderId": "TESTORDER04",
            "createDate": "2018-08-13T05:48:46+0000",
            "expireDate": "2019-08-15T23:59:59+0000",
            "holdPointsReleaseDate": "2018-08-13T05:48:46+0000"
        }
    ],
    "pages": 1,
    "currentPage": 1,
    "totalActivityCount": 5
}
Response  401
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
    "errorCode": "AC1001",
    "errorMessage": "Oops! Something went wrong.",

}

Get Used Rewards API

Get Used Rewards
GET/users/{id}/usedreward

OUTPUT field Field Description
rewardCode Displays the reward code.
pointsUsed Displays the points used to redeem that reward.
rewardName Displays the name of the reward.
rewardStatus Displays the status of the reward.
reason Displays the reason.
createDate Displays the date on which the reward is claimed.
pages Display the total number of pages.
currentPage Displays the current page number.
errorCode Displays only when the API request fails, this will denote the type of error.
errorMessage Displays the reason why the API request failed

Example URI

GET .../users/[email protected]/usedreward
URI Parameters
HideShow
id
string (required) Example: [email protected]

ID of the user.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "rewardDetail": [
    {
      "rewardCode": "Code001",
      "pointsUsed": "100",
      "rewardName": "$5 coupon",
      "rewardStatus": "Claimed",
      "reason": "",
      "createDate": "2019-06-10T06:22:58+0000"
    },
    {
      "rewardCode": "Code002",
      "pointsUsed": "200",
      "rewardName": "$10 Reward",
      "rewardStatus": "Claimed",
      "reason": "",
      "createDate": "2019-06-10T07:22:54+0000"
    }
  ],
  "pages": 1,
  "current_page": 1
}
Response  401
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
    "errorCode": "AC1001",
    "errorMessage": "Oops! Something went wrong.",

}

Tier Actions

Get Tier Information
GET/users/{userId}/tiers

OUTPUT field Field Description
currentTier Returns the name of the tier.
nextTier Displays the name of the next tier.
pointsToNextTier Displays the number of points required to achieve the next tier.
purchaseRatio Displays the purchase ratio which will be applied to the user (from this tier) while earning purchase points.
currentTierPurchaseRatio Displays the purchase ratio which will be applied to the user for this tier while earning purchase points.
spendAmountToNextTier Displays the amount the user needs to spend to achieve the next tier.
errorCode Displays only when the API request fails, this will denote the type of error.
errorMessage Displays the reason why the API request failed.

Example URI

GET .../users/[email protected]/tiers
URI Parameters
HideShow
userId
string (required) Example: [email protected]

ID of the user.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "currentTier": "Silver",
  "nextTier": "Gold",
  "PointsToNextTier": "120",
  "purchaseRatio": "2",
  "currentTierPurchaseRatio": "0.5",
  "spendAmountToNextTier": ""
}
Response  401
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
    "errorCode": "AC1001",
    "errorMessage": "Oops! Something went wrong.",

}

Orders

APIs related to Orders are described in this section

Order Creation

Create a Order
POST/orders

You may create a new Order using this action.

INPUT Parameter Parameter Description Parameter Type
id (Mandatory) Enter the unique order id string
userId (Mandatory) Enter the user id string
email Enter the user’s email address (Require a valid email address, in case of “Invalid Parameters” error) string
firstName Enter the user’s first name string
lastName Enter the user’s last name string
eventId Enter the event identified for the user to check whether the order is referral or not. string
storeId Enter the store id integer
source Enter the source of the order i.e. web or store string
discountAmount Enter the discount amount if any float
coupon Enter the coupon code string
shippingAmount Enter the number of shipping points which you want to award string
orderDetail Pass the order details presented in the orderDetail object as follows (id, quantity and unitPrice are mandatory) :
id - Pass the product id
quantity - Pass the quantity of the product
unitPrice - Pass the unit price of the product
estimatedShipDate - Pass the estimated ship date in yyyy-MM-dd’T’HH:mm:ssZ format. Please notice, if estimatedShipDate is set to be before current date time, this product will be considered shipped out already, the hold point of this item will be released, and you can not cancel/ship it using AC API anymore.
categoryId - Pass the category id of the product.
categoryName - Pass the category name of the product.
url - Pass the product url.
imageUrl - Pass the product image url
description - Enter the product description.
autoDelivery - Pass Yes if you want to award points according to the minimum value set at the site admin else pass No. To activate this turn on the autoDelivery feature from the site admin.
object
OUTPUT field Field Description
id Displays the unique order id.
userId Returns the user id.
email Displays the email address of the user.
firstName Displays the first name of the user.
lastName Displays the last name of the user.
orderTotal Displays the total order amount.
eventId Displays the event identified for the user.
storeId Displays the store id.
source Displays the source of the order i.e. web or store.
pointsAwarded Displays points awarded in this order
updatedAvailablePoints Display updated available points
updatedLifetimePoints Display updated lifetime points
discountAmount Displays the discount amount.
coupon Displays the coupon codes if applied.
orderDetail Displays the order details such as product id, quantity, unit price, estimated ship date, category id, category name, product url, image url, and description.
errorCode Displays only when the API request fails, this will denote the type of error.
errorMessage Displays the reason why the API request failed.

Example URI

POST .../orders
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "OD1",
  "userId": "[email protected]",
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "orderTotal": "125.20",
  "eventId": "1234",
  "coupon": [
    "SARL0RXQ12017",
    "SAZRLJ8Q12017"
  ],
  "orderDetail": [
    {
      "id": "P1",
      "quantity": "1",
      "unitPrice": "60.00",
      "netPrice": "60.00",
      "estimatedShipDate": "2018-04-01T14:00:00-0700",
      "categoryId": "C1",
      "categoryName": "flowers",
      "url": "domain.com/image.gif",
      "imageUrl": "domain.com/image.gif",
      "description": "XYZ Flowers",
      "coupon": [
        "SARL0RXQ12017",
        "SAZRLJ8Q12017"
      ]
    }
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "OD1",
  "userId": "[email protected]",
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe",
  "orderTotal": "125.20",
  "eventId": "1234",
  "coupon": [
    "SARL0RXQ12017",
    "SAZRLJ8Q12017"
  ],
  "orderDetail": [
    {
      "id": "P1",
      "quantity": "1",
      "unitPrice": "60.00",
      "netPrice": "60.00",
      "estimatedShipDate": "2018-04-01T14:00:00-0700",
      "categoryId": "C1",
      "categoryName": "flowers",
      "url": "domain.com/image.gif",
      "imageUrl": "domain.com/image.gif",
      "description": "XYZ Flowers",
      "coupon": [
        "SARL0RXQ12017",
        "SAZRLJ8Q12017"
      ]
    }
  ]
}
Response  401
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
    "errorCode": "AC1001",
    "errorMessage": "Oops! Something went wrong.",

}

Ship/Return/Cancel Order API

Ship/Return/Cancel Order
PATCH/orders/{id}

This API is used to change the status of the order. For Ship pass the status as “ship”, for a return pass the status as “return” and for cancel pass the status as “cancel” in the input parameter.

INPUT Parameter Parameter Description Parameter Type
orderId (mandatory) Pass the original order id string
status (mandatory) Pass the status as ship or return or cancel. string
orderDetail Pass the order details presented in the orderDetail object as follows
(only for Partial Ship/Return/Cancel, Do not pass for Full Ship)
(id, quantity and unitPrice are mandatory)
id - Pass the product id
quantity - Pass the quantity of the product
unitPrice - Pass the unit price of the product
OUTPUT field Field Description
orderId Returns the order id.
pointsAwarded Displays the number of points awarded to the user.
pointsRemoved Displays the number of points removed from the user’s account.
updatedAvailablePoints Displays the updated available points of the user.
updatedLifetimePoints Displays the updated lifetime points of the user.
updatedUserTier Displays the updated user tier.
errorCode Displays only when the API request fails, this will denote the type of error.
errorMessage Displays the reason why the API request failed.

Example URI

PATCH .../orders/[email protected]
URI Parameters
HideShow
id
string (required) Example: [email protected]

ID of the user.

Request
HideShow
Headers
Content-Type: application/json
Body
Partial Ship

{
    "orderId": "satestorder1",
    "status": "ship",
    "orderDetail": 
    [{
        "id": "P1",
        "quantity": "1",
        "unitPrice": "60.00"
    }]
}

Full Ship

{
    "orderId": "satestorder1",
    "status": "ship"
}

Partial Return

{
    "orderId": "satestorder1",
    "status": "return",
    "orderDetail": 
    [{
        "id": "P1",
        "quantity": "1",
        "unitPrice": "60.00"
    }]
}

Full Return

{
    "orderId": "satestorder1",
    "status": "return"
}

Partial Cancel

{
    "orderId": "satestorder1",
    "status": "cancel",
    "orderDetail": 
    [{
        "id": "P1",
        "quantity": "1",
        "unitPrice": "60.00"      
    }]
}

Full Cancel

{
    "orderId": "satestorder1",
    "status": "cancel"
}
Response  201
HideShow
Headers
Content-Type: application/json
Body
For Ship:
{
    "orderId": "satestorder1",
    "pointsAwarded": "60" 
}

For Return:
{
    "orderId": "satestorder1",
    "pointsRemoved": "60" ,
    "updatedAvailablePoints": "468",
    "updatedLifetimePoints": "768",
    "updatedUserTier": "Tier3" 
}

For Cancel:
{ 
    "orderId": "satestorder1",
    "pointsRemoved": "60" ,
    "updatedAvailablePoints": "1118",
    "updatedLifetimePoints": "1418",
    "updatedUserTier": "Tier3" 
}
Response  401
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
    "errorCode": "AC1001",
    "errorMessage": "Oops! Something went wrong.",

}

Points

APIs related to Points are described in this section

View Point Details

View Point Details
GET/points/{id}

OUTPUT field Field Description
id Displays the unique id of the user.
availablePoints Displays the available points of the user.
usedPoints Displays the used points of the user.
expiredPoints Displays the expired points of the user.
lifetimePoints Displays the number of points the user has earned since the account is created.
earnedPointsPeriod Displays the earned points period
spendPointsPeriod Displays the spend points period
earnedPoints Displays the total earned points in the select period
spendPoints Displays the total spend points in the selected period
holdPoints Displays the number of hold points.
usedPointsOnReward Displays the number of points used on the reward.
pointsToExpire Displays the number of points that are getting expired.
pointsToNextTier Displays the number of points needed to achieve the next tier.
pointsToExpireDate Displays the date (in yyyy-mm-dd format) on which the points will expire.
spendToNextTier Displays the number of dollars that the user needs to spend to achieve the next tier. (This field will be displayed only if the tier functionality is based on spend)
creditsToCurrencyRatio Displays the credits to currency ration set at the site admin.
creditsToCurrencyValue Displays the converted value of credits to currency according to the ratio.
errorCode Displays only when the API request fails, this will denote the type of error.
errorMessage Displays the reason why the API request failed.

Example URI

GET .../points/[email protected]
URI Parameters
HideShow
id
string (required) Example: [email protected]

ID of the user.

Response  200
HideShow
Body
{
    "id": "[email protected]",
    "availablePoints": "6656",
    "usedPoints": "600",
    "expiredPoints": "0",
    "lifetimePoints": "7256",
    "earnedPointsPeriod": "anniversaryYear",  //calenderYear,quarter,semester
    "spendPointsPeriod": "calenderYear",  //anniversaryYear,quarter,semester
    "earnedPoints": "1200",
    "spendPoints": "350",
    "holdPoints": 1000,
    "usedPointsOnReward": "600",
    "pointsToExpire": "56",
    "pointsToNextTier": 0,
    "spendToNextTier": 0,
    "pointsToExpireDate": "2020-01-30T05:30:00+0000",
    "creditsToCurrencyRatio": "1",
    "creditsToCurrencyValue": 6656
}
Response  401
Response  400
HideShow
Body
{
    "errorCode": "AC1001",
    "errorMessage": "Oops! Something went wrong.",

}

Points ADD/REMOVE

ADD/REMOVE points
POST/points

This API is used to give, redeem, award loyalty points to the user.

To give point for an action:

INPUT Parameter Parameter Description Parameter Type
id (mandatory) Enter the user’s unique id. string
actionId (Mandatory) Enter the action id (it is mandatory if the action id is set at the site admin). string
customId (Optional) Enter the Custom Id string
activity (Mandatory) Enter the activity as CREDIT string
reason Enter the reason for adding or removing the points. string

To redeem a reward:

INPUT Parameter Parameter Description Parameter Type
id (Mandatory) Enter the user’s unique id. string
rewardId (Mandatory) Enter the reward id (it is mandatory if the reward id is set at the site admin). string
activity (Mandatory) Enter the activity as CREDIT string
orderId (optional) For checkout integration, pass the order id string
reason Enter the reason for adding or removing the points. string
source (optional) Enter the source as web or store. string

To deduct custom points without an action:

INPUT Parameter Parameter Description Parameter Type
id (mandatory) Enter the user’s unique id. string
activity (Mandatory) Enter the activity as CREDIT string
orderId(optional) For checkout integration, pass the order id string
debit Displays the number of debited points string
reason Enter the reason for adding or removing the points string
source(optional) Enter the source as web or store. string

To award/deduct points for an action with open point value:

INPUT Parameter Parameter Description Parameter Type
id (mandatory) Enter the user’s unique id. string
actionId (Mandatory) Enter the action id. (for example action 100) string
activity (Mandatory) Enter the activity as CREDIT string
customId (Optional) Enter the Custom Id string
orderId(optional) For checkout integration, pass the order id string
credit/debit Enter the number of credited/debited points string
reason Enter the reason for adding or removing the points (If the actionId is not passed then the reason is mandatory) string
OUTPUT field Field Description
id Displays the unique customer id.
actionId Return the particular action id.
customId Displays the custom id.
activity Displays the action as credit or debit.
credit Displays the number of points credited in the user’s account.
pointsAwarded Displays the number of points awarded.
updatedAvailablePoints Displays the number of updated available points.
updatedLifetimePoints Displays the number of updated lifetime points.
updatedUserTier Displays the updated user tier.
releaseDate Displays the release date in yyyy-mm-dd format on which the hold points will be released.
reason Displays the reason for adding or removing the points.
errorCode Displays only when the API request fails, this will denote the type of error.
errorMessage Displays the reason why the API request failed.

Example URI

POST .../points
Request
HideShow
Headers
Content-Type: application/json
Body
To give point for an action:
{
  "id": "[email protected]",
  "actionId": "235",
  "customId": "xxxx",
  "activity": "CREDIT",
  "reason": "25 points for create account"
}

To redeem a reward:
{
  "id": "[email protected]",
  "rewardId": "111",
  "activity": "DEBIT",
  "orderId": "OD001",
  "reason":"claim"
  "source":"web"
}

To deduct custom points without an action:
{
  "id": "[email protected]",
  "activity": "DEBIT",
  "orderId": "OD001",
  "debit": "500",
  "reason":"used for purchase"
  "source":"web"
}

To award custom points with action 100:
{
  "id": "[email protected]",
  "actionId": "100",
  "customId": "xxxx",
  "activity": "CREDIT",
  "credit": "50",
  "reason":"bonus"
}

To deduct custom points with action 100:
{
  "id": "[email protected]",
  "actionId": "100",
  "activity": "DEBIT",
  "orderId": "OD001",
  "debit": "50",
  "reason":"adjustment"
}
Response  201
HideShow
Headers
Content-Type: application/json
Body
To give point for an action response:
{
    "id": "[email protected]",
    "actionId": 100,
    "customId": "xxxx",
    "activity": "CREDIT",
    "credit": 50,
    "pointsAwarded": 50,
    "reason": "aj Bonus",
    "updatedAvailablePoints": "7561",
    "updatedLifetimePoints": "7561",
    "updatedUserTier": "Gold"
}

To redeem a reward response:
{
  "id": "[email protected]",
  "rewardId": "111",
  "activity": "DEBIT",
  "orderId": "OD001",
  "debit": "500",
  "reason":"claim"
}

To deduct custom points without an action response:
{
  "id": "[email protected]",
  "activity": "DEBIT",
  "orderId": "OD001",
  "debit": "500",
  "reason":"used for purchase"
}

To award custom points with action 100 response:
{
  "id": "[email protected]",
  "actionId": "100",
  "customId": "xxxx",
  "activity": "CREDIT",
  "credit": "50",
  "reason":"bonus"
}

To deduct custom points with action 100 response:
{
  "id": "[email protected]",
  "actionId": "100",
  "activity": "DEBIT",
  "orderId": "OD001",
  "debit": "50",
  "reason":"adjustment"
}
Response  401
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
    "errorCode": "AC1001",
    "errorMessage": "Oops! Something went wrong.",

}

Cart Potential Points Calculation

Cart Potential Points Calculation
POST/cart

This API is used to calculate the potential points of the products which are in the user’s cart. The API will not work until Purchase Action is properly setup.

INPUT Parameter Parameter Description Parameter Type
userId (Mandatory) Enter the user’s unique id. string
appliedPoints Enter the number of points the user has applied (for redeem) on the cart page. string
shippingAmount Enter the number of shipping points which you want to award string
discountAmount Enter the discount amount if any. float
productDetail (Mandatory) Pass the array of product details presented in the productDetail object as follows (id, quantity & unitPrice are mandatory):
id - Pass the product id
quantity - Pass the quantity of the product
unitPrice - Pass the unit price of the product
autoDelivery - Pass YES if you want to award points according to the minimum value set at the site admin else pass NO.
string
OUTPUT field Field Description
userId Displays the unique customer id.
lifetimePoints Displays the lifetime points of the user.
usedPoints Displays the used points of the user.
availablePoints Displays the available points of the user.
holdPoints Displays the number of hold points of the user.
appliedPoints Displays the number of points the user has applied (for redeem) on the cart page.
cartPoints Displays the number of points the user will earn after purchasing the products which are in the cart.
availablePointsAfterOrder Displays the number of available points of the user after placing the order.
holdPointsAfterOrder Displays the number of hold points of the user after placing the order.
creditsToCurrencyRatio Displays the credits to currency ration set at the site admin.
creditsToCurrencyValue Displays the converted value of credits to currency according to the ratio.
creditsToCurrencyValueAfterOrder Displays the credits to currency value of total available points after the order is placed.
creditsToCurrencyValueCartPoints Displays the credits to the currency value of the current cart if the order is placed.
productDetails Returns an array of the product details which contains the following parameters.
id Displays the unique product id.
quantity Displays the quantity of the product.
unitPrice Displays the unit price of the product.
points Displays the number of points the user will earn after purchasing that product.
errorCode Displays only when the API request fails, this will denote the type of error.
errorMessage Displays the reason why the API request failed.

Example URI

POST .../cart
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "userId": "[email protected]",
  "appliedPoints": "200",
  "shippingAmount": "10",
  "discountAmount": "100",
  "productDetail": [
    {
      "id": "16160",
      "quantity": "1",
      "unitPrice": "1000",
      "autoDelivery": "YES"
    },
    {
      "id": "16161",
      "quantity": "1",
      "unitPrice": "500"
    }
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json
Body
An example of positive response is:
{
    "userId": "2fa81c89-8019-4c49-8ddd-c4f255a3d6d7",
    "lifetimePoints": "62976",
    "usedPoints": "255",
    "availablePoints": 62721,
    "holdPoints": 0,
    "appliedPoints": "200",
    "cartPoints": 250,
    "availablePointsAfterOrder": 62771,
    "holdPointsAfterOrder": 0,
    "creditsToCurrencyRatio": "0.03",
    "creditsToCurrencyValue": 1881.63,
    "creditsToCurrencyValueAfterOrder": 1883.13,
    "creditsToCurrencyValueCartPoints": 7.5,
    "productDetail": [
        {
            "id": "MERC",
            "quantity": "1",
            "unitPrice": "50",
            "points": 50
        },
        {
            "id": "PART",
            "quantity": "2",
            "unitPrice": "100",
            "points": 200
        }
    ]
}
Response  401
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
    "errorCode": "AC1001",
    "errorMessage": "Oops! Something went wrong.",

}

Others

APIs related to activities, segmentation, campaign are described in this section

Rewards List API

Get Rewards List
GET/users/{id}/reward

Example URI

GET .../users/[email protected]/reward
URI Parameters
HideShow
id
string (required) Example: [email protected]

ID of the user.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "creditsToCurrencyRatio": "0.05",
  "creditsToCurrencyValue": 5,
  "rewardDetail": [
    {
      "rewardId": "111",
      "rewardCategory": "",
      "displayText": "$5 off gift card",
      "creditRequired": "500",
      "eligible": "1",
      "rewardUrl": "www.example.com/reward",
      "rewardImageUrl": "www.example.com/example.png"
    },
    {
      "rewardId": "112",
      "rewardCategory": "",
      "displayText": "XYZ product",
      "creditRequired": "1000",
      "eligible": "0",
      "rewardUrl": "www.example.com/reward",
      "rewardImageUrl": "www.example.com/example.png",
      "productId": "P1"
    }
  ]
}
Response  401
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
    "errorCode": "AC1001",
    "errorMessage": "Oops! Something went wrong.",

}

Segment Detail API

Get Segment Detail
GET/segment/{segment_id}

This API is used to get the details of the segment.

Example URI

GET .../segment/444
URI Parameters
HideShow
segment_id
string (required) Example: 444

ID of the segment.

Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "segmentDetail": {
    "segmentName": "Global users",
    "segmentType": "Current Data",
    "segmentDateFromUTC": "0000-00-00T00:00:00-00:00",
    "segmentDateToUTC": "0000-00-00T00:00:00-00:00",
    "segmentDateFrom": "2019-04-01T00:00:00-07:00",
    "segmentDateTo": "2019-04-21T00:00:00-07:00",
    "memberDetails": {
      "userId": [
        "001",
        "002"
      ],
      "zipCode": [
        "411025",
        "411206"
      ],
      "anniversaryDate": "YES",
      "BirthDate": "YES"
    },
    "actionDetails": {
      "actions": [
        "Facebook Share",
        "Tweet"
      ],
      "actionSeries": [
        "First Purchase Review",
        "Purchase + Write a Review"
      ]
    },
    "pointsDetails": {
      "availablePointRangeFrom": "0",
      "availablePointRangeTo": "10",
      "lifetimePointRangeFrom": "0",
      "lifetimePointRangeTo": "10",
      "redeemPointRangeFrom": "0",
      "redeemPointRangeTo": "10"
    },
    "purchaseDetails": {
      "productPurchased": [
        "P1",
        "P2"
      ],
      "productCategory": [
        "Category 1",
        "Category 2"
      ],
      "source": "website",
      "country": "US"
    },
    "storeDetails": {
      "storeName": "Store 1",
      "country": "US",
      "region": "Bascom",
      "state": "Florida",
      "city": "Bascom"
    }
  }
}
Response  401
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
    "errorCode": "AC1001",
    "errorMessage": "Oops! Something went wrong.",

}

Campaign Detail API

Get Campaign Detail
GET/campaign/{campaign_id}

This API is used to get the details of the segment.

Example URI

GET .../campaign/555
URI Parameters
HideShow
campaign_id
string (required) Example: 555

ID of the campaign.

Response  201
HideShow
Headers
Content-Type: application/json
Body
{
  "campaignId": "123",
  "campaignName": "CampaignandSegment",
  "campaignDateFrom": "2019-11-14T00:00:00+0000",
  "campaignDateTo": "2019-11-30T00:00:00+0000",
  "campaignDescription": "",
  "campaignTerms": "",
  "campaignTagline": "",
  "audience": {
    "segment": "SegmentandCampaign",
    "tier": ""
  },
  "campaignStatus": "ACTIVE",
  "campaignGroupName": "",
  "campaignCreateDate": "2019-11-14 06:49:41",
  "campaignUpdateDate": "2019-11-14 07:05:20",
  "mileStone": [
    {
      "name": "",
      "description": "",
      "type": "",
      "detail": "",
      "benefitName": "",
      "benefitValue": "",
      "benefitActiveImageUrl": "",
      "benefitInactiveImageUrl": "",
      "benefitRedemptionDate": "0000-00-00 00:00:00"
    }
  ],
  "campaignBenefit": {
    "campaignBenefitType": "0",
    "campaignBenefitName": "",
    "campaignBenefitValue": "",
    "campaignBenefitImageUrl": "",
    "campaignBenefitExpirationDate": "0000-00-00 00:00:00"
  }
}
Response  401
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
    "errorCode": "AC1001",
    "errorMessage": "Oops! Something went wrong.",

}

Generated by aglio on 15 Mar 2020