Open Loyalty

Open Loyalty Customer API

Register, list, read, and update loyalty members (customers), check existence by email or phone, manage activation and status, assign members to levels and POS, and read per-member history. Members are the core loyalty account that points, transactions, and campaigns attach to.

GitHub OpenAPI

Documentation

📖
APIReference
https://docs.openloyalty.io/en/latest/api/customer.html
📖
Documentation
https://docs.openloyalty.io/en/latest/api/introduction.html

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/open-loyalty/refs/heads/main/openapi/open-loyalty-openapi.yml

Other Resources

🔗
PostmanCollection
https://raw.githubusercontent.com/api-evangelist/open-loyalty/refs/heads/main/collections/open-loyalty.postman_collection.json
🔗
OpenCollection
https://raw.githubusercontent.com/api-evangelist/open-loyalty/refs/heads/main/collections/open-loyalty.opencollection.json
🔗
APIsJSON
https://raw.githubusercontent.com/api-evangelist/open-loyalty/refs/heads/main/apis.yml

OpenAPI Specification

open-loyalty-openapi.yml Raw ↑ 
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