openapi: 3.2.0
info:
  title: Notification schemas Loyalty notifications API
  version: ''
  description: 'Use [Application notifications](/docs/product/applications/application-notifications/overview)

    and [loyalty notifications](/docs/product/loyalty-programs/loyalty-notifications/overview)

    to notify the system of your choice of certain changes that happened in Talon.One.


    > [!note] **Note:**

    > - Required fields are not omitted if they are empty (have `null` value).

    > - The notification schemas may be extended with additional properties in future releases.

    > To maintain forward compatibility, ensure your implementation ignores unknown properties.

    '
servers:
- url: https://yourbaseurl.talon.one
security: []
tags:
- name: Loyalty notifications
  description: 'Represents the [notifications](/docs/product/loyalty-programs/loyalty-notifications/overview)

    about changes to loyalty points in profile-based loyalty programs.

    '
paths: {}
webhooks:
  expiringPointsNotification:
    post:
      operationId: expiringPointsNotification
      summary: Expiring points
      tags:
      - Loyalty notifications
      parameters:
      - $ref: '#/components/parameters/x-uuid'
      requestBody:
        description: The [notification](/docs/product/loyalty-programs/loyalty-notifications/overview) reminding users that their active loyalty points will expire soon.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExpiringPointsNotification'
            example:
              TotalResultSize: 1
              Data:
              - ExpiryDate: '2019-08-24'
                LoyaltyProgramID: 5
                CustomerProfileID: URNGV8294NV
                AmountOfExpiringPoints: 10.99
                SubledgerID: sub-123
              NotificationType: LoyaltyPointsExpiring
        required: true
  addedDeductedPointsNotification:
    post:
      operationId: addedDeductedPointsNotification
      summary: Added or deducted points
      tags:
      - Loyalty notifications
      parameters:
      - $ref: '#/components/parameters/x-uuid'
      requestBody:
        description: The [notification](/docs/product/loyalty-programs/loyalty-notifications/overview) informing users when loyalty points are added or deducted.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddedDeductedPointsNotification'
            example:
              ProfileIntegrationID: URNGV8294NV
              LoyaltyProgramID: 5
              SubledgerID: sub-123
              Amount: 10.99
              Reason: Compensation
              TypeOfChange: campaign_manager
              EmployeeName: Franziska Schneider
              UserID: 25
              Operation: addition
              StartDate: '2023-01-24T14:15:22Z'
              ExpiryDate: '2024-01-24T14:15:22Z'
              SessionIntegrationID: cc53e4fa-547f-4f5e-8333-76e05c381f67
              NotificationType: LoyaltyPointsDeducted
              TransactionUUID: 1a6a7599-2622-4489-9034-5a62da3944e0
        required: true
  addedDeductedPointsBalancesNotification:
    post:
      operationId: addedDeductedPointsBalancesNotification
      summary: Added or deducted points with current balance
      tags:
      - Loyalty notifications
      parameters:
      - $ref: '#/components/parameters/x-uuid'
      requestBody:
        description: The [notification](/docs/product/loyalty-programs/loyalty-notifications/overview) informing users when loyalty points are added or deducted, including the current balance of points.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddedDeductedPointsBalancesNotification'
            example:
              ProfileIntegrationID: URNGV8294NV
              LoyaltyProgramID: 5
              SubledgerID: sub-123
              TypeOfChange: campaign_manager
              EmployeeName: Franziska Schneider
              UserID: 25
              SessionIntegrationID: cc53e4fa-547f-4f5e-8333-76e05c381f67
              NotificationType: LoyaltyAddedDeductedPointsBalances
              CurrentPoints: 10.99
              Actions:
              - Amount: 10.99
                Reason: Compensation
                Operation: addition
                StartDate: '2023-01-24T14:15:22Z'
                ExpiryDate: '2024-01-24T14:15:22Z'
                TransactionUUID: 1a6a7599-2622-4489-9034-5a62da3944e0
        required: true
  pendingActivePointsNotification:
    post:
      operationId: pendingActivePointsNotification
      summary: Pending points
      tags:
      - Loyalty notifications
      parameters:
      - $ref: '#/components/parameters/x-uuid'
      requestBody:
        description: The [notification](/docs/product/loyalty-programs/loyalty-notifications/overview) informing users that their pending points will become active soon.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PendingActivePointsNotification'
            example:
              TotalResultSize: 1
              Data:
              - LoyaltyProgramID: 5
                SubledgerID: SL001
                CustomerProfileID: URNGV8294NV
                Points: 10.99
                ActiveOn: '2023-08-20T12:22:00+02:00'
                ExpireOn: '2023-09-01T12:23:00+02:00'
                SessionIntegrationID: cc53e4fa-547f-4f5e-8333-76e05c381f67
              NotificationType: LoyaltyPointsPendingToActive
        required: true
  tierUpgradeNotification:
    post:
      operationId: tierUpgradeNotification
      summary: Tier upgrade
      tags:
      - Loyalty notifications
      parameters:
      - $ref: '#/components/parameters/x-uuid'
      requestBody:
        description: The [notification](/docs/product/loyalty-programs/loyalty-notifications/overview) informing users when a loyalty tier upgrade occurs.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TierUpgradeNotification'
            example:
              TotalResultSize: 1
              Data:
              - CustomerProfileID: URNGV8294NV
                LoyaltyProgramID: 5
                SubledgerID: SL001
                CurrentTier: Silver
                CurrentPoints: 120.55
                OldTier: Bronze
                PointsRequiredToTheNextTier: 23.51
                NextTier: Gold
                TierExpirationDate: '2023-12-01T12:23:00+02:00'
                TimestampOfTierChange: '2023-10-26T12:23:00+02:00'
              NotificationType: TierUpgrade
        required: true
  tierDowngradeNotification:
    post:
      operationId: tierDowngradeNotification
      summary: Tier downgrade
      tags:
      - Loyalty notifications
      parameters:
      - $ref: '#/components/parameters/x-uuid'
      requestBody:
        description: The [notification](/docs/product/loyalty-programs/loyalty-notifications/overview) informing users when a loyalty tier downgrade occurs.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TierDowngradeNotification'
            example:
              TotalResultSize: 1
              Data:
              - CustomerProfileID: URNGV8294NV
                LoyaltyProgramID: 5
                SubledgerID: SL001
                CurrentTier: Silver
                CurrentPoints: 120.55
                OldTier: Gold
                TierExpirationDate: '2023-12-01T12:23:00+02:00'
                TimestampOfTierChange: '2023-10-26T12:23:00+02:00'
              NotificationType: TierDowngrade
        required: true
  tierWillDowngradeNotification:
    post:
      operationId: tierWillDowngradeNotification
      summary: Upcoming tier downgrade
      tags:
      - Loyalty notifications
      parameters:
      - $ref: '#/components/parameters/x-uuid'
      requestBody:
        description: The [notification](/docs/product/loyalty-programs/loyalty-notifications/overview) reminding users of an upcoming loyalty tier downgrade.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TierWillDowngradeNotification'
            example:
              TotalResultSize: 1
              Data:
              - CustomerProfileID: URNGV8294NV
                LoyaltyProgramID: 5
                SubledgerID: SL001
                CurrentTier: Silver
                CurrentPoints: 120.55
                PointsRequiredToRemain: 23.51
                NextTier: Bronze
                TierExpirationDate: '2023-12-01T12:23:00+02:00'
              NotificationType: TierWillDowngrade
        required: true
components:
  schemas:
    ExpiringPointsData:
      type: object
      properties:
        ExpiryDate:
          type: string
          format: date
          description: The expiration date of loyalty points.
        LoyaltyProgramID:
          type: integer
          description: The ID of the loyalty program.
          minimum: 1
          example: 5
        CustomerProfileID:
          type: string
          description: The integration ID of the customer profile that has expiring points.
          example: URNGV8294NV
        AmountOfExpiringPoints:
          type: number
          description: The amount of loyalty points that will be expired soon.
          example: 10.99
        SubledgerID:
          type: string
          description: The ID of the subledger within the loyalty program where these points were added.
          example: sub-123
    PendingActivePointsNotification:
      type: object
      properties:
        TotalResultSize:
          type: integer
          example: 1
        Data:
          type: array
          description: The array of pending points.
          maxLength: 1000
          items:
            $ref: '#/components/schemas/PendingActivePointsData'
        NotificationType:
          type: string
          description: The type of notification.
          enum:
          - LoyaltyPointsPendingToActive
    AddedDeductedPointsBalancesAction:
      type: object
      properties:
        Amount:
          type: number
          description: The amount of added or deducted loyalty points.
          example: 10.99
        Reason:
          type: string
          description: The reason for the points addition or deduction.
          example: Compensation
        Operation:
          type: string
          description: The action (addition or subtraction) made with loyalty points.
          enum:
          - addition
          - subtraction
        StartDate:
          type: string
          format: date-time
          description: The start date for loyalty points.
          example: '2023-01-24T14:15:22Z'
        ExpiryDate:
          type: string
          format: date-time
          description: The expiration date for loyalty points.
          example: '2024-01-24T14:15:22Z'
        TransactionUUID:
          type: string
          format: uuid
          description: The identifier of the transaction in the loyalty ledger.
    AddedDeductedPointsBalancesNotification:
      type: object
      properties:
        EmployeeName:
          type: string
          description: The name of the employee who added or deducted points.
          example: Franziska Schneider
        LoyaltyProgramID:
          type: integer
          description: The ID of the loyalty program.
          minimum: 1
          example: 5
        NotificationType:
          type: string
          description: The type of notification.
          enum:
          - LoyaltyAddedDeductedPointsBalances
        ProfileIntegrationID:
          type: string
          description: The integration ID of the customer profile to whom points were added or deducted.
          example: URNGV8294NV
        SessionIntegrationID:
          type: string
          description: The integration ID of the session through which the points were earned or lost.
          example: cc53e4fa-547f-4f5e-8333-76e05c381f67
        SubledgerID:
          type: string
          description: The ID of the subledger within the loyalty program where these points were added.
          example: sub-123
        TypeOfChange:
          type: string
          enum:
          - campaign_manager
          - rule_engine
          - management_api
          description: 'The notification source, that is, it indicates whether the points were added or deducted via one of the following routes:

            - [The Campaign Manager](/docs/product/getting-started)

            - [Management API](/management-api#tag/Loyalty)

            - [Rule Engine](/docs/product/applications/evaluation-order-for-rules-and-filters)

            '
        UserID:
          type: integer
          description: The ID of the employee who added or deducted points.
          example: 25
        Actions:
          type: array
          description: The list of actions that have been triggered in the loyalty program.
          minItems: 1
          items:
            $ref: '#/components/schemas/AddedDeductedPointsBalancesAction'
        CurrentPoints:
          type: number
          description: The current points balance.
          example: 10.99
    AddedDeductedPointsNotification:
      type: object
      properties:
        EmployeeName:
          type: string
          description: The name of the employee who added or deducted points.
          example: Franziska Schneider
        LoyaltyProgramID:
          type: integer
          description: The ID of the loyalty program.
          minimum: 1
          example: 5
        NotificationType:
          type: string
          description: The type of notification.
          enum:
          - LoyaltyPointsDeducted
          - LoyaltyPointsAdded
        ProfileIntegrationID:
          type: string
          description: The integration ID of the customer profile to whom points were added or deducted.
          example: URNGV8294NV
        SessionIntegrationID:
          type: string
          description: The integration ID of the session through which the points were earned or lost.
          example: cc53e4fa-547f-4f5e-8333-76e05c381f67
        SubledgerID:
          type: string
          description: The ID of the subledger within the loyalty program where these points were added.
          example: sub-123
        TypeOfChange:
          type: string
          enum:
          - campaign_manager
          - rule_engine
          - management_api
          description: 'The notification source, that is, it indicates

            whether the points were added or deducted via one of the following routes:


            - [The Campaign Manager](/docs/product/getting-started)


            - [Management API](/management-api#tag/Loyalty)


            - [Rule Engine](/docs/product/applications/evaluation-order-for-rules-and-filters)

            '
        UserID:
          type: integer
          description: The ID of the employee who added or deducted points.
          example: 25
        Amount:
          type: number
          description: The amount of added or deducted loyalty points.
          example: 10.99
        ExpiryDate:
          type: string
          format: date-time
          description: The expiration date for loyalty points.
          example: '2024-01-24T14:15:22Z'
        Operation:
          type: string
          description: The action (addition or subtraction) made with loyalty points.
          enum:
          - addition
          - subtraction
        Reason:
          type: string
          description: The reason for the points addition or deduction.
          example: Compensation
        StartDate:
          type: string
          format: date-time
          description: The start date for loyalty points.
          example: '2023-01-24T14:15:22Z'
        TransactionUUID:
          type: string
          format: uuid
          description: The identifier of the transaction in the loyalty ledger.
    TierDowngradeNotification:
      type: object
      properties:
        TotalResultSize:
          type: integer
          example: 1
        Data:
          type: array
          description: The array of tier downgrade notifications.
          maxLength: 1000
          items:
            $ref: '#/components/schemas/TierDowngradeData'
        NotificationType:
          type: string
          description: The type of notification.
          enum:
          - TierDowngrade
    TierUpgradeNotification:
      type: object
      properties:
        TotalResultSize:
          type: integer
          example: 1
        Data:
          type: array
          description: The array of tier upgrade notifications.
          maxLength: 1000
          items:
            $ref: '#/components/schemas/TierUpgradeData'
        NotificationType:
          type: string
          description: The type of notification.
          enum:
          - TierUpgrade
    ExpiringPointsNotification:
      type: object
      properties:
        TotalResultSize:
          type: integer
          example: 1
        Data:
          type: array
          description: The array of expiring points.
          maxLength: 1000
          items:
            $ref: '#/components/schemas/ExpiringPointsData'
        NotificationType:
          type: string
          description: The type of notification.
          enum:
          - LoyaltyPointsExpiring
    TierUpgradeData:
      type: object
      properties:
        CustomerProfileID:
          type: string
          description: The integration ID of the customer profile whose tier was upgraded.
          example: URNGV8294NV
        LoyaltyProgramID:
          type: integer
          description: The ID of the loyalty program.
          minimum: 1
          example: 5
        SubledgerID:
          type: string
          description: The ID of the subledger, when applicable. If this field is empty, the main ledger is used.
          default: ''
          example: SL001
        CurrentTier:
          type: string
          description: The name of the customer's current tier.
          example: Silver
        CurrentPoints:
          type: number
          description: The number of points the customer had at the time of tier upgrade.
          example: 120.55
        OldTier:
          type: string
          description: The name of the customer's previous tier.
          example: Bronze
        PointsRequiredToTheNextTier:
          type: number
          description: The number of points needed for a customer to reach the next tier.
          example: 23.51
        NextTier:
          type: string
          description: The name of the customer's next tier.
          example: Gold
        TierExpirationDate:
          type: string
          format: date-time
          description: The exact date and time the tier expires.
          example: '2023-12-01T12:23:00+02:00'
        TimestampOfTierChange:
          type: string
          format: date-time
          description: The exact date and time the tier was changed.
          example: '2023-10-26T12:23:00+02:00'
    PendingActivePointsData:
      type: object
      properties:
        LoyaltyProgramID:
          type: integer
          description: The ID of the loyalty program.
          minimum: 1
          example: 5
        SubledgerID:
          type: string
          description: The ID of the subledger, when applicable. If this field is empty, the main ledger is used.
          default: ''
          example: SL001
        CustomerProfileID:
          type: string
          description: The integration ID of the customer profile whose loyalty points are becoming active.
          example: URNGV8294NV
        Points:
          type: number
          description: The amount of pending loyalty points becoming active.
          example: 10.99
        ActiveOn:
          type: string
          format: date-time
          description: The date and time the loyalty points become active.
          example: '2023-08-20T12:22:00+02:00'
        ExpireOn:
          type: string
          format: date-time
          description: The date and time the loyalty points expire.
          example: '2023-09-01T12:23:00+02:00'
        SessionIntegrationID:
          type: string
          description: The integration ID of the session through which the points were earned.
          example: cc53e4fa-547f-4f5e-8333-76e05c381f67
    TierWillDowngradeData:
      type: object
      properties:
        CustomerProfileID:
          type: string
          description: The integration ID of the customer profile whose tier was downgraded.
          example: URNGV8294NV
        LoyaltyProgramID:
          type: integer
          description: The ID of the loyalty program.
          minimum: 1
          example: 5
        SubledgerID:
          type: string
          description: The ID of the subledger, when applicable. If this field is empty, the main ledger is used.
          default: ''
          example: SL001
        CurrentTier:
          type: string
          description: The name of the customer's current tier.
          example: Silver
        CurrentPoints:
          type: number
          description: The number of points the customer will have after the tier downgrade.
          example: 120.55
        PointsRequiredToRemain:
          type: number
          description: The number of points needed for a customer to remain on the same tier.
          example: 23.51
        NextTier:
          type: string
          description: The name of the customer's next tier.
          example: Bronze
        TierExpirationDate:
          type: string
          format: date-time
          description: The date and time the tier expires.
          example: '2023-12-01T12:23:00+02:00'
    TierDowngradeData:
      type: object
      properties:
        CustomerProfileID:
          type: string
          description: The integration ID of the customer profile whose tier was downgraded.
          example: URNGV8294NV
        LoyaltyProgramID:
          type: integer
          description: The ID of the loyalty program.
          minimum: 1
          example: 5
        SubledgerID:
          type: string
          description: The ID of the subledger, when applicable. If this field is empty, the main ledger is used.
          default: ''
          example: SL001
        CurrentTier:
          type: string
          description: The name of the customer's current tier.
          example: Silver
        CurrentPoints:
          type: number
          description: The number of points the customer had at the time of tier downgrade.
          example: 120.55
        OldTier:
          type: string
          description: The name of the customer's previous tier.
          example: Gold
        TierExpirationDate:
          type: string
          format: date-time
          description: The exact date and time the tier expires.
          example: '2023-12-01T12:23:00+02:00'
        TimestampOfTierChange:
          type: string
          format: date-time
          description: The exact date and time the tier was changed.
          example: '2023-10-26T12:23:00+02:00'
    TierWillDowngradeNotification:
      type: object
      properties:
        TotalResultSize:
          type: integer
          example: 1
        Data:
          type: array
          description: The array of upcoming tier downgrade notifications.
          maxLength: 1000
          items:
            $ref: '#/components/schemas/TierWillDowngradeData'
        NotificationType:
          type: string
          description: The type of notification.
          enum:
          - TierWillDowngrade
  parameters:
    x-uuid:
      name: X-UUID
      in: header
      description: The unique message ID. You can use it, for example, to deduplicate messages.
      schema:
        type: string
      example: 9aa05ee1-876f-42e6-9a5d-fc0bd424d9cb