We have a brand new Developer Portal!

This page will be expiring soon; be sure to bookmark the new link.
Take me there

Loyalty (Member) (1.0.0)

Download OpenAPI specification:Download

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

fabric Loyalty formerly 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.

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.

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

First name of member

middleName
string (Middlename) <= 100 characters

Middle name of member

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

Last name of member

suffix
string or null (Suffix)

Suffix of the member name, if any.

gender
string (Gender)

Gender of member

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

Date of birth of member

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

Email address of the member

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

Phone number of member (without space or dash).

addressLine1
string or null (Addressline1) <= 500 characters

Line 1 of address

addressLine2
string or null (Addressline2) <= 500 characters

Line 2 of 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 address

postalCode
string (Postalcode)

Zip code of address

country
string (Country) non-empty

Country name

nationality
string (Nationality)

Nationality of member

maritalStatus
string (Maritalstatus)

Marital status of member

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

Prefix (if appliable) of 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 redeem reward.

entityReference
required
string (Entityreference) non-empty

Name or ID of 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) <= 30 characters

Reason code for enrollment

enrollReasonNote
string or null (Enrollreasonnote) <= 300 characters

Enrollment reason

tierReference
string or null (Tierreference)

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: 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

Company website used for member enrollmen

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": "Duke",
  • "lastName": "Wayne",
  • "suffix": "string",
  • "gender": "Male",
  • "birthDate": "1990-11-16",
  • "emailAddress": "user@abc.com",
  • "phoneNumber": "923331234567",
  • "addressLine1": "10400 NE 4th St",
  • "addressLine2": "Suite 505",
  • "addressLine3": "",
  • "city": "Austin",
  • "region": "Texas",
  • "postalCode": "98004",
  • "country": "United States",
  • "nationality": "",
  • "maritalStatus": "Single",
  • "prefix": "Mr",
  • "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": "Created",
  • "errors": { },
  • "data": {
    },
  • "status": 201
}

Update Member

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

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

Profile ID of the member to update

firstName
string (Firstname) [ 1 .. 100 ] characters

First name of member

middleName
string (Middlename)

Middle name of member

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

Last name of member

suffix
string (Suffix)

Suffix member

gender
string (Gender)

Gender of member

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

Date of birth of member

emailAddress
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 address

addressLine2
string or null (Addressline2) <= 500 characters

Line 2 of address

addressLine3
string or null (Addressline3) <= 500 characters

An additional line for directional information

city
string (City) <= 50 characters

City name of address

region
string (Region) <= 150 characters

State name of address

postalCode
string (Postalcode)

Zip code of address

country
string (Country) non-empty

Country name of 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

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

Store name (physical entire/store or a website) where member was 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

tierReference
string (Tierreference)

Reference-name of the tier to assign member to

tierExpirationDatetime
string <date-time> (Tierexpirationdatetime)

Tier expiration date-time. Only utilized if tierReference is specified

customAttributes
object (customAttributes)

A dictionary representing the custom fields.

Responses
200

Member updated

400

Bad request

401

Unauthorized

put/v1/members
Request samples
application/json
{
  • "profileId": "f90a1da5-c072-48b7-a9ea-eb35c5dd506b",
  • "firstName": "John",
  • "middleName": "M",
  • "lastName": "Williams",
  • "suffix": "string",
  • "gender": "Male",
  • "birthDate": "1980-11-30",
  • "emailAddress": "user@abc.com",
  • "phoneNumber": "923331234567",
  • "addressLine1": "10400 NE 4th St",
  • "addressLine2": "Suite 505",
  • "addressLine3": "null",
  • "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",
  • "tierReference": "GOLD",
  • "tierExpirationDatetime": "2026-01-15T23:59:59.000Z",
  • "customAttributes": {
    }
}
Response samples
application/json
{
  • "message": "Member updated",
  • "errors": {
    },
  • "data": {
    },
  • "status": 200
}

Get Members

Gets the details of all members of a parent company. Results can be 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) Query parameter used to get results must be part of member information.

SecuritybearerAuth
Request
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 member

Example: firstName=Sam
middleName
string

Middle name of member

Example: middleName=M
lastName
string

Last name of member

Example: lastName=Demo
phonenumber
string

Phone number given for enrollment (without space or dash)

Example: phonenumber=923331234567
email
string

Email address given for enrollment

Example: email=user@abc.com
address
string

Address of member

postalCode
string

Postal code of address

Example: postalCode=98004
city
string

City name

Example: city=Bellevue
countryName
string

Country name

Example: countryName=United State
countryAbbreviation
string

Abbreviation of country name

Example: countryAbbreviation=US
regionName
string

State name

Example: regionName=Washington
regionAbbreviation
string

Abbreviation of state name

Example: regionAbbreviation=WA
offset
integer

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

limit
integer

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

Responses
200

OK

400

Bad request

401

Unauthorized

get/v1/members
Response samples
application/json
{
  • "message": "Result of requested Members",
  • "errors": { },
  • "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.

SecuritybearerAuth
Request
Request Body schema: application/json
profileId
required
string <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)

Beginning of the date range, in UTC format

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

Ending of the date range, in UTC format

Responses
200

OK

400

Bad request

401

Unauthorized

post/v1/members/points-activate
Request samples
application/json
{
  • "profileId": "f90a1da5-c072-48b7-a9ea-eb35c5dd506b",
  • "startDate": "2020-02-08 00:00:00",
  • "endDate": "2020-02-08 00:00:00"
}
Response samples
application/json
{
  • "message": "Member points activated",
  • "errors": { },
  • "data": null,
  • "status": 200
}

Adjust Points

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

SecuritybearerAuth
Request
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.

pointType
string or null (Pointtype) 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 for the adjustment transaction

points
required
number <integer> (Points)

Number of points to adjust. Can be positive or negative.

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
200

OK

400

Bad request

401

Unauthorized

post/v1/members/points-adjustment
Request samples
application/json
{
  • "profileId": "f90a1da5-c072-48b7-a9ea-eb35c5dd506b",
  • "pointType": "Base",
  • "billingEntity": "Company_Club",
  • "points": 100,
  • "reasonCode": "7502",
  • "setToPending": false
}
Response samples
application/json
{
  • "message": "Member points adjusted",
  • "errors": { },
  • "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. 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.

Earn endpoint uses the following formula for validating Payload:
1) Amount Paid = Gross Amount - Discounts
2) Net Amount = Gross Amount - Taxes - Discounts
3) At the Transaction Item level: Item Price - (Discount/Quantity) = Net Amount / Quantity
4) Total of all Transaction Items' Gross Amount = Total Gross Amount

SecuritybearerAuth
Request
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.

entityReference
required
string (Entityreference) [ 1 .. 100 ] characters

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

transactionTypeExternalReference
required
string (Transactiontypeexternalreference) [ 1 .. 100 ] characters

External reference for the transaction type such as 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.

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.

discountValue
required
integer <int32> (Discountvalue)

Discount value on the transaction, if applicable

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.

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

Net transaction amount based on the total items in the transaction, after subtracting taxes and discounts.

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

Representative who issued the earn transaction

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

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.

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

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

reasonDescription
string (Reasondescription) [ 1 .. 300 ] 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",
  • "entityReference": "Company LIBERTY CENTER",
  • "transactionTypeExternalReference": "Supplements",
  • "activityTimestamp": "2020-02-08 09:30:26",
  • "transactionExternalReference": "123321abc",
  • "transactionGrossAmount": 200,
  • "checkForDuplicateTransaction": 1,
  • "fetchUpdatedMemberPointTotals": 0,
  • "totalAmountPaid": 180,
  • "discountValue": 20,
  • "totalTax": 20,
  • "netAmount": 160,
  • "issueAuditUser": "Joe",
  • "cancelAuditUser": "John",
  • "redemptionCode": [
    ],
  • "reasonCode": "9393",
  • "reasonDescription": "earning item",
  • "discounts": [
    ],
  • "transactionItems": [
    ],
  • "setToPending": false
}
Response samples
application/json
{
  • "status": 201,
  • "message": "earned",
  • "errors": { },
  • "data": {
    }
}

Get Transactions

Gets 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.

SecuritybearerAuth
Request
query Parameters
profileId
string

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

Example: profileId=67460e74-02e3-11e8-b443-00163e990bd2
startTimestampUTC
string <date-time>

Start date of the selected date range (UTC format)

Example: startTimestampUTC=2020-03-20T01:30:08.180856
endTimestampUTC
string <date-time>

End date of the selected date range (UTC format)

Example: endTimestampUTC=2020-03-20T01:30:08.180856
transactionExternalReference
string

External reference (name or ID) of the transaction like POS Order Id or Ecommerce Order Id.

Example: transactionExternalReference=2883-7273-61186
transactionType
string

Refers to the different type of transaction activities on a member account such as Earn Transaction, Burn Transaction, Earn Reverse Transaction and so on

Enum: "EARN" "BURN" "EXPIRY" "EARN_REVERSE" "BURN_REVERSE" "ADJUSTMENT" "DEDUCT" "TRANSFER" "MERGE" "FORFEITED" "CONVERT" "UNMERGE"
Example: transactionType=EARN
transactionCode
string <uuid>

Transaction Code

Example: transactionCode=62660e74-02e3-11e8-b443-00163e990abc
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
{
  • "status": 200,
  • "message": "",
  • "errors": { },
  • "data": [
    ]
}

Reverse Earned Points

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

SecuritybearerAuth
Request
Request Body schema: application/json
profileId
required
string <uuid>

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

entityReference
required
string [ 3 .. 15 ] characters

Unique name or ID of store (or entity) where the transaction took place.

reverseTransactionExternalRef
required
string [ 1 .. 100 ] characters

External reference number of the transaction to be reversed

transactionTypeExternalReference
required
string [ 3 .. 15 ] characters

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

activityTimestamp
required
string <date-time>

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

transactionExternalReference
required
string [ 1 .. 100 ] characters

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

checkForDuplicateTransaction
required
integer <int32>

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

fetchUpdatedMemberPointTotals
required
integer <int32>

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.

transactionGrossAmount
required
number <float>

Transaction gross amount. For example, gross amount of item1 is 50.00 and gross amount of item2 is 100.00, then transactionGrossAmount is 150.00

discountValue
required
number or null <float>

Discount amount applied on the transaction.

totalAmountPaid
required
number <float>

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.

totalTax
required
number <float>

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.

netAmount
required
number <float>

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.

Array of objects (DiscountData)

Discount details.

issueAuditUser
string or null [ 1 .. 100 ] characters

Representative who issued the earn transaction.

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

Representative who cancelled the earn transaction.

redemptionCode
Array of strings or null

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: Points in Active status. Note: The time period for Pending state is configurable.

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.

Array of objects (TransactionItemsSerializerEarnReverse)

Details of the transaction items to be reversed.

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",
  • "entityReference": "LIBERTY_STORE",
  • "reverseTransactionExternalRef": "LOYALTY-12345",
  • "transactionTypeExternalReference": "RETURN",
  • "activityTimestamp": "2020-02-08 09:30:26",
  • "transactionExternalReference": "LOYALTY-8675",
  • "checkForDuplicateTransaction": 1,
  • "fetchUpdatedMemberPointTotals": 1,
  • "transactionGrossAmount": -100,
  • "discountValue": -20,
  • "totalAmountPaid": -80,
  • "totalTax": -10,
  • "netAmount": -70,
  • "discounts": [
    ],
  • "issueAuditUser": "Joe",
  • "cancelAuditUser": "Mia",
  • "redemptionCode": [ ],
  • "setToPending": true,
  • "reasonCode": "9393",
  • "reasonDescription": "returning item",
  • "transactionItems": [
    ],
  • "isCompanyUser": false
}
Response samples
application/json
{
  • "status": 201,
  • "message": "earn reversed",
  • "errors": { },
  • "data": {
    }
}

Redeem

Issue Reward

Issues a reward certificate based on the member's request or when the points in the member's account reach a configurable threshold.
Note - A single reward is issued at a time.
When the redemptionChoice is set to 'auto', the points are automatically converted to rewards. When the redemptionChoice is 'bank,' the points are converted based on the member's request.
Response of this endpoint includes a redemptionCode, which is required to redeem the reward in the future.

SecuritybearerAuth
Request
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 being redeemed.

amountToRedeem
required
number <float> (Amounttoredeem)

Dollar amount being redeemed. Maximum amount which can 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 is issuing the reward.

tierDiscountValue
required
number <float> (Tierdiscountvalue)

Tier-based discounts can be offered by attaching members to different tiers, such as silver, gold, platinum, etc. 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": 50,
  • "issueAuditUser": "Joe",
  • "tierDiscountValue": 0
}
Response samples
application/json
{
  • "status": 201,
  • "message": "Created",
  • "errors": { },
  • "data": {
    }
}

Redeem Rewards

Confirms the redemption and marks the reward as used. This is done based on the redemptionCode that is 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.

SecuritybearerAuth
Request
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.

redemptionCode
required
string <uuid> (Redemptioncode)

Redemption code. This code must be specified. 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 are being redeemed. Each store (online, physical or POS) has a unique locationExternalReference name or ID.

redeemAuditUser
string (Redeemaudituser) non-empty

Representative who is issuing the reward redemption.

Responses
200

OK

400

Bad request

401

Unauthorized

post/v1/redeem/member-reward
Request samples
application/json
{
  • "profileId": "67460e74-02e3-11e8-b443-00163e990bdb",
  • "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 the profileId query-param is not specified, this endpoint gets all rewards for all members of a company.

SecuritybearerAuth
Request
query Parameters
profileId
required
string

Member's unique profileId, generated in the response of the Enroll Member endpoint - POST /v1/members.

limit
integer

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

offset
integer

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

SecuritybearerAuth
Request
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.

redemptionCode
required
string <uuid> (Redemptioncode)

Redemption code used to identify 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
{
  • "profileId": "67460e74-02e3-11e8-b443-00163e990bdb",
  • "redemptionCode": "04c229d7-03cb-421f-9d77-1c0ff1fc2641"
}
Response samples
application/json
{
  • "status": 200,
  • "message": "Reward reversed successfully.",
  • "errors": { },
  • "data": null
}

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.

SecuritybearerAuth
Request
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.

redemptionCode
required
string <uuid> (Redemptioncode)

Redemption code. This code must be specified. It is 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

Representative who cancelled the audit.

Responses
200

OK

400

Bad request

401

Unauthorized

post/v1/redeem/cancel
Request samples
application/json
{
  • "profileId": "67460e74-02e3-11e8-b443-00163e990bdb",
  • "redemptionCode": "04c229d7-03cb-421f-9d77-1c0ff1fc2641",
  • "cancelAuditUser": "Joe"
}
Response samples
application/json
{
  • "status": 200,
  • "message": "Reward cancelled successfully.",
  • "errors": { },
  • "data": null
}

Discounts

Get Discounts

Gets applicable discounts for a transaction. The discounts are categorized as
1) Transaction-level discounts: Applied on the whole transaction. For example, if the transaction is for $100, the discount is applied by percentage or amount to the whole transaction amount. This category includes tier-specific discounts.
2) Item-level discounts: Applied on specific SKU so that discount percentage or amount is applied to specific product (regardless of the quantity).
3) Miscellaneous discounts - This category captures all other types of discounts.

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

Profile ID of member

entityReference
required
string (Entityreference) non-empty

External reference of the store where the transaction occurred

transactionTimestamp
required
string <date-time> (Transactiontimestamp)

Transaction timestamp (UTC format)

taxAmount
required
number <float> (Taxamount)

Tax amount

grossAmount
required
number <float> (Grossamount)

Gross amount of the transaction (before discount)

netAmount
required
number <float> (Netamount)

Net amount of the transaction (after discount).

Array of objects (DiscountRequestTransactionItems)
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": 1,
  • "grossAmount": 6,
  • "netAmount": 5,
  • "transactionItems": [
    ]
}
Response samples
application/json
{
  • "status": 200,
  • "message": "Created",
  • "errors": { },
  • "data": [
    ]
}

Inquire

Get Member Points

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

SecuritybearerAuth
Request
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
{
  • "status": 200,
  • "message": "",
  • "errors": { },
  • "data": [
    ]
}

Get Redeemable Points

Gets 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.

SecuritybearerAuth
Request
query Parameters
profileId
required
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
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
{
  • "status": 200,
  • "message": "Success",
  • "errors": { },
  • "data": [
    ]
}

Get Action Reasons

Gets 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.

SecuritybearerAuth
Responses
200

OK

400

Bad request

401

Unauthorized

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

Get Point Types

Gets 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.

SecuritybearerAuth
Responses
200

OK

400

Bad request

401

Unauthorized

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

Get Points to be Expired

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

SecuritybearerAuth
Request
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": { }
}

Get Expired Points

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

SecuritybearerAuth
Request
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
startTimestampUTC
string

Start date of the date range, in UTC format.

Example: startTimestampUTC=2020-03-20T01:30:08.180856
endTimestampUTC
string

End date of the date range, in UTC format.

Example: endTimestampUTC=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
{
  • "status": 200,
  • "message": "Success",
  • "errors": { },
  • "data": [
    ]
}