openapi: 3.0.3
info:
  title: LoyaltyLion API
  description: >-
    The LoyaltyLion v2 REST API powers an e-commerce loyalty and rewards program.
    It is split into an Admin API - for moving data in and out of LoyaltyLion, such
    as retrieving customers and transactions, tracking orders, and adjusting points
    - and a Headless API for building custom shopper-facing loyalty experiences in
    web, mobile, and POS applications. Requests authenticate with a Program API key
    passed as a Bearer token in the Authorization header (with scoped access such as
    read_customers), or the deprecated token/secret pair over HTTP Basic auth
    (supported until 2027-01-10). Customers are addressed by the merchant_id you use
    in your own platform. All endpoints share a rate limit of 20 requests per second
    unless otherwise stated. This document grounds the core Customers, Activities,
    Points, Rewards, and Redemptions resources; some verbs are modeled from the
    documented resource index and should be verified against the live reference.
  version: '2.0'
  contact:
    name: LoyaltyLion
    url: https://developers.loyaltylion.com
servers:
  - url: https://api.loyaltylion.com/v2
    description: LoyaltyLion v2 API
security:
  - bearerAuth: []
  - basicAuth: []
tags:
  - name: Customers
    description: Loyalty customer profiles, points balances, tiers, and referrals.
  - name: Activities
    description: Customer activities recorded against loyalty rules to award points.
  - name: Points
    description: Manual point adjustments and immutable point transactions.
  - name: Rewards
    description: Rewards a customer can claim and program reward catalog controls.
  - name: Redemptions
    description: Claiming and refunding rewards on behalf of a customer.
  - name: Utility
    description: Identity and diagnostic endpoints.
paths:
  /whoami:
    get:
      operationId: whoAmI
      tags:
        - Utility
      summary: Who am I
      description: Returns the identity and scopes associated with the authenticated API key.
      responses:
        '200':
          description: The authenticated identity.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /customers:
    get:
      operationId: listCustomers
      tags:
        - Customers
      summary: List customers
      description: >-
        Lists loyalty customers. Supports cursor pagination and filtering by email
        substring and created/updated date ranges. Requires a key with the
        read_customers scope.
      parameters:
        - name: since_id
          in: query
          schema:
            type: integer
          description: Return resources with an ID greater than this value.
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 100
          description: Maximum results per request.
        - name: cursor
          in: query
          schema:
            type: string
          description: Pagination cursor from a previous response.
        - name: sort_field
          in: query
          schema:
            type: string
            enum:
              - id
              - updated_at
        - name: sort_direction
          in: query
          schema:
            type: string
            enum:
              - asc
              - desc
        - name: email
          in: query
          schema:
            type: string
          description: Filter by email substring match.
        - name: created_at_min
          in: query
          schema:
            type: string
            format: date-time
        - name: created_at_max
          in: query
          schema:
            type: string
            format: date-time
        - name: updated_at_min
          in: query
          schema:
            type: string
            format: date-time
        - name: updated_at_max
          in: query
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: A paginated list of customers.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Customer'
                  cursors:
                    $ref: '#/components/schemas/Cursors'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /customers/{merchant_id}:
    parameters:
      - $ref: '#/components/parameters/MerchantId'
    put:
      operationId: updateCustomer
      tags:
        - Customers
      summary: Update a customer
      description: >-
        Updates a loyalty customer, for example setting their date of birth or other
        profile attributes. Verify the exact verb against the live reference.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerInput'
      responses:
        '200':
          description: The updated customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Customer'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /customers/{merchant_id}/transactions:
    parameters:
      - $ref: '#/components/parameters/MerchantId'
    get:
      operationId: listCustomerTransactions
      tags:
        - Points
      summary: List a customer's point transactions
      description: Lists the immutable point transactions for a single customer.
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: A paginated list of point transactions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Transaction'
                  cursors:
                    $ref: '#/components/schemas/Cursors'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /customers/{merchant_id}/points:
    parameters:
      - $ref: '#/components/parameters/MerchantId'
    post:
      operationId: addPoints
      tags:
        - Points
      summary: Add points to a customer
      description: Manually adds points to a customer's balance with an optional shopper-visible reason.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PointsAdjustment'
      responses:
        '200':
          description: Points added.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /customers/{merchant_id}/remove_points:
    parameters:
      - $ref: '#/components/parameters/MerchantId'
    post:
      operationId: removePoints
      tags:
        - Points
      summary: Remove points from a customer
      description: Manually removes points from a customer's balance with an optional shopper-visible reason.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PointsAdjustment'
      responses:
        '200':
          description: Points removed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /customers/{merchant_id}/available_rewards:
    parameters:
      - $ref: '#/components/parameters/MerchantId'
    get:
      operationId: listAvailableRewards
      tags:
        - Rewards
      summary: List available rewards for a customer
      description: Lists the rewards a given customer can currently claim, optionally filtered by site and country.
      parameters:
        - name: site_id
          in: query
          schema:
            type: string
          description: Filter rewards by a specific site in multi-site programs.
        - name: country
          in: query
          schema:
            type: string
          description: ISO 3166-1 alpha-2 country code to filter rewards by location.
      responses:
        '200':
          description: A list of rewards the customer can claim.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Reward'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /customers/{merchant_id}/claimed_rewards:
    parameters:
      - $ref: '#/components/parameters/MerchantId'
    post:
      operationId: redeemReward
      tags:
        - Redemptions
      summary: Redeem a reward
      description: >-
        Redeems a reward on behalf of a customer, spending their points to create a
        claimed reward.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RedeemRewardInput'
      responses:
        '200':
          description: The claimed reward.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaimedReward'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /customers/{merchant_id}/claimed_rewards/{claimed_reward_id}/refund:
    parameters:
      - $ref: '#/components/parameters/MerchantId'
      - name: claimed_reward_id
        in: path
        required: true
        schema:
          type: string
        description: The ID of the claimed reward to refund.
    post:
      operationId: refundReward
      tags:
        - Redemptions
      summary: Refund a claimed reward
      description: Refunds a previously claimed reward, returning the spent points to the customer.
      responses:
        '200':
          description: The refunded claimed reward.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaimedReward'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /activities:
    get:
      operationId: listActivities
      tags:
        - Activities
      summary: List activities
      description: Lists customer activities recorded against loyalty rules.
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: A paginated list of activities.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Activity'
                  cursors:
                    $ref: '#/components/schemas/Cursors'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createActivity
      tags:
        - Activities
      summary: Create an activity
      description: >-
        Records a customer activity against a built-in or custom loyalty rule to
        award points. Clickthrough rules require a url in properties.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivityInput'
      responses:
        '200':
          description: The created activity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Activity'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
  /activities/{merchant_id}:
    parameters:
      - $ref: '#/components/parameters/MerchantId'
    put:
      operationId: updateActivity
      tags:
        - Activities
      summary: Update an activity
      description: >-
        Updates an activity previously created with a merchant_id, for example to
        void it. Verify the exact verb against the live reference.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivityUpdate'
      responses:
        '200':
          description: The updated activity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Activity'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /transactions:
    get:
      operationId: listTransactions
      tags:
        - Points
      summary: List transactions
      description: >-
        Lists point transactions across the program. Each transaction is an
        immutable addition or removal of points from a customer.
      parameters:
        - name: type
          in: query
          schema:
            type: string
            enum:
              - json
              - csv
          description: Response format.
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
        - name: since_id
          in: query
          schema:
            type: integer
        - name: customer_id
          in: query
          schema:
            type: string
          description: Filter by LoyaltyLion customer ID.
        - name: created_at_min
          in: query
          schema:
            type: string
            format: date-time
        - name: created_at_max
          in: query
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: A paginated list of point transactions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Transaction'
                  cursors:
                    $ref: '#/components/schemas/Cursors'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /rewards/{reward_id}/enable:
    parameters:
      - name: reward_id
        in: path
        required: true
        schema:
          type: string
        description: The ID of the reward in the program catalog.
    post:
      operationId: enableReward
      tags:
        - Rewards
      summary: Enable a reward
      description: >-
        Enables a reward in the program catalog so shoppers can claim it. Verb and
        path modeled from the documented resource index; verify against the live
        reference.
      responses:
        '200':
          description: The enabled reward.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reward'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /rewards/{reward_id}/disable:
    parameters:
      - name: reward_id
        in: path
        required: true
        schema:
          type: string
        description: The ID of the reward in the program catalog.
    post:
      operationId: disableReward
      tags:
        - Rewards
      summary: Disable a reward
      description: >-
        Disables a reward in the program catalog so shoppers can no longer claim it.
        Verb and path modeled from the documented resource index; verify against the
        live reference.
      responses:
        '200':
          description: The disabled reward.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reward'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Program API key passed as a Bearer token in the Authorization header.
    basicAuth:
      type: http
      scheme: basic
      description: Deprecated token (username) and secret (password) over HTTP Basic auth, supported until 2027-01-10.
  parameters:
    MerchantId:
      name: merchant_id
      in: path
      required: true
      schema:
        type: string
      description: The ID of the customer in your platform or e-commerce store.
    Limit:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 500
        default: 100
      description: Maximum results per request.
    Cursor:
      name: cursor
      in: query
      schema:
        type: string
      description: Pagination cursor from a previous response.
  responses:
    Unauthorized:
      description: Authentication failed or the API key lacks the required scope.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: The request body failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Cursors:
      type: object
      properties:
        next:
          type: string
          nullable: true
        previous:
          type: string
          nullable: true
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
    Customer:
      type: object
      properties:
        id:
          type: integer
        merchant_id:
          type: string
        email:
          type: string
          format: email
        points_approved:
          type: integer
        points_pending:
          type: integer
        points_spent:
          type: integer
        loyalty_tier_membership:
          type: object
          additionalProperties: true
        referral_url:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    CustomerInput:
      type: object
      properties:
        date_of_birth:
          type: string
          format: date
        merchant_id:
          type: string
    Transaction:
      type: object
      description: An immutable addition or removal of points from a customer.
      properties:
        id:
          type: integer
        customer_id:
          type: string
        points:
          type: integer
          description: Positive for an addition, negative for a removal.
        title:
          type: string
        reason:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
    PointsAdjustment:
      type: object
      required:
        - points
      properties:
        points:
          type: integer
          minimum: 1
          maximum: 1000000
          description: The number of points to add or remove.
        reason:
          type: string
          nullable: true
          description: A shopper-visible message shown on the customer's page in the LoyaltyLion admin.
    Activity:
      type: object
      properties:
        id:
          type: integer
        merchant_id:
          type: string
        name:
          type: string
        customer_id:
          type: string
        customer_email:
          type: string
          format: email
        state:
          type: string
        properties:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
    ActivityInput:
      type: object
      required:
        - name
        - customer_id
        - customer_email
      properties:
        name:
          type: string
          description: A built-in or custom activity rule name.
        customer_id:
          type: string
          description: A unique ID for the customer involved in the activity.
        customer_email:
          type: string
          format: email
        properties:
          type: object
          additionalProperties: true
          description: Rule-specific properties. Clickthrough rules must include a url.
        date:
          type: string
          format: date-time
          description: ISO 8601 timestamp; defaults to the current time if omitted.
        guest:
          type: boolean
          default: true
        merchant_id:
          type: string
          description: Your own identifier for the activity, used to update it later.
        ip_address:
          type: string
        user_agent:
          type: string
    ActivityUpdate:
      type: object
      properties:
        state:
          type: string
          description: The new state of the activity, for example to void it.
    Reward:
      type: object
      properties:
        id:
          type: integer
        title:
          type: string
        points_price:
          type: integer
        enabled:
          type: boolean
        kind:
          type: string
    RedeemRewardInput:
      type: object
      required:
        - reward_id
      properties:
        reward_id:
          type: integer
        multiplier:
          type: number
        variant_id:
          type: string
        shopify_action_id:
          type: string
        attribution:
          type: string
          enum:
            - redemption_notification
        session:
          type: object
          properties:
            kind:
              type: string
            token:
              type: string
    ClaimedReward:
      type: object
      properties:
        id:
          type: integer
        reward_id:
          type: integer
        customer_id:
          type: string
        points_spent:
          type: integer
        state:
          type: string
        created_at:
          type: string
          format: date-time