Award (add) and spend points on a member account, transfer points peer-to-peer between members, and cancel, activate, expire, or block a points transfer. List points transfers and read transfer histograms. This is the ledger surface for the loyalty points economy.
openapi: 3.1.0
info:
title: Open Loyalty REST API
version: '1.0'
description: >-
API-first, headless loyalty and gamification platform. This document models a
representative, grounded subset of the Open Loyalty REST API across members
(customers), transactions, points transfers, reward campaigns, levels
(tiers), and earning rules. Endpoints are scoped per store using a storeCode
path segment. Open Loyalty is delivered as managed cloud SaaS on a per-tenant
instance, so the server host below is a template - substitute your own Open
Loyalty instance host. Requests and responses are JSON over HTTPS,
authenticated with a JWT bearer token or a permanent API token.
contact:
name: Open Loyalty
url: https://www.openloyalty.io
license:
name: Open Loyalty (Open Source Edition Apache-2.0 / Enterprise SaaS)
url: https://github.com/OpenLoyalty
servers:
- url: https://{instance}.openloyalty.io/api
description: Per-tenant Open Loyalty instance (substitute your own host).
variables:
instance:
default: your-instance
description: Your Open Loyalty tenant subdomain.
externalDocs:
description: Open Loyalty REST API reference
url: https://docs.openloyalty.io/en/latest/api/
security:
- bearerAuth: []
- permanentToken: []
tags:
- name: Members
description: Loyalty members (customers).
- name: Transactions
description: Purchase transactions and points accrual.
- name: Points
description: Points transfers - the loyalty points ledger.
- name: Rewards
description: Reward campaigns, coupons, and redemption.
- name: Tiers
description: Levels (loyalty tiers).
- name: Earning Rules
description: Rules that define how members earn points.
- name: Authorization
description: Authentication and token issuance.
paths:
/admin/login_check:
post:
operationId: adminLogin
tags:
- Authorization
summary: Obtain a JWT for an admin user
security: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
username:
type: string
password:
type: string
required:
- username
- password
responses:
'200':
description: A signed JWT bearer token.
content:
application/json:
schema:
type: object
properties:
token:
type: string
/{storeCode}/customer/login_check:
post:
operationId: customerLogin
tags:
- Authorization
summary: Obtain a JWT for a member (customer)
security: []
parameters:
- $ref: '#/components/parameters/StoreCode'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
username:
type: string
password:
type: string
responses:
'200':
description: A signed JWT bearer token for the member.
/{storeCode}/customer/register:
post:
operationId: registerCustomer
tags:
- Members
summary: Register a new member
parameters:
- $ref: '#/components/parameters/StoreCode'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerRegistration'
responses:
'200':
description: Member registered.
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
/{storeCode}/customer:
get:
operationId: listCustomers
tags:
- Members
summary: List members
parameters:
- $ref: '#/components/parameters/StoreCode'
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PerPage'
responses:
'200':
description: A paginated list of members.
content:
application/json:
schema:
type: object
properties:
customers:
type: array
items:
$ref: '#/components/schemas/Customer'
total:
type: integer
/{storeCode}/customer/check:
get:
operationId: checkCustomer
tags:
- Members
summary: Check whether a member exists by email or phone
parameters:
- $ref: '#/components/parameters/StoreCode'
- name: email
in: query
schema:
type: string
- name: phone
in: query
schema:
type: string
responses:
'200':
description: Existence result.
/{storeCode}/customer/{customer}:
get:
operationId: getCustomer
tags:
- Members
summary: Get a member
parameters:
- $ref: '#/components/parameters/StoreCode'
- $ref: '#/components/parameters/CustomerId'
responses:
'200':
description: The member.
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
put:
operationId: updateCustomer
tags:
- Members
summary: Update a member
parameters:
- $ref: '#/components/parameters/StoreCode'
- $ref: '#/components/parameters/CustomerId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerRegistration'
responses:
'200':
description: Member updated.
/{storeCode}/customer/{customer}/level:
post:
operationId: assignCustomerLevel
tags:
- Members
summary: Assign a member to a level
parameters:
- $ref: '#/components/parameters/StoreCode'
- $ref: '#/components/parameters/CustomerId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
levelId:
type: string
responses:
'200':
description: Member assigned to level.
/{storeCode}/admin/customer/{customer}/history:
get:
operationId: getCustomerHistory
tags:
- Members
summary: Get a member's loyalty history
parameters:
- $ref: '#/components/parameters/StoreCode'
- $ref: '#/components/parameters/CustomerId'
responses:
'200':
description: The member's loyalty activity history.
/{storeCode}/transaction:
get:
operationId: listTransactions
tags:
- Transactions
summary: List transactions
parameters:
- $ref: '#/components/parameters/StoreCode'
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PerPage'
responses:
'200':
description: A paginated list of transactions.
post:
operationId: registerTransaction
tags:
- Transactions
summary: Register a transaction
parameters:
- $ref: '#/components/parameters/StoreCode'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Transaction'
responses:
'200':
description: Transaction registered; earning rules evaluated.
/{storeCode}/transaction/simulate:
post:
operationId: simulateTransaction
tags:
- Transactions
summary: Simulate the points a transaction would earn
parameters:
- $ref: '#/components/parameters/StoreCode'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Transaction'
responses:
'200':
description: The points obtainable if this transaction were registered.
content:
application/json:
schema:
type: object
properties:
points:
type: number
/{storeCode}/transaction/{transaction}:
get:
operationId: getTransaction
tags:
- Transactions
summary: Get a transaction
parameters:
- $ref: '#/components/parameters/StoreCode'
- name: transaction
in: path
required: true
schema:
type: string
responses:
'200':
description: The transaction.
/{storeCode}/customer/transaction/customer/assign:
post:
operationId: assignTransactionToCustomer
tags:
- Transactions
summary: Assign a transaction to a member
parameters:
- $ref: '#/components/parameters/StoreCode'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
transactionId:
type: string
customerId:
type: string
responses:
'200':
description: Transaction assigned.
/{storeCode}/points/transfer:
get:
operationId: listPointsTransfers
tags:
- Points
summary: List points transfers
parameters:
- $ref: '#/components/parameters/StoreCode'
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PerPage'
responses:
'200':
description: A paginated list of points transfers.
/{storeCode}/points/transfer/add:
post:
operationId: addPoints
tags:
- Points
summary: Add (award) points to a member
parameters:
- $ref: '#/components/parameters/StoreCode'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PointsTransfer'
responses:
'200':
description: Points awarded.
/{storeCode}/points/transfer/spend:
post:
operationId: spendPoints
tags:
- Points
summary: Spend (deduct) points from a member
parameters:
- $ref: '#/components/parameters/StoreCode'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PointsTransfer'
responses:
'200':
description: Points spent.
/{storeCode}/customer/points/p2p-transfer:
post:
operationId: p2pTransferPoints
tags:
- Points
summary: Transfer points peer-to-peer between members
parameters:
- $ref: '#/components/parameters/StoreCode'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
receiver:
type: string
points:
type: number
responses:
'200':
description: Points transferred.
/{storeCode}/points/transfer/{transfer}/cancel:
post:
operationId: cancelPointsTransfer
tags:
- Points
summary: Cancel a points transfer
parameters:
- $ref: '#/components/parameters/StoreCode'
- name: transfer
in: path
required: true
schema:
type: string
responses:
'200':
description: Points transfer cancelled.
/{storeCode}/campaign:
get:
operationId: listCampaigns
tags:
- Rewards
summary: List reward campaigns
parameters:
- $ref: '#/components/parameters/StoreCode'
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PerPage'
responses:
'200':
description: A paginated list of reward campaigns.
post:
operationId: createCampaign
tags:
- Rewards
summary: Create a reward campaign
parameters:
- $ref: '#/components/parameters/StoreCode'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Campaign'
responses:
'200':
description: Reward campaign created.
/{storeCode}/campaign/active:
get:
operationId: listActiveCampaigns
tags:
- Rewards
summary: List active reward campaigns
parameters:
- $ref: '#/components/parameters/StoreCode'
responses:
'200':
description: A collection of active reward campaigns.
/{storeCode}/campaign/{campaign}:
get:
operationId: getCampaign
tags:
- Rewards
summary: Get a reward campaign
parameters:
- $ref: '#/components/parameters/StoreCode'
- $ref: '#/components/parameters/CampaignId'
responses:
'200':
description: The reward campaign.
put:
operationId: updateCampaign
tags:
- Rewards
summary: Update a reward campaign
parameters:
- $ref: '#/components/parameters/StoreCode'
- $ref: '#/components/parameters/CampaignId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Campaign'
responses:
'200':
description: Reward campaign updated.
/{storeCode}/admin/customer/{customer}/campaign/{campaign}/buy:
post:
operationId: buyCampaignForCustomer
tags:
- Rewards
summary: Buy a reward campaign for a member
parameters:
- $ref: '#/components/parameters/StoreCode'
- $ref: '#/components/parameters/CustomerId'
- $ref: '#/components/parameters/CampaignId'
responses:
'200':
description: Reward campaign purchased for the member; points deducted.
/{storeCode}/level:
get:
operationId: listLevels
tags:
- Tiers
summary: List levels (tiers)
parameters:
- $ref: '#/components/parameters/StoreCode'
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PerPage'
responses:
'200':
description: A paginated list of levels.
/{storeCode}/level/create:
post:
operationId: createLevel
tags:
- Tiers
summary: Create a level (tier)
parameters:
- $ref: '#/components/parameters/StoreCode'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Level'
responses:
'200':
description: Level created.
/{storeCode}/level/{level}:
get:
operationId: getLevel
tags:
- Tiers
summary: Get a level (tier)
parameters:
- $ref: '#/components/parameters/StoreCode'
- $ref: '#/components/parameters/LevelId'
responses:
'200':
description: The level.
put:
operationId: updateLevel
tags:
- Tiers
summary: Update a level (tier)
parameters:
- $ref: '#/components/parameters/StoreCode'
- $ref: '#/components/parameters/LevelId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Level'
responses:
'200':
description: Level updated.
delete:
operationId: deleteLevel
tags:
- Tiers
summary: Delete a level (tier)
parameters:
- $ref: '#/components/parameters/StoreCode'
- $ref: '#/components/parameters/LevelId'
responses:
'204':
description: Level deleted.
/{storeCode}/level/{level}/customers:
get:
operationId: listLevelCustomers
tags:
- Tiers
summary: List members assigned to a level
parameters:
- $ref: '#/components/parameters/StoreCode'
- $ref: '#/components/parameters/LevelId'
responses:
'200':
description: Members currently in this level.
/{storeCode}/earningRule:
get:
operationId: listEarningRules
tags:
- Earning Rules
summary: List earning rules
parameters:
- $ref: '#/components/parameters/StoreCode'
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PerPage'
responses:
'200':
description: A paginated list of earning rules.
post:
operationId: createEarningRule
tags:
- Earning Rules
summary: Create an earning rule
parameters:
- $ref: '#/components/parameters/StoreCode'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EarningRule'
responses:
'200':
description: Earning rule created.
/{storeCode}/earningRule/{earningRule}:
get:
operationId: getEarningRule
tags:
- Earning Rules
summary: Get an earning rule
parameters:
- $ref: '#/components/parameters/StoreCode'
- name: earningRule
in: path
required: true
schema:
type: string
responses:
'200':
description: The earning rule.
put:
operationId: updateEarningRule
tags:
- Earning Rules
summary: Update an earning rule
parameters:
- $ref: '#/components/parameters/StoreCode'
- name: earningRule
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/EarningRule'
responses:
'200':
description: Earning rule updated.
/{storeCode}/earningRule/{earningRule}/activate:
post:
operationId: activateEarningRule
tags:
- Earning Rules
summary: Activate or deactivate an earning rule
parameters:
- $ref: '#/components/parameters/StoreCode'
- name: earningRule
in: path
required: true
schema:
type: string
responses:
'200':
description: Earning rule activation state changed.
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
JWT obtained from POST /admin/login_check (admin) or
POST /{storeCode}/customer/login_check (member), sent as
Authorization: Bearer <token>.
permanentToken:
type: apiKey
in: header
name: X-AUTH-TOKEN
description: Permanent API token issued to an admin account.
parameters:
StoreCode:
name: storeCode
in: path
required: true
description: The store the request is scoped to.
schema:
type: string
default: DEFAULT
CustomerId:
name: customer
in: path
required: true
description: Member (customer) identifier.
schema:
type: string
CampaignId:
name: campaign
in: path
required: true
description: Reward campaign identifier.
schema:
type: string
LevelId:
name: level
in: path
required: true
description: Level (tier) identifier.
schema:
type: string
Page:
name: page
in: query
schema:
type: integer
default: 1
PerPage:
name: perPage
in: query
schema:
type: integer
default: 10
schemas:
Customer:
type: object
properties:
customerId:
type: string
firstName:
type: string
lastName:
type: string
email:
type: string
phone:
type: string
levelId:
type: string
loyaltyCardNumber:
type: string
active:
type: boolean
CustomerRegistration:
type: object
properties:
firstName:
type: string
lastName:
type: string
email:
type: string
phone:
type: string
birthDate:
type: string
format: date
agreement1:
type: boolean
required:
- firstName
- lastName
Transaction:
type: object
properties:
transactionData:
type: object
properties:
documentNumber:
type: string
documentType:
type: string
purchaseDate:
type: string
format: date-time
customerData:
type: object
properties:
email:
type: string
phone:
type: string
items:
type: array
items:
type: object
properties:
sku:
type: object
properties:
code:
type: string
name:
type: string
quantity:
type: integer
grossValue:
type: number
PointsTransfer:
type: object
properties:
customer:
type: string
points:
type: number
comment:
type: string
validityDuration:
type: integer
required:
- customer
- points
Campaign:
type: object
properties:
name:
type: string
reward:
type: string
costInPoints:
type: integer
active:
type: boolean
levels:
type: array
items:
type: string
limit:
type: integer
Level:
type: object
properties:
name:
type: string
description:
type: string
conditionValue:
type: number
active:
type: boolean
reward:
type: object
properties:
name:
type: string
value:
type: number
EarningRule:
type: object
properties:
name:
type: string
type:
type: string
description: Rule type - points, event, multiply_points, qrcode, geolocation, etc.
pointsAmount:
type: number
active:
type: boolean
startAt:
type: string
format: date-time
endAt:
type: string
format: date-time