> ## Documentation Index
> Fetch the complete documentation index at: https://developer.fabric.inc/llms.txt
> Use this file to discover all available pages before exploring further.
# 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`
## OpenAPI
````yaml member post /v2/earn
openapi: 3.0.1
info:
title: Loyalty (Member)
description: >-
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.
version: 1.0.0
contact:
email: support@fabric.inc
license:
name: fabric Inc
url: https://fabric.inc
servers:
- url: https://vanilla-dev02-loyalty.fabric.zone/api
description: For developers to work outside of the production environment.
- url: https://vanilla-stg-loyalty.fabric.zone/api
description: Replica of the production environment for testing.
- url: https://loyalty-sbx.fabric.zone/api
description: >-
An isolated testing environment (UAT) to run programs without affecting
the application, system or platform on which they run.
- url: https://loyalty.fabric.zone/api
description: Production environment.
security:
- bearerAuth: []
paths:
/v2/earn:
post:
tags:
- Earn
summary: Earn Points
description: >-
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`
operationId: earn_create
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Earn'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/EarnResponse'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponseClass1'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/GenericResponseClass2'
components:
schemas:
Earn:
required:
- ProfileId
- activityTimestamp
- checkForDuplicateTransaction
- discountValue
- entityReference
- fetchUpdatedMemberPointTotals
- netAmount
- totalTax
- transactionExternalReference
- transactionGrossAmount
- transactionTypeExternalReference
- totalAmountPaid
type: object
description: Details required to earn points
properties:
profileId:
title: Profileid
type: string
description: >-
Profile ID of the member. In an ecosystem, it acts as a primary ID
to keep the various systems (apps, websites, etc.) in sync.
example: 67460e74-02e3-11e8-b443-00163e990bdb
format: uuid
entityReference:
title: Entityreference
maxLength: 100
minLength: 1
type: string
description: >-
Name or ID for the store (or entity) where the transaction took
place.
example: Company LIBERTY CENTER
transactionTypeExternalReference:
title: Transactiontypeexternalreference
maxLength: 100
minLength: 1
type: string
description: >-
External reference for the transaction type such as purchase,
return, or exchange (Configurable as per requirement).
example: Supplements
activityTimestamp:
title: Activitytimestamp
type: string
description: >-
Activity date (in UTC format). An activity could be enrolling a
member, making a transaction, etc.
example: '2020-02-08 09:30:26'
format: date-time
transactionExternalReference:
title: Transactionexternalreference
maxLength: 100
minLength: 1
type: string
description: >-
Order ID or receipt ID for a transaction (received from the store).
It is needed to cancel or return an order.
example: 123321abc
transactionGrossAmount:
title: Transactiongrossamount
minimum: 0
description: >-
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.
example: 200
type: number
format: float
checkForDuplicateTransaction:
title: Checkforduplicatetransaction
type: integer
description: >-
0 indicates the system allows duplicates and 1 indicates there is a
validation in place to identity duplicate.
example: 1
format: int32
fetchUpdatedMemberPointTotals:
title: Fetchupdatedmemberpointtotals
type: integer
description: >-
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.
example: 0
format: int32
totalAmountPaid:
title: Totalamountpaid
description: >-
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.
example: 180
type: number
format: float
discountValue:
title: Discountvalue
type: integer
description: Discount value on the transaction, if applicable
example: 20
format: int32
totalTax:
title: Totaltax
type: number
format: float
description: >-
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.
example: 20
netAmount:
title: Netamount
minimum: 0
description: >-
Net transaction amount based on the total items in the transaction,
after subtracting taxes and discounts.
example: 160
type: number
format: float
issueAuditUser:
title: Issueaudituser
maxLength: 200
minLength: 1
type: string
description: Representative who issued the earn transaction
example: Joe
nullable: true
cancelAuditUser:
title: Cancelaudituser
maxLength: 200
minLength: 1
type: string
description: Representative who cancelled the earn transaction
nullable: true
example: John
redemptionCode:
description: >-
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.
example:
- 67460e74-02e3-11e8-b443-00163e990bdb
type: array
items:
type: string
nullable: true
reasonCode:
title: Reasoncode
maxLength: 30
minLength: 1
type: string
description: >-
Reason code to categorize transactions. A parent company can
configure custom codes for their stores as required.
example: '9393'
reasonDescription:
title: Reasondescription
maxLength: 300
minLength: 1
type: string
description: >-
When reason codes are not configured, store can make use of the
reason description to add notes on the transaction.
example: earning item
discounts:
type: array
description: Represents the discounts on the item.
items:
$ref: '#/components/schemas/Discount'
transactionItems:
type: array
description: Details of the items in the transaction.
items:
$ref: '#/components/schemas/TransactionItemsSerializerEarn'
setToPending:
title: Settopending
type: boolean
description: >-
true: Points in Pending status
false: Points in Active
status.
**Note**:The time period for Pending state is
configurable.
default: false
EarnResponse:
type: object
description: Metadata for the `Earn points` response
properties:
status:
title: Status
type: integer
description: Status code of call
example: 201
format: int32
message:
title: Message
minLength: 1
type: string
description: Message corresponding to status code.
example: earned
default: Exception message
errors:
title: Errors
type: object
description: In a successful response, this is always a blank object.
properties: {}
data:
$ref: '#/components/schemas/EarnApiResponse'
description: Earn details
GenericResponseClass1:
type: object
description: Bad request
properties:
message:
title: Message
minLength: 1
type: string
description: Message corresponding to the call.
example: Error message string
errors:
title: Errors
type: object
properties: {}
description: A dictionary of lists with different number of errors or exceptions.
example:
ExceptionString:
- Invalid Field
data:
title: Data
type: object
properties: {}
description: Returns data in the form of a list of dictionaries or null
example: null
status:
title: Status
type: integer
description: Status code of the call
example: 400
format: int32
GenericResponseClass2:
type: object
description: Unauthorized
properties:
detail:
title: Detail
type: string
description: Message corresponding to the response
example: Authentication Failed
Discount:
required:
- value
type: object
properties:
type:
title: Type
minLength: 1
type: string
description: Discount type
example: promotion
description:
title: Description
minLength: 1
type: string
description: Description of the discount.
example: Black Friday discount
value:
title: Value
type: number
format: float
description: Monetary value of the discount.
example: 20
id:
title: Id
type: integer
description: Discount ID
example: 23
format: int32
TransactionItemsSerializerEarn:
required:
- SKU
- grossAmount
- itemPrice
- itemQuantity
- lineNumber
- netAmount
- taxAmount
- totalAmountPaid
type: object
description: Transaction details
properties:
grossAmount:
title: Grossamount
type: number
format: float
description: Gross amount of the item, before discount application
example: 200
totalAmountPaid:
title: Totalamountpaid
type: number
format: float
description: Amount paid for the item, including tax
example: 200
taxAmount:
title: Taxamount
type: number
format: float
description: Tax on the item
example: 20
netAmount:
title: Netamount
description: >-
Total amount of the item without tax, and after item-discount
application
example: 180
type: number
format: float
itemName:
title: Itemname
minLength: 1
type: string
description: Item name
example: demo item
itemPrice:
title: Itemprice
type: integer
description: Item price
example: 90
format: int32
itemQuantity:
title: Itemquantity
type: integer
description: Item quantity
example: 2
format: int32
SKU:
title: Sku
maxLength: 100
minLength: 1
type: string
description: Stock Keeping Unit (SKU), a unique identifier of the item.
example: '1123455'
UOM:
title: Uom
minLength: 1
type: string
description: Unit of Measurement (UOM)
example: unit
lineNumber:
title: Linenumber
type: integer
description: Line number of the item in the purchase order (PO)
example: 0
format: int32
discounts:
type: array
description: Discounts detail of the item
items:
$ref: '#/components/schemas/earn-discount'
couponCodes:
type: array
items:
minLength: 1
type: string
description: Coupon Codes
example: H4B-1000
EarnApiResponse:
required:
- profileId
- transactionNumber
- transactionType
type: object
description: Details of points earned
properties:
transactionCode:
title: Transactioncode
type: string
description: Transaction Code, which uniquely identifies each transaction
example: 78660e74-02e3-11e8-b443-00163e911bd2
format: uuid
profileId:
title: Profileid
type: string
description: >-
Profile ID of the member. In an ecosystem, it acts as a primary ID
to keep the various systems (apps, websites, etc.) in sync.
example: 67460e74-02e3-11e8-b443-00163e990bdb
format: uuid
transactionNumber:
title: Transactionnumber
minLength: 1
type: string
description: >-
Transaction number. It is same as the transactionExternalReference
and indicates a unique order ID or receipt ID.
example: LOYALTY-54321
transactionDateTime:
title: Transactiondatetime
type: string
description: Transaction time (UTC format)
example: '2020-03-20T14:28:23.382748'
format: date
activityTimestamp:
title: ActivityTimestamp
type: string
description: Activty time (UTC format)
example: '2020-03-20T14:28:23.382748'
format: date
totalAmountPaid:
title: Totalamountpaid
type: number
description: >-
Total amount paid for 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.
example: 180
format: float
totalTax:
title: Totaltax
type: integer
description: Total tax applied on earning items
example: 20
format: int32
transactionNetAmount:
title: Transactionnetamount
description: Net total amount of the transaction
example: 160
type: number
format: float
points:
title: points
type: number
format: integer
description: Points earned by the member
example: 16
basePoints:
title: Basepoints
type: number
format: integer
description: Base points earned in this transaction
example: 16
bonusPoints:
title: Bonuspoints
type: number
format: integer
description: Bonus points earned in this transaction
example: 0
promotionalPoints:
title: Promotionalpoints
type: number
format: integer
description: Promotional points earned in this transaction
example: 0
currentPointsBalance:
title: currentPointsBalance
type: number
format: integer
description: Total points currently available in the member's account.
example: 26
reasonCode:
title: Reasoncode
minLength: 1
type: string
description: >-
Reason code used to categorize transactions. A parent company can
configure custom codes for their stores as required.
example: '9393'
nullable: true
reasonDescription:
title: Reasondescription
minLength: 1
type: string
description: >-
When reason codes are not configured, store can make use of the
reason description to add notes on the transaction.
example: earning item
discounts:
type: array
description: Represents the discount details.
items:
$ref: '#/components/schemas/DiscountData'
discountValue:
title: Discountvalue
type: number
format: float
description: Discount amount on the specified transaction.
example: 20
transactionItems:
type: array
description: Details of transaction items
items:
$ref: '#/components/schemas/TransactionItemsSerializerEarn'
rewards:
type: array
description: Represents the variable rewards details
items:
$ref: '#/components/schemas/Reward'
issueAuditUser:
title: Issueaudituser
minLength: 1
type: string
description: Representative who issued the earn transaction.
example: Joe
nullable: true
cancelAuditUser:
title: Cancelaudituser
minLength: 1
type: string
description: Representative who cancelled the earn transaction.
example: John
nullable: true
deviceId:
title: Deviceid
type: string
description: Device ID used to capture the transaction
example: D10626
transactionType:
title: Transactiontype
type: string
description: >-
Refers to the different types of transaction activities on a member
account such as `Earn Transaction`, `Burn Transaction`, `Earn
Reverse Transaction` and so on
example: EARN
enum:
- EARN
- BURN
- EXPIRY
- EARN_REVERSE
- BURN_REVERSE
- ADJUSTMENT
- DEDUCT
- TRANSFER
- MERGE
- FORFEITED
- CONVERT
- UNMERGE
transactionActivityType:
title: Transactionactivitytype
type: string
description: Configurable alias for the `transactionType`
example: BASE_POINTS_EARNED
transactionTypeExternalReference:
title: Transactiontypeexternalreference
minLength: 1
type: string
description: >-
External reference for transaction type such as `purchase`,
`return`, or `exchange`. Supports any value as configured by store.
example: PURCHASE
transactionExternalReference:
title: Transactionexternalreference
minLength: 1
type: string
description: >-
Order ID or receipt ID for a transaction (received from the store).
This is unique and needed to cancel or return an order.
example: SHOP-7654321
transactionEntityReference:
title: Transactionentityreference
minLength: 1
type: string
description: Transaction entity reference
example: Liberty_center_store
earn-discount:
required:
- id
- value
type: object
description: Discount details
properties:
type:
title: type
maxLength: 50
minLength: 1
type: string
description: Type of discount (configurable)
example: promotion
description:
title: Description
type: string
description: Description of the discount
example: Black Friday discount
id:
title: Id
type: integer
description: Discount ID
example: 2345
format: int32
value:
title: Value
type: integer
description: Discount amount
example: 0
format: int32
DiscountData:
required:
- id
- value
type: object
description: Discount details
properties:
type:
title: Type
minLength: 1
type: string
description: Discount type (configurable).
example: promotion
description:
title: Description
type: string
description: Description of the discount.
example: Black Friday discount
id:
title: Id
type: integer
description: Discount ID
example: 2345
format: int32
value:
title: Value
type: number
format: float
description: Discount amount
example: 20
Reward:
type: object
description: Reward details
properties:
reward_id:
title: Reward ID
type: integer
description: >-
Variable reward IDs (also referred to as reward certificate).
**Note**:Multiple rewards can be used a transaction.
example: 111
format: int32
core_rule_id:
title: Core rule ID
type: integer
description: ID of the core rule based on which the rewards are generated.
example: 2
format: int32
reward_portion:
title: Reward portion
type: number
format: float
description: Total reward amount.
example: 10
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
````