Member APIs (1.0.0)

Download OpenAPI specification:Download

E-mail: support@fabric.inc License: fabric Inc

fabric Member is a Loyalty Management System (LMS) that enables marketers to create multiple loyalty strategies under a loyalty program to cater to various businesses and customer segments.
Member overview:
During onboarding, you are given the necessary credentials (client_id and client_secret) to obtain an access token, which is required to run every call. Membership hierarchy is organized into Programs, Clubs, and Tiers.
Program is the first hierarchy level and is where rewards and benefits are configured for the organization.
Club is the second hierarchy level and is where Rules for the program are configured.
Each Club must have at least one Tier, which is used to define membership and to configure criteria and thresholds (including free vs paid). Additional hierarchy levels can be added to support the needs of your business.
Members are always enrolled into a Default Tier within a club. When members make purchases, they earn Points based on the rules set at the club level and/or based on promotions. When points in a member account reach a predefined Threshold Value, points are converted to Rewards. This conversion may be manual or automatic depending on the program configuration. Members can Redeem their rewards within the reward Expiry Period. Account point balances are updated after each point-impacting activity.

Authentication

bearerAuth

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

Members

Enroll Member

After setting up your loyalty program with fabric, the next crucial step is to enroll members to the program. This endpoint enrolls a loyalty member into a default tier associated with a club.
Note: Only a single member can be enrolled at a time.

Request
Security:
Request Body schema: application/json
firstName
required
string (Firstname) [ 1 .. 100 ] characters

First name of the member.

middleName
string (Middlename) <= 100 characters

Middle name of the member.

lastName
required
string (Lastname) [ 1 .. 100 ] characters

Last name of the member.

suffix
string or null (Suffix) non-empty

Suffix of the member name, if any.

gender
string (Gender) non-empty

Gender of the member.

Enum: "Male" "Female" "Other"
birthDate
string <date> (Birthdate)

Date of birth of the member.

emailAddress
required
string <email> (Emailaddress) [ 1 .. 254 ] characters

Email address of the member.

phoneNumber
required
string (Phonenumber) [ 1 .. 16 ] characters

Phone number of the member (without space or dash).

addressLine1
string or null (Addressline1) <= 500 characters

Line 1 of the address.

addressLine2
string or null (Addressline2) <= 500 characters

Line 2 of the address.

addressLine3
string or null (Addressline3) <= 500 characters

Additional line for directional information.

city
string (City) <= 50 characters

City name of the address.

region
string (Region) <= 150 characters

State name of the address.

postalCode
string (Postalcode)

Zip code of the address.

country
string (Country) non-empty

Country name.

nationality
string (Country) non-empty

Nationality of the member.

maritalStatus
string (Maritalstatus)

Marital status of the member.

Enum: "None" "Single" "Married" "Divorced" "Widowed" "Separated"
prefix
string (Prefix)

Prefix (if appliable) of the member name.

Enum: "None" "Mr" "Mrs" "Ms"
redemptionChoice
string or null (Redemptionchoice) non-empty

Redemption choices are Bank and Auto. When the choice is 'auto,' the points are automatically converted to rewards. When the choice is 'bank,' the points are converted to rewards at the member’s request.

Enum: "Bank" "Auto"
redemptionThreshold
string or null (Redemptionthreshold)

Threshold value (configurable) to be able to redeem the reward.

entityReference
required
string (Entityreference) non-empty

Name or ID for the store (or entity) where the member is enrolled.

enrollmentTimestamp
string or null <date-time> (enrollmenttimestamp)

Date of member enrollment.

clubReference
required
string (Clubreference) non-empty

Club name or ID where the member is enrolled.

enrollReasonCode
string or null (Enrollreasoncode) <= 4 characters

Reason code for enrollment.

enrollReasonNote
string or null (Enrollreasonnote) <= 100 characters

The enrollment reason.

tierReference
string or null (Tierreference) non-empty

Tiers are always setup at the club level and a number of tiers can be created. Tiers are categorized as Free (Predefined names are Bronze, Silver, Gold) and Paid (Example - Pro).
Note: The tier names and the rules to move up and down the tiers are configurable. In addition, points, rewards, and tier expiration can be setup at the tier level.

customAttributes
object or null (customAttributes)

Inputs from the store (if applicable) and stored without validation.

sourceExternalReference
string or null (Sourceexternalreference) <= 100 characters

Website of the company used for member enrollment.

channelExternalReference
string or null (Channelexternalreference) <= 100 characters

Sales channel.

Responses
201

Created

400

Bad request

401

Unauthorized

post/v1/members
Request samples
application/json
{
  • "firstName": "John",
  • "middleName": "D",
  • "lastName": "Demo",
  • "suffix": "string",
  • "gender": "Male",
  • "birthDate": "1990-11-16",
  • "emailAddress": "abc@domain.com",
  • "phoneNumber": "923331234567",
  • "addressLine1": "10400 NE 4th St",
  • "addressLine2": "Suite 505",
  • "addressLine3": "string",
  • "city": "Bellevue",
  • "region": "Wisconsin",
  • "postalCode": "98004",
  • "country": "United States",
  • "nationality": "American",
  • "maritalStatus": "Single",
  • "prefix": "Ms",
  • "redemptionChoice": "Auto",
  • "redemptionThreshold": 10,
  • "entityReference": "BOUNTEE_CLUB",
  • "enrollmentTimestamp": "2021-01-25",
  • "clubReference": "BLOCK_A",
  • "enrollReasonCode": "1234",
  • "enrollReasonNote": "As guest member",
  • "tierReference": "Silver",
  • "customAttributes": { },
  • "sourceExternalReference": "example.com",
  • "channelExternalReference": "WEB"
}
Response samples
application/json
{
  • "message": "Exception message",
  • "errors": { },
  • "data": {
    },
  • "status": 200
}

Update Member

Updates details of an existing member.
Note: Only a single member can be updated at a time.

Request
Security:
Request Body schema: application/json
firstName
required
string (Firstname) [ 1 .. 100 ] characters

First name of the member.

middleName
string (Middlename) non-empty

Middle name of the member.

lastName
required
string (Lastname) [ 1 .. 100 ] characters

Last name of the member.

suffix
string (Suffix) non-empty

Suffix of the member name.

gender
string (Gender) non-empty

Gender of the member.

Enum: "Male" "Female" "Other"
birthDate
string <date> (Birthdate)

Date of birth of the member.

emailAddress
required
string <email> (Emailaddress) [ 1 .. 254 ] characters

Email address given during enrollment.

phoneNumber
string (Phonenumber) non-empty

Phone number given for enrollment (without space or dash).

addressLine1
string or null (Addressline1) <= 500 characters

Line 1 of the address.

addressLine2
string or null (Addressline2) <= 500 characters

Line 2 of the address.

addressLine3
string or null (Addressline3) <= 500 characters

An additional line for directional information.

city
string (City) <= 50 characters

City name of the address.

region
string (Region) <= 150 characters

State name of the address.

postalCode
string (Postalcode)

Zip code of the address.

country
string (Country) non-empty

Country name of the address.

maritalStatus
string (Maritalstatus)

Marital status of the member.

Enum: "None" "Single" "Married" "Divorced" "Widowed" "Separated"
prefix
string (Prefix)

Prefix (if appliable) of the member name.

Enum: "None" "Mr" "Mrs" "Ms"
redemptionChoice
string (Redemptionchoice) non-empty

The redemption options are Bank and Auto. If the redemptionChoice is 'auto,' the points are automatically converted to rewards. When the redemptionChoice is 'bank,' the points are converted to rewards at the member’s request.

Enum: "Bank" "Auto"
redemptionThreshold
string (Redemptionthreshold)
Default: "0.00"

Points can be redeemed only when they reach a defined threshold value.

enrollmentStore
string (enrollmentstore) non-empty

Name of the entity or store (physical entire/store or a website) where the member is enrolled.

enrollmentDate
string <date> (enrollmentdate)

Date of member enrollment.

lastPaidStatusCenter
string (Lastpaidstatuscenter) non-empty

Entity or store where the pro membership was purchased (for the paid tier).

lastPaidStatusDate
string <date> (Lastpaidstatusdate)

Date to update the paid status.

tierExpirationDatetime
string <date-time> (Tierexpirationdatetime)

Tier expiration date.

tierQualificationDatetime
string <date-time> (Tierqualificationdatetime)

Tier enrollment date.

customAttributes
object (customAttributes)

Represents the custom fields.

Responses
201

Created.

400

Bad request

401

Unauthorized

put/v1/members
Request samples
application/json
{
  • "firstName": "John",
  • "middleName": "M",
  • "lastName": "Williams",
  • "suffix": "string",
  • "gender": "Male",
  • "birthDate": "1980-11-30",
  • "emailAddress": "abc@domain.com",
  • "phoneNumber": "923331234567",
  • "addressLine1": "10400 NE 4th St",
  • "addressLine2": "Suite 505",
  • "addressLine3": "string",
  • "city": "Bellevue",
  • "region": "Wisconsin",
  • "postalCode": "98004",
  • "country": "United States",
  • "maritalStatus": "Single",
  • "prefix": "Mr",
  • "redemptionChoice": "Auto",
  • "redemptionThreshold": 10,
  • "enrollmentStore": "www.demostore.come",
  • "enrollmentDate": "2021-01-15",
  • "lastPaidStatusCenter": "1201",
  • "lastPaidStatusDate": "2021-01-15",
  • "tierExpirationDatetime": "2027-01-15",
  • "tierQualificationDatetime": "2021-01-15",
  • "customAttributes": "{joiningDate: 2021-07-26, confirmationDate: 2021-07-26}."
}
Response samples
application/json
{
  • "message": "Member updated",
  • "errors": "ExceptionString - Invalid fields",
  • "data": {
    },
  • "status": 200
}

Retrieve Member(s)

Retrieves the details of all members of a parent company. The results can narrowed down by using the query parameters. By specifying the loyaltyNumber or the profileId as query parameter, you can get details of a single member.
Note:
1) Member must be already part of the loyalty program.
2) The query parameter used to get results must be part of member information.

Request
Security:
query Parameters
loyaltyNumber
string

Loyalty number of the member. Either the loyaltyNumber or the profileId must be specified. It is generated in the response of the Enroll Member endpoint - POST /v1/members/.

ProfileId
string

Profile ID of the member. Either the loyaltyNumber or the profileId must be specified. It is generated in the response of the Enroll Member endpoint - POST /v1/members/.

redemptionChoice
string

Redemption choice. Supported options are Bank and Auto. If the redemptionChoice is 'auto,' the points are automatically converted to rewards. When the redemptionChoice is 'bank,' the points are converted to rewards at the member’s requests.

firstName
string

First name of the member.

Example: firstName=Sam
middleName
string

Middle name of the member.

Example: middleName=M
lastName
string

Last name of the member.

Example: lastName=Demo
phone
string

Phone number given for enrollment (without space or dash).

Example: phone=923331234567
email
string

Email address given for enrollment.

Example: email=john.demo@test.com
address
string

Address of member.

postalCode
string

Postal code of the address.

Example: postalCode=98004
city
string

City name

Example: city=Bellevue
countryName
string

Country name

Example: countryName=United State
countryAbbreviation
string

Abbreviation of the country name.

Example: countryAbbreviation=US
regionName
string

State name

Example: regionName=Washington
regionAbbreviation
string

Abbreviation of the state name.

Example: regionAbbreviation=WA
offset
integer

The starting number of record (within the total number of records) in the response. Default value is 0.

limit
integer

The ending number of record (from the offset number) in the response. Default value is 20.

Responses
201

OK

400

Bad request

401

Unauthorized

get/v1/members
Response samples
application/json
{
  • "message": "Getting Requested Members",
  • "errors": "[ExceptionString]: Invalid fields",
  • "data": {
    },
  • "status": 200
}

Activate Points

Updates the status of the points from Pending to Active. When setToPending flag is true, the duration in which the points will be in Pending status must be specified between 0-24 hours. When it is 0, the endpoint must be run manually (otherwise, the points earned will remain in Pending status). When the duration is between 1-24 hours, the points stay in Pending status only for the defined period. This endpoint can be configured to run automatically to activate the points. Note: Points in the Pending status reflect in the account balance but they can be redeemed only after they reach the defined threshold value and is in Active status.

Request
Security:
Request Body schema: application/json
profileId
string or null <uuid> (Profileid)

Profile ID of the member. It is generated in the response of the Enroll Member endpoint - POST /v1/members.

startDate
string or null <date-time> (Startdate)

Start of the date range, in UTC format.

endDate
string or null <date-time> (Enddate)

End of the date range, in UTC format.

Responses
201

OK

400

Bad request

401

Unauthorized

post/v1/members/points-activate
Request samples
application/json
{
  • "profileId": "123abc-45def-67ghi-89jkl",
  • "startDate": "2020-02-08 00:00:00",
  • "endDate": "2020-02-08 00:00:00"
}
Response samples
application/json
{
  • "message": "Member points activated",
  • "errors": "[ExceptionString]: Invalid fields",
  • "data": { },
  • "status": 200
}

Adjust Points

Allows points adjustment by adding (positive adjustments) or deducting points (negative adjustments) from the member’s loyalty account.
Note:
1) The daily cap for adjustment is configurable as per the role requirements.
2) Point adjustments are recorded as a transaction, where a pre-defined code must be selected.

Request
Security:
Request Body schema: application/json
profileId
string <uuid> (Profileid)

Profile ID of the member. In an ecosystem, it acts as a primary ID to keep the various systems (apps, websites, etc.) in sync.

pointTypes
string or null (Pointtypes) non-empty

Points type.
They are categorized as:
1) Base points - Earned in any purchase transaction based on the core rule.
2) Bonus points - Earned as a bonus for example on a large purchase.
3) Promotional Points - Earned as part of promotional events.
4) Restricted Points - Points to be used only on specified stores.

billingEntity
string or null (Billingentity) non-empty

Billing entity of the adjustment transaction.

points
required
number <float> (Points)

Monetary value of the points.

reasonCode
string or null (Reasoncode) non-empty

Reason code for the point adjustment.

setToPending
boolean (Settopending)
Default: false

true: Points in Pending status.
false: Points in Active status.
Note:The time period for Pending state is configurable.

Responses
201

OK

400

Bad request

401

Unauthorized

post/v1/members/points-adjustment
Request samples
application/json
{
  • "profileId": "f90a1da5-c072-48b7-a9ea-eb35c5dd506b",
  • "pointTypes": 1,
  • "billingEntity": "Company_Club",
  • "points": 10,
  • "reasonCode": "0591",
  • "setToPending": false
}
Response samples
application/json
{
  • "message": "Member points adjusted",
  • "errors": "[ExceptionString]: Invalid fields",
  • "data": {
    },
  • "status": 200
}

Earn

Earn Points

Earns and accumulates points based on core (earn and burn) rules, promotional rules, etc. set at the club level. It is possible, for instance, to set rules that a member will earn 10 points for every $100 spent in a purchase transaction, and 10 points are equivalent to $2. The rules are customizable based on the requirement.
Points are categorized as:
1) Base points - Earned in any purchase transaction based on the core rule.
2) Bonus points - Earned as a bonus for example on a large purchase.
3) Promotional Points - Earned as part of promotional events.
4) Restricted Points - Points to be used only on specified stores.

Request
Security:
Request Body schema: application/json
profileId
string <uuid> (Profileid)

Profile ID of the member. In an ecosystem, it acts as a primary ID to keep the various systems (apps, websites, etc.) in sync.

totalAmountPaid
required
number <float> (Totalamountpaid)

Total amount paid for the items. For example, the amount paid for item1 is 100.00 and the amount of item2 is 200.00 so the total amount paid is 300.00.

entityReference
required
string (Entityreference) [ 3 .. 15 ] characters

Name or ID for the store (or entity) where the transaction took place.

transactionTypeExternalReference
required
string (Transactiontypeexternalreference) [ 3 .. 15 ] characters

External reference for the transaction type such purchase, return, or exchange (Configurable as per requirement).

activityTimestamp
required
string <date-time> (Activitytimestamp)

Activity date (in UTC format). An activity could be enrolling a member, making a transaction, etc.

transactionExternalReference
required
string (Transactionexternalreference) [ 1 .. 100 ] characters

Order ID or receipt ID for a transaction (received from the store). It is needed to cancel or return an order.

transactionGrossAmount
required
number <float> (Transactiongrossamount) >= 0

Gross transaction amount (in currency unit) of the total items earn. For example the gross amount of item1 is 50.00 and gross amount of item2 is 100.00. The transactionGrossAmount is 150.00.

checkForDuplicateTransaction
required
integer <int32> (Checkforduplicatetransaction)

0 indicates the system allows duplicates and 1 indicates there is a validation in place to identity duplicate.

fetchUpdatedMemberPointTotals
required
integer <int32> (Fetchupdatedmemberpointtotals)

1 indicates the total points are calculated and shown to the member. 0 indicates the total points are not calculated and the member is only notified the earn is successful. Note: The response is faster when the value is 0 because the total points are not calculated on the fly.

discountValue
required
integer <int32> (Discountvalue)

Discount value on the transaction, if applicable.

netAmount
required
number <float> (Netamount) >= 0

Net transaction amount based on the total items in the transaction. For example the net amount of item1 is 100.00 and net amount of item2 is 200.00. Then the net amount is 300.00.

issueAuditUser
string or null (Issueaudituser) [ 1 .. 100 ] characters

Name of the representative who issued the earn transaction.

cancelAuditUser
string or null (Cancelaudituser) [ 1 .. 100 ] characters

Name of the representative who cancelled the earn transaction.

redemptionCode
Array of strings or null

Redemption code to identify and link the rewards used in a specific transaction. This is generated in the response of the 'Issue Variable Rewards' endpoint - POST /api/v1/redeem/reward/issue.

totalTax
required
number <float> (Totaltax)

Total tax based on the number of items in the transaction. For example, the tax amount of item1 is 2.00 and tax amount of item2 is 1.00. The totalTax is 3.00.

reasonCode
string (Reasoncode) [ 1 .. 4 ] characters

Reason code to categorize transactions. A parent company can configure custom codes for their stores as required.

reasonDescription
string (Reasondescription) [ 1 .. 20 ] characters

When reason codes are not configured, store can make use of the reason description to add notes on the transaction.

Array of objects (Discount)

Represents the discounts on the item.

Array of objects (TransactionItemsSerializerEarn)

Details of the items in the transaction.

setToPending
boolean (Settopending)
Default: false

true: Points in Pending status
false: Points in Active status.
Note:The time period for Pending state is configurable.

Responses
200

OK

400

Bad request

401

Unauthorized

post/v2/earn
Request samples
application/json
{
  • "profileId": "67460e74-02e3-11e8-b443-00163e990bdb",
  • "totalAmountPaid": 1,
  • "entityReference": "Company LIBERTY CENTER",
  • "transactionTypeExternalReference": "Supplements",
  • "activityTimestamp": "2020-02-08 09:30:26",
  • "transactionExternalReference": "123321abc",
  • "transactionGrossAmount": 0,
  • "checkForDuplicateTransaction": 1,
  • "fetchUpdatedMemberPointTotals": 0,
  • "discountValue": 2,
  • "netAmount": 300,
  • "issueAuditUser": "Joe",
  • "cancelAuditUser": "John",
  • "redemptionCode": [
    ],
  • "totalTax": 3,
  • "reasonCode": "Earn",
  • "reasonDescription": "earning item",
  • "discounts": [
    ],
  • "transactionItems": [
    ],
  • "setToPending": false
}
Response samples
application/json
{
  • "status": 200,
  • "totalAmountPaid": 1,
  • "message": "earned",
  • "errors": { },
  • "data": {
    },
  • "limit": 10,
  • "offset": 2,
  • "count": 200
}

Retrieve Transactions

Retrieves transactions based on the limit (default: 20) and offset (default: 0) values. This endpoint serves to populate the transaction listing page and as a search function based on the query parameters such as date range, transaction ID, etc.

Request
Security:
query Parameters
startTimestamp
string

The start date of the selected date range, in UTC format.

Example: startTimestamp=2020-03-20T01:30:08.180856.
endTimestamp
string

The end date of the selected date range, in UTC format.

Example: endTimestamp=2020-03-20T01:30:08.180856
transactionExternalReference
integer

External reference (name or ID) of the transaction.

Example: transactionExternalReference=Company_CLUB
transactionId
integer

Transaction ID

Example: transactionId=75407
offset
integer

Indicates the starting record number (within the total number of records) in the response. When no value is provided, the default value is 0.

limit
integer

Indicates the final record number (from the offset number) in the response. When no value is provided, the default value is 20.

Responses
200

OK

400

Bad request

401

Unauthorized

get/v2/earn/get-transaction
Response samples
application/json
{
  • "profileId": "67460e74-02e3-11e8-b443-00163e990bdb",
  • "transactionId": 6789,
  • "transactionTypeExternalReference": "0591",
  • "transactionTotalTax": 15,
  • "transactionExternalReference": "proteins_supplements",
  • "transactionEntityReference": "Liberty_center",
  • "netValue": 100,
  • "grossValue": 100,
  • "eligibleRevenue": 100,
  • "itemNumber": "1123455",
  • "quantity": 4,
  • "status": "ON HOLD",
  • "basePoints": "100.0",
  • "bonusPoints": 100,
  • "promotionalPoints": 100,
  • "discounts": [
    ],
  • "transactionItems": [
    ],
  • "activityTimestamp": "2020-02-08 09:30:26",
  • "discountValue": 1,
  • "entityReference": "Company Club",
  • "issueAuditUser": "Joe",
  • "cancelAuditUser": "John"
}

Reverse Earned Points

When a member cancels a purchase transaction or returns an order, this endpoint cancels all the points earned in that transaction.

Request
Security:
Request Body schema: application/json
profileId
string <uuid> (Profileid)

The profile ID of the member. In an ecosystem, it acts as a primary ID to keep the various systems (apps, websites, etc.) in sync. The profileId is generated as part of the Enroll Member endpoint - POST /members.

totalAmountPaid
required
number <float> (Totalamountpaid)

Total amount paid for the items. For example, the amount paid for item1 is 100.00 and the amount of item2 is 200.00 so the total amount paid is 300.00.

entityReference
required
string (Entityreference) [ 3 .. 15 ] characters

A unique name or ID for the store (or entity) where the transaction took place.

transactionTypeExternalReference
required
string (Transactiontypeexternalreference) [ 3 .. 15 ] characters

The external reference for the transaction type such purchase, return, or exchange (configurable as per requirement).

activityTimestamp
required
string <date-time> (Activitytimestamp)

The activity date (in UTC format). An activity could be enrolling a member, making a transaction, etc.

transactionExternalReference
required
string (Transactionexternalreference) [ 1 .. 100 ] characters

The order ID or receipt ID for a transaction (received from the store). This is needed to cancel or return an order.

transactionGrossAmount
required
number <float> (Transactiongrossamount)

The gross amount on the transaction. For example, gross amount of item1 is 50.00 and gross amount of item2 is 100.00. The ransactionGrossAmount is 150.00

checkForDuplicateTransaction
required
integer <int32> (Checkforduplicatetransaction)

0 indicates the system allows duplicate and 1 indicates there is a validation in place to identify duplicate.

fetchUpdatedMemberPointTotals
required
integer <int32> (Fetchupdatedmemberpointtotals)

A value of 1 indicates the total points (including the points earned in the latest transaction) are calculated and displayed to the member. A value of 0 indicates the total points are not calculated and the member is only notified if the earn is successful. The response is faster when the value is 0 because there is no calculations involved.

discountValue
required
integer or null <int32> (Discountvalue)

The discount amount applied on the transaction.

netAmount
required
number <float> (Netamount)

The net transaction amount. Example - the net amount of item1 is 100.00 and net amount of item2 is 200.00. So, the netAmount is 300.00.

issueAuditUser
string or null (Issueaudituser) [ 1 .. 100 ] characters

The name of the representative who issued the earn transaction.

cancelAuditUser
string or null (Cancelaudituser) [ 1 .. 100 ] characters

The name of the representative who cancelled the earn transaction.

redemptionCode
Array of strings or null

The redemption code used to identify and link the rewards used in a specific transaction. This code is generated in the response of the 'Issue Variable Rewards' endpoint - POST /api/v1/redeem/reward/issue.

setToPending
boolean (Settopending)

true: Points in Pending status
false: Point in Active status. Note: The time period for Pending state is configurable.

totalTax
required
number <float> (Totaltax)

Final tax amount based on the number of items in the transaction. Example - the tax amount of item1 is 2.00; Tax amount of item2 is 2.00. The totalTax is 4.00.

reasonCode
string or null (Reasoncode) [ 1 .. 4 ] characters

Reason code to categorize transactions. A parent company can configure custom codes for their stores as required.

reasonDescription
string or null (Reasondescription) [ 1 .. 20 ] characters

When reason codes are not configured, store can make use of the reason description.

reverseTransactionExteranlRef
string (Reversetransactionexteranlref) [ 1 .. 100 ] characters

External reference number of the reverse transaction.

Array of objects (TransactionItemsSerializerEarnReverse)

Details of the transaction items.

isCompanyUser
boolean (Iscompanyuser)
Default: false

true: Company user is running the endpoint
false: Client user is running the endpoint.

Responses
200

OK

400

Bad request

401

Unauthorized

post/v2/earn/reverse
Request samples
application/json
{
  • "profileId": "67460e74-02e3-11e8-b443-00163e990bdb",
  • "totalAmountPaid": 1,
  • "entityReference": "Company LIBERTY CENTER",
  • "transactionTypeExternalReference": "Supplements",
  • "activityTimestamp": "2020-02-08 09:30:26",
  • "transactionExternalReference": "123321abc",
  • "transactionGrossAmount": 150,
  • "checkForDuplicateTransaction": 1,
  • "fetchUpdatedMemberPointTotals": 1,
  • "discountValue": 2,
  • "netAmount": 300,
  • "issueAuditUser": "Joe",
  • "cancelAuditUser": "John",
  • "redemptionCode": [
    ],
  • "setToPending": true,
  • "totalTax": 4,
  • "reasonCode": "Earn",
  • "reasonDescription": "earning item",
  • "reverseTransactionExteranlRef": "orderNO1",
  • "transactionItems": [
    ],
  • "isCompanyUser": false
}
Response samples
application/json
{
  • "transactionId": 1001,
  • "totalAmountPaid": 1,
  • "profileId": "67460e74-02e3-11e8-b443-00163e990bdb",
  • "transactionTypeCode": "ext",
  • "transactionNumber": "ext",
  • "transactionDateTime": "2020-03-20T14:28:23.382748",
  • "activityDate": "2020-03-20T14:28:23.382748",
  • "createDate": "2020-03-20T14:28:23.382748",
  • "updateDate": "2020-03-20T14:28:23.382748",
  • "transactionNetTotal": 100,
  • "memberPointsEarned": 10,
  • "memberPointsDeducted": 2,
  • "memberPointsUsed": 5,
  • "memberPointsExpired": 5,
  • "memberPointsAvailable": 5,
  • "memberPointsLocked": "5",
  • "totalTax": 10,
  • "reasonCode": "Earn",
  • "reasonDescription": "earning item",
  • "setToPending": true,
  • "discounts": [
    ],
  • "products": [
    ],
  • "rewards": [
    ],
  • "issueAuditUser": "Joe",
  • "cancelAuditUser": "mia"
}

Redeem

Issue Reward

Issues a reward certificate when the points in the member's account reach a threshold (configurable as per requirement).
Note - A single reward is issued at a time.
When the redemptionChoice is set 'auto,' the points are automatically converted to reward. When the redemptionChoice is 'bank,' the points are converted to reward based on the member's request.
The response of this endpoint includes a memberRewardId, which is required to redeem the reward in the future.

Request
Security:
Request Body schema: application/json
profileId
required
string <uuid> (Profileid)

Profile ID of the member. In an ecosystem, it acts as a primary ID to keep the various systems (apps, websites, etc.) in sync.

locationExternalReference
required
string (Locationexternalreference) non-empty

External reference ID (or name) of the location where the points are redeemed.

amountToRedeem
required
number <float> (Amounttoredeem)

Redeemable amount. The maximum amount to be redeemed (or the reward limit) is configurable. When a member has $100 in their loyalty account and the store has a reward limit of $50, they can use two rewards certificates to redeem the amount fully.

issueAuditUser
string (Issueaudituser) non-empty

Name of the representative who issued the audit.

tierDiscountValue
required
number <float> (Tierdiscountvalue)

Tier-based discounts can be offered by attaching members to different tiers, such as silver, gold, platinum, etc. The discount percentage or discount amounts can be customized.

Responses
200

OK

400

Bad request

401

Unauthorized

post/v1/redeem/reward/issue
Request samples
application/json
{
  • "profileId": "67460e74-02e3-11e8-b443-00163e990bdb",
  • "locationExternalReference": "Company_Club",
  • "amountToRedeem": 15,
  • "issueAuditUser": "Joe",
  • "tierDiscountValue": 3
}
Response samples
application/json
{
  • "status": 200,
  • "message": "Created",
  • "errors": null,
  • "data": {
    }
}

Redeem Rewards

Confirms the redemption and marks the reward as used. This is done based on the rewardId or redemptionCode that are generated from the response of the 'Issue Variable Rewards' - POST /api/v1/redeem/reward/issue endpoint.
Note:
1) Rewards have to be issued before they can be redeemed.
2) Rewards must be within their expiration date.

Request
Security:
Request Body schema: application/json
memberRewardId
integer <int32> (Memberrewardid)

Reward ID of the member. Either the reward ID or the redemption code must be specified.

redemptionCode
string <uuid> (Redemptioncode)

Redemption code. It links reward IDs to a transaction, for future reference. Either the member reward ID or the redemption code must be specified. The redemption code is generated in the response of the 'Issue Variable Rewards' (POST /api/v1/redeem/reward/issue) endpoint.

locationExternalReference
required
string (Locationexternalreference) non-empty

Represents the store where the rewards were redeemed. Each store (online, physical or POS) has a unique locationExternalReference name or ID.

redeemAuditUser
string (Redeemaudituser) non-empty

Name of the representative who redeemed the audit.

Responses
200

OK

400

Bad request

401

Unauthorized

post/v1/redeem/member-reward
Request samples
application/json
{
  • "memberRewardId": 455,
  • "redemptionCode": "04c229d7-03cb-421f-9d77-1c0ff1fc2641",
  • "locationExternalReference": "Company_Club",
  • "redeemAuditUser": "Joe"
}
Response samples
application/json
{
  • "status": 200,
  • "message": "Redeem Member Reward succeed.",
  • "errors": { },
  • "data": null
}

Rewards History

Gets status-wise (Active, Cancelled, Redeemed, Reversed, etc.) details of all the rewards of a member.
Note: When profileId is not specified, this endpoint retrieves all rewards for all members of a company.

Request
Security:
path Parameters
profileId
required
string

Profile ID. It is generated in the response of the Enroll Member endpoint - POST /v1/members.

query Parameters
limit
integer

The ending number of the record (from the offset number) in the response. When no value is provided, the default value is 10.

offset
integer

The starting number of the record (within the total number of records) in the response. When no value is provided, the default value is 0.

Responses
200

OK

400

Bad request

401

Unauthorized

get/v1/redeem/{profileId}
Response samples
application/json
{
  • "status": 200,
  • "message": " ",
  • "errors": { },
  • "data": [
    ]
}

Reverse Redeemed Rewards

Converts rewards back to points when the order is cancelled or returned.
Note: Once a reward has been redeemed, it cannot be cancelled. To cancel the rewards (convert back to points) before redemption, use the ‘Cancel Reward’ endpoint - POST /api/v1/redeem/cancel.

Request
Security:
Request Body schema: application/json
memberRewardId
integer <int32> (Memberrewardid)

Reward ID of the member. Either the member reward ID or the redemption code must be specified.

redemptionCode
string <uuid> (Redemptioncode)

Redemption code used to identify and link the rewards used in a specific transaction. This is generated in the response of the 'Issue Variable Rewards' endpoint - POST /api/v1/redeem/reward/issue.

Responses
200

OK

400

Bad request

401

Unauthorized

post/v1/redeem/reverse
Request samples
application/json
{
  • "memberRewardId": 455,
  • "redemptionCode": "04c229d7-03cb-421f-9d77-1c0ff1fc2641"
}
Response samples
application/json
{
  • "status": 200,
  • "message": "Reward reversed successfully.",
  • "errors": { },
  • "data": { }
}

Cancel Rewards

Loyalty points that are converted into reward certificates have an expiration date. Members can cancel their rewards if they are unable to use them before expiration or do not want to use them. The endpoint converts the rewards back into points, for future use.
Note: Once the reward is redeemed, it cannot be cancelled. If the member cancels or returns an order, the rewards are reversed back to points using the ‘Reverse Redeemed Reward’ endpoint - POST v1/redeem/reverse.

Request
Security:
Request Body schema: application/json
memberRewardId
integer <int32> (Memberrewardid)

Reward ID of the member. Either the memberRewardId or the redemptionCode must be specified. The reward ID is generated in the response of the 'Issue Variable Rewards' endpoint - POST /api/v1/redeem/rewardissue API.

redemptionCode
string <uuid> (Redemptioncode)

Redemption code. Either the memberRewardId or the redemptionCode must be specified. The redemption code used to identify and link the rewards used in a specific transaction. This code is generated in the response of the 'Issue Variable Rewards' endpoint - POST /api/v1/redeem/reward/issue.

cancelAuditUser
string (Cancelaudituser) non-empty

Name of the representative who cancelled the audit.

Responses
200

OK

400

Bad request

401

Unauthorized

post/v1/redeem/cancel
Request samples
application/json
{
  • "memberRewardId": 455,
  • "redemptionCode": "04c229d7-03cb-421f-9d77-1c0ff1fc2641",
  • "cancelAuditUser": "Joe"
}
Response samples
application/json
{
  • "status": 200,
  • "message": "Reward cancelled successfully.",
  • "errors": { },
  • "data": null
}

Discounts

Retrieve Discounts

Retrieves applicable discounts for a transaction. The discounts are categorized as
1) Transaction amount discount: Applied for the whole transaction. For example, if the transaction is for $100, the discount is applied by percentage or amount to the whole transaction amount.
2) Product discount: Applied on specific SKU so that discount percentage or amount is applied to specific product (regardless of the quantity).
3) Tier discount - Applied based on the membership tier. For example, shipping discount or flat percentage applied according to membership tier.
4) Item level discount: Applied on Product SKU.
5) Full amount discount - Applied on the total transaction amount on the transaction.

Request
Security:
Request Body schema: application/json
profileId
required
string <uuid> (Profileid)

Profile ID of the member.

entityReference
required
string (Entityreference) non-empty

External reference of the store where the transaction occurred.

transactionTimestamp
required
string <date-time> (Transactiontimestamp)

Transaction date, in UTC format.

taxAmount
required
number <float> (Taxamount)

Tax amount.

grossAmount
required
number <float> (Grossamount)

Gross amount of the transaction (after discount).

netAmount
required
number <float> (Netamount)

Net amount of the transaction (before discount).

Array of objects (TransactionItems)
Responses
200

Ok

400

Bad request

401

Unauthorized

post/v1/discounts
Request samples
application/json
{
  • "profileId": "67460e74-02e3-11e8-b443-00163e990bdb",
  • "entityReference": "Company_Club",
  • "transactionTimestamp": "2020-02-08 09:30:26",
  • "taxAmount": 3,
  • "grossAmount": 5,
  • "netAmount": 5,
  • "transactionItems": [
    ]
}
Response samples
application/json
{
  • "taxAmount": 5,
  • "netAmount": 5,
  • "grossAmount": 5,
  • "discounts": [
    ],
  • "transactionItems": [
    ],
  • "tierDiscounts": [
    ]
}

Inquire

Retrieve Member Points

Retrieves all active and pending (excluding expired) member points along with the points breakdown.

Request
Security:
path Parameters
profileId
required
string

Profile ID. It is generated in the response of the Enroll Member endpoint - POST /v1/members.

Responses
200

OK

400

Bad request

401

Unauthorized

get/v1/inquire/{profileId}/member-points
Response samples
application/json
{
  • "totalPoints": 1500,
  • "pointsbyType": [
    ],
  • "pointsBalance": {
    },
  • "breakdown": {
    }
}

Retrieve Redeemable Points

Retrieves the redeemable points of a member on a given entity.
When points in the member account reach a defined threshold value, the points are converted to rewards, which can be redeemed in the future purchases.
Note: The points to rewards conversion may be manual or automatic depending on how it is configured.

Request
Security:
query Parameters
profileId
string

Profile ID. It is generated in the response of the Enroll Member endpoint - POST /v1/members.

ehtId
integer

Entity Hierarchy Tree (EHT) ID. Either the EHT ID or the clubExternalReference must be specified along with the profileID.

externalReference
required
string

External reference number of the entity/store.

clubExternalReference
string

External reference number of the club.

Responses
200

OK

400

Bad request

401

Unauthorized

get/v1/inquire/redeemable-points
Response samples
application/json
{
  • "total_points": 1000
}

Retrieve Action Reasons

Retrieves reason codes and reason descriptions based on the actions defined for your business. This serves as a log for tracking and analysis. As an example, an action such as 'points transfer' has a specific code for it and a description such as 'transferring to relative' associated with it. In addition to the predefined actions, custom actions can be added.

Request
Security:
Responses
200

OK

400

Bad request

401

Unauthorized

get/v1/inquire/get_action_reasons
Response samples
application/json
{
  • "id": 1001,
  • "code": "5726",
  • "code_description": "Manual Tier Upgrade - VIP from EHG",
  • "action": "Tier",
  • "company_id": 15,
  • "reason": "Tier upgrade"
}

Retrieve Point Types

Retrieve all the point types configured for your business. The point types are categorized as:
1) Base points - Earned in any purchase transaction based on the core rule.
2) Bonus points - Earned as a bonus for example on a large purchase.
3) Promotional Points - Earned as part of promotional events.
4) Restricted Points - Points to be used only on specific entity/stores.
Note: You may choose only the point types that apply to your business.

Request
Security:
Responses
200

OK

400

Bad request

401

Unauthorized

get/v1/inquire/point-type-choices
Response samples
application/json
{
  • "point_type_choices": [
    ]
}

Retrieve Points to be Expired

Retrieves all points that will expire within a year starting at 30 days, 60 days, and up to one year.

Request
Security:
query Parameters
profileId
integer

Profile ID. It is generated in the response of the Enroll Member endpoint - POST /v1/members.

Responses
200

OK

400

Bad request

401

Unauthorized

get/v1/inquire/points-expiry
Response samples
application/json
{
  • "message": "Success",
  • "data": [
    ],
  • "status": 200,
  • "errors": { }
}

Retrieve Expired Points

Retrieves expired points of a member for a date range, in UTC format. When date range is not specified, all the expired points are retrieved

Request
Security:
path Parameters
profileId
required
string

ProfileId of the member, which is generated in the response of the Enroll Member endpoint - POST /v1/members.

query Parameters
startTimestamp
string

The start date of the date range, in UTC format.

Example: startTimestamp=2020-03-20T01:30:08.180856
endTimestamp
string

The end date of the date range, in UTC format.

Example: endTimestamp=2020-03-20T01:30:08.180856
Responses
200

OK

400

Bad request

401

Unauthorized

get/v1/inquire/all-points-expiry/{profileId}
Response samples
application/json
{
  • "expiryDuration": 40,
  • "unRestrictedTotalPoints": 10,
  • "totalPoints": 10,
  • "pointValue": 10,
  • "expiryDate": "2020-03-20T01:30:08.180856",
  • "restrictedTotalPoints": 10,
  • "restrictedPoints": [
    ]
}