openapi: 3.0.3
info:
  title: Zinrelo Loyalty API
  description: >-
    The Zinrelo Loyalty API is a REST API for building and operating loyalty and
    rewards programs across web, mobile, in-store, and other sales channels. It
    lets you enroll and manage members, award and deduct points, record
    purchases and returns, list rewards, and redeem points for rewards. Every
    request is authenticated with a partner-id and an api-key sent as HTTP
    headers, both provisioned to your Zinrelo account. This document models
    Zinrelo's publicly documented endpoints. The v1 surface is documented in the
    Zinrelo API reference (slate) and the v2 loyalty and loyalty-storefront
    surfaces are documented in the Zinrelo help center. Request and response
    bodies are modeled from the public documentation and examples; verify exact
    field names and shapes against the live reference before production use.
  version: '1.0'
  contact:
    name: Zinrelo
    url: https://www.zinrelo.com
servers:
  - url: https://api.zinrelo.com
    description: Zinrelo production API
security:
  - partnerId: []
    apiKey: []
tags:
  - name: Members
    description: Enroll, retrieve, update, block, and manage loyalty program members.
  - name: Points
    description: Award, deduct, and manage member point balances.
  - name: Transactions
    description: Record purchases and returns and list loyalty transactions.
  - name: Rewards
    description: List and retrieve the rewards a program offers.
  - name: Redemptions
    description: Redeem points for rewards and list a member's redemptions.
  - name: Tiers
    description: Retrieve loyalty tier configuration and a member's next tier.
  - name: Events
    description: Retrieve webhook event details by event ID.
paths:
  /v1/loyalty/users:
    get:
      operationId: listMembers
      tags:
        - Members
      summary: List members
      description: Retrieves all enrolled loyalty program members.
      parameters:
        - name: start_cursor
          in: query
          schema:
            type: integer
            default: 0
          description: Pagination cursor position.
        - name: count
          in: query
          schema:
            type: integer
            default: 100
          description: Number of members to return.
      responses:
        '200':
          description: A list of members.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createMember
      tags:
        - Members
      summary: Create a member
      description: Enrolls a new participant in the loyalty program.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MemberCreate'
      responses:
        '200':
          description: The created member.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Member'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/loyalty/users/{user_email}:
    get:
      operationId: getMember
      tags:
        - Members
      summary: Get a member
      description: Fetches a specific member's details and point balances.
      parameters:
        - $ref: '#/components/parameters/UserEmail'
      responses:
        '200':
          description: The member.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Member'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/loyalty/users/{user_email}/transactions:
    get:
      operationId: listMemberTransactions
      tags:
        - Members
        - Transactions
      summary: List a member's transactions
      description: Returns the historical loyalty transactions for a specific member.
      parameters:
        - $ref: '#/components/parameters/UserEmail'
      responses:
        '200':
          description: A list of the member's transactions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/loyalty/users/{user_email}/eligible_activities:
    get:
      operationId: listMemberEligibleActivities
      tags:
        - Members
      summary: List a member's eligible activities
      description: Lists the loyalty activities available to a specific member.
      parameters:
        - $ref: '#/components/parameters/UserEmail'
      responses:
        '200':
          description: A list of eligible activities.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/loyalty/users/{user_email}/redemptions:
    get:
      operationId: listMemberRedemptions
      tags:
        - Members
        - Redemptions
      summary: List a member's redemptions
      description: Retrieves the redemption options and redemptions available to a member.
      parameters:
        - $ref: '#/components/parameters/UserEmail'
      responses:
        '200':
          description: A list of the member's redemptions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedemptionList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/loyalty/users/{user_email}/next_tier:
    get:
      operationId: getMemberNextTier
      tags:
        - Members
        - Tiers
      summary: Get a member's next tier
      description: Returns the member's upcoming tier status and progress.
      parameters:
        - $ref: '#/components/parameters/UserEmail'
      responses:
        '200':
          description: The member's next tier status.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/loyalty/users/{user_email}/block:
    put:
      operationId: blockMember
      tags:
        - Members
      summary: Block a member
      description: Restricts a member from participating in the loyalty program.
      parameters:
        - $ref: '#/components/parameters/UserEmail'
      responses:
        '200':
          description: The member was blocked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/loyalty/update_user_email:
    post:
      operationId: updateMemberEmail
      tags:
        - Members
      summary: Update a member's email
      description: Modifies the email address associated with a member.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                old_email:
                  type: string
                new_email:
                  type: string
      responses:
        '200':
          description: The member email was updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/loyalty/unsubscribe_email:
    post:
      operationId: unsubscribeMember
      tags:
        - Members
      summary: Unsubscribe a member
      description: Opts a member out of loyalty program communications.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user_email:
                  type: string
      responses:
        '200':
          description: The member was unsubscribed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/loyalty/unsubscribed_users:
    get:
      operationId: listUnsubscribedMembers
      tags:
        - Members
      summary: List unsubscribed members
      description: Lists members who have opted out of communications.
      responses:
        '200':
          description: A list of unsubscribed members.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/loyalty/award:
    post:
      operationId: awardPoints
      tags:
        - Points
      summary: Award points
      description: >-
        Grants points to a member for a completed activity. Based on the
        activity configuration in the Zinrelo admin console, the appropriate
        number of points is awarded.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AwardRequest'
      responses:
        '200':
          description: The award transaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/loyalty/users/deduct:
    post:
      operationId: deductPoints
      tags:
        - Points
      summary: Deduct points
      description: Removes points from a member's account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeductRequest'
      responses:
        '200':
          description: The deduction transaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/loyalty/purchase:
    post:
      operationId: recordPurchase
      tags:
        - Transactions
        - Points
      summary: Record a purchase
      description: >-
        Awards points for a purchase and stores the associated order and
        product data with the transaction.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseRequest'
      responses:
        '200':
          description: The purchase transaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/loyalty/transaction/return:
    post:
      operationId: recordReturn
      tags:
        - Transactions
      summary: Record a return
      description: Deducts points that were awarded when an order is later returned.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user_email:
                  type: string
                order_id:
                  type: string
      responses:
        '200':
          description: The return transaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/loyalty/transactions:
    get:
      operationId: listTransactions
      tags:
        - Transactions
      summary: List transactions
      description: Fetches all loyalty program transactions within a date range.
      parameters:
        - name: start_cursor
          in: query
          schema:
            type: integer
            default: 0
        - name: count
          in: query
          schema:
            type: integer
            default: 100
        - name: status
          in: query
          schema:
            type: string
            enum:
              - Approved
              - Rejected
              - Pending
      responses:
        '200':
          description: A list of transactions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/loyalty-storefront/transactions:
    get:
      operationId: listStorefrontTransactions
      tags:
        - Transactions
        - Members
      summary: List member transactions (storefront)
      description: >-
        Returns a list of the authenticated member's transactions, identified by
        the access token and partner id. Supports pagination and date, status,
        and points-status filters.
      parameters:
        - name: start_cursor
          in: query
          schema:
            type: integer
            default: 0
        - name: count
          in: query
          schema:
            type: integer
            default: 100
        - name: status
          in: query
          schema:
            type: string
            enum:
              - Approved
              - Rejected
              - Pending
        - name: language
          in: query
          schema:
            type: string
            default: english
      responses:
        '200':
          description: A list of the member's transactions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v2/loyalty/rewards:
    get:
      operationId: listRewards
      tags:
        - Rewards
      summary: List all rewards
      description: >-
        Returns a list of all rewards. By default rewards are sorted by
        last_modified_date with the most recently modified rewards first.
      parameters:
        - name: language
          in: query
          schema:
            type: string
          description: Store language for reward content.
        - name: sort_by
          in: query
          schema:
            type: string
          description: >-
            Sort order such as rank, -rank, or points_to_be_redeemed.
      responses:
        '200':
          description: A list of rewards.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RewardList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/loyalty/redemptions:
    get:
      operationId: listRedemptions
      tags:
        - Redemptions
      summary: List redemption options
      description: Retrieves the redemption option details configured for the program.
      responses:
        '200':
          description: A list of redemption options.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedemptionList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/loyalty/redeem:
    post:
      operationId: redeemPoints
      tags:
        - Redemptions
      summary: Redeem points for a reward
      description: Exchanges a member's points for a reward.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RedeemRequest'
      responses:
        '200':
          description: The redemption transaction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Redemption'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/loyalty/tiers:
    get:
      operationId: listTiers
      tags:
        - Tiers
      summary: List tiers
      description: Lists all loyalty tier configurations for the program.
      responses:
        '200':
          description: A list of tiers.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/events/{id}:
    get:
      operationId: getEvent
      tags:
        - Events
      summary: Get a webhook event
      description: Retrieves webhook event details by event ID.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The event.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    partnerId:
      type: apiKey
      in: header
      name: partner-id
      description: Your Zinrelo Partner ID, provisioned to your account.
    apiKey:
      type: apiKey
      in: header
      name: api-key
      description: Your Zinrelo API key, provisioned to your account.
  parameters:
    UserEmail:
      name: user_email
      in: path
      required: true
      description: The member's email address, used as the member identifier.
      schema:
        type: string
  responses:
    Unauthorized:
      description: Authentication failed - missing or invalid partner-id or api-key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Member:
      type: object
      properties:
        user_email:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        available_points:
          type: integer
        redeemed_points:
          type: integer
        expired_points:
          type: integer
        tier_name:
          type: string
        member_since:
          type: string
    MemberCreate:
      type: object
      required:
        - user_email
      properties:
        user_email:
          type: string
        first_name:
          type: string
        last_name:
          type: string
    MemberList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Member'
        total_count:
          type: integer
    Transaction:
      type: object
      properties:
        transaction_id:
          type: string
        user_email:
          type: string
        activity_id:
          type: string
        points:
          type: integer
        status:
          type: string
          enum:
            - Approved
            - Rejected
            - Pending
        created_date:
          type: string
        approved_date:
          type: string
    TransactionList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Transaction'
        total_count:
          type: integer
    AwardRequest:
      type: object
      required:
        - user_email
        - activity_id
      properties:
        user_email:
          type: string
        activity_id:
          type: string
        additional_data:
          type: object
    DeductRequest:
      type: object
      required:
        - user_email
        - points
      properties:
        user_email:
          type: string
        points:
          type: integer
        reason:
          type: string
    PurchaseRequest:
      type: object
      required:
        - user_email
      properties:
        user_email:
          type: string
        order_id:
          type: string
        order_total:
          type: number
        products:
          type: array
          items:
            type: object
    RedeemRequest:
      type: object
      required:
        - user_email
        - reward_id
      properties:
        user_email:
          type: string
        reward_id:
          type: string
    Reward:
      type: object
      properties:
        reward_id:
          type: string
        name:
          type: string
        description:
          type: string
        points_to_be_redeemed:
          type: integer
        rank:
          type: integer
        last_modified_date:
          type: string
    RewardList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Reward'
        total_count:
          type: integer
    Redemption:
      type: object
      properties:
        redemption_id:
          type: string
        user_email:
          type: string
        reward_id:
          type: string
        points_redeemed:
          type: integer
        status:
          type: string
    RedemptionList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Redemption'
        total_count:
          type: integer
    StatusResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
    Error:
      type: object
      properties:
        success:
          type: boolean
        error_code:
          type: string
        message:
          type: string