openapi: 3.2.0
info:
  title: Notification schemas Loyalty card 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 card notifications
  description: Represents the [notifications](/docs/product/loyalty-programs/loyalty-notifications/overview) about changes to loyalty points in card-based loyalty programs.
paths: {}
webhooks:
  expiringCardPointsNotification:
    post:
      operationId: expiringCardPointsNotification
      summary: Expiring card points
      tags:
      - Loyalty card 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/ExpiringCardPointsNotification'
            example:
              TotalResultSize: 1
              Data:
              - ExpiryDate: '2019-08-24'
                LoyaltyProgramID: 5
                AmountOfExpiringPoints: 10.99
                SubledgerID: sub-123
                CardIdentifier: summer-loyalty-card-0543
                UsersPerCardLimit: 5
                Profiles:
                - URNGV8294NV
              NotificationType: LoyaltyCardPointsExpiring
        required: true
  cardAddedDeductedPointsNotification:
    post:
      operationId: cardAddedDeductedPointsNotification
      summary: Added or deducted card points
      tags:
      - Loyalty card 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/CardAddedDeductedPointsNotification'
            example:
              ProfileIntegrationIDs:
              - yJSObdNNtOetCHWHPFuz
              - test-user-4zoj1c
              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: LoyaltyCardPointsDeducted
              CardIdentifier: 123-456-789ATBC
              UsersPerCardLimit: 10
              TransactionUUID: 1a6a7599-2622-4489-9034-5a62da3944e0
        required: true
  cardAddedDeductedPointsBalancesNotification:
    post:
      operationId: cardAddedDeductedPointsBalancesNotification
      summary: Added or deducted card points with current balance
      tags:
      - Loyalty card 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 from a card, including the current balance of points.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CardAddedDeductedPointsBalancesNotification'
            example:
              LoyaltyProgramID: 5
              SubledgerID: sub-123
              CardIdentifier: 123-456-789ATBC
              UsersPerCardLimit: 10
              ProfileIntegrationIDs:
              - yJSObdNNtOetCHWHPFuz
              - test-user-4zoj1c
              TypeOfChange: campaign_manager
              EmployeeName: Franziska Schneider
              UserID: 25
              SessionIntegrationID: cc53e4fa-547f-4f5e-8333-76e05c381f67
              NotificationType: LoyaltyCardAddedDeductedPointsBalances
              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
components:
  schemas:
    CardAddedDeductedPointsNotification:
      type: object
      properties:
        CardIdentifier:
          type: string
          description: Loyalty card identification number.
          example: 123-456-789ATBC
        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:
          - LoyaltyCardPointsDeducted
          - LoyaltyCardPointsAdded
        ProfileIntegrationIDs:
          type: array
          description: The integration ID of the customer profile to whom points were added or deducted.
          items:
            type: string
          example:
          - yJSObdNNtOetCHWHPFuz
          - test-user-4zoj1c
        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 or deducted.
          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
        UsersPerCardLimit:
          type: integer
          description: The max amount of user profiles with whom a card can be shared. This can be set to `0` for no limit.
          example: 10
        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.
    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.
    ExpiringCardPointsData:
      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
        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
        CardIdentifier:
          type: string
          description: 'The identifier of the loyalty card, `which must match the regular expression `^[A-Za-z0-9._%+@-]+$`.

            '
          example: summer-loyalty-card-0543
        UsersPerCardLimit:
          type: integer
          description: 'The maximum number of customer profiles with which a card can be shared. This can be set to `0` for no limit.

            '
          minimum: 0
          example: 5
        Profiles:
          type: array
          description: The integration IDs of the customer profiles linked to the card.
          items:
            type: string
            example: URNGV8294NV
    ExpiringCardPointsNotification:
      type: object
      properties:
        TotalResultSize:
          type: integer
          example: 1
        Data:
          type: array
          description: The array of expiring points.
          maxLength: 1000
          items:
            $ref: '#/components/schemas/ExpiringCardPointsData'
        NotificationType:
          type: string
          description: The type of notification.
          enum:
          - LoyaltyCardPointsExpiring
    CardAddedDeductedPointsBalancesNotification:
      type: object
      properties:
        CardIdentifier:
          type: string
          description: Loyalty card identification number.
          example: 123-456-789ATBC
        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:
          - LoyaltyCardAddedDeductedPointsBalances
        ProfileIntegrationIDs:
          type: array
          description: The integration ID of the customer profile to whom points were added or deducted.
          items:
            type: string
          example:
          - yJSObdNNtOetCHWHPFuz
          - test-user-4zoj1c
        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 or deducted.
          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
        UsersPerCardLimit:
          type: integer
          description: The max amount of user profiles with whom a card can be shared. This can be set to `0` for no limit.
          example: 10
        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
  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