openapi: 3.2.0
info:
  title: Publiq Rewards API
  version: '4.0'
  contact:
    name: publiq helpdesk
    email: technical-support@publiq.be
    url: https://docs.publiq.be
  x-refined-note:
  - x-source differs across the merged source definitions and was not carried
  description: 'Operations tagged Rewards across 2 of this provider''s published API definitions: uitpas-uitpas.json, publiq-uitpas-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api-test.uitpas.be
  description: Testing
- url: https://api.uitpas.be
  description: Production
tags:
- name: Rewards
paths:
  /rewards:
    get:
      x-internal: false
      summary: Search rewards
      operationId: get-rewards
      responses:
        '200':
          description: Paginated collection of rewards.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RewardsPaginatedResponse'
              examples:
                Example:
                  value:
                    totalItems: 1
                    member:
                    - id: '1234'
                      title: Free entrance for 10 points on 1 specific event
                      type: POINTS
                      owningCardSystem:
                        id: 1
                        name: UiTPAS Dender
                      categories:
                      - Doen
                      allCardSystems: true
                      status: ACTIVE
                      maxAvailableUnits: 0
                      unitsTaken: 0
                      promotionalDescription: this is the mandatory description
                      practicalInfo: this is an optional extra description
                      pictures:
                      - https://www.uitpas.be/default-picture-for-ticketsale-rewards.png
                      publicationPeriod:
                        begin: '2021-08-24T14:15:22+00:00'
                        end: '2022-08-24T14:15:22+00:00'
                      redeemPeriod:
                        begin: '2021-08-24T14:15:22+00:00'
                        end: '2022-08-24T14:15:22+00:00'
                      grantingPeriod:
                        begin: '2021-08-24T14:15:22+00:00'
                        end: '2022-08-24T14:15:22+00:00'
                      moreInfoURL: https://www.uitpas.be/reward/example-more-info
                      inSpotlight: false
                      points: 10
                      forKids: false
                      sport: false
                      online: false
                      featured: true
                    facet:
                      categories:
                        Doen:
                          name:
                            nl: Doen
                          count: 402
                        Gadget:
                          name:
                            nl: Gadget
                          count: 101
                      owningCardSystemId:
                        '1':
                          name:
                            nl: UiTPAS Dender
                          count: 124
                        '8':
                          name:
                            nl: UiTPAS Gent
                          count: 503
                      sport:
                        'true':
                          name:
                            nl: Sportactiviteiten
                          count: 45
                        'false':
                          name:
                            nl: Geen sportactiviteiten
                          count: 458
                      forKids:
                        'true':
                          name:
                            nl: Speciaal voor kinderen
                          count: 24
                        'false':
                          name:
                            nl: Niet speciaal voor kinderen
                          count: 479
        '400':
          description: 'Bad Request. Possible error types:


            * https://api.publiq.be/probs/uitpas/organizer-not-found

            * https://api.publiq.be/probs/uitpas/event-not-found

            * https://api.publiq.be/probs/uitpas/cardsystem-not-found

            * https://api.publiq.be/probs/url/query-limit-exceeded'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: 'Not Found. Error type:


            https://api.publiq.be/probs/url/not-found'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Rewards
      description: 'Search rewards.


        The caller of this request does not need special permissions permission except `REWARDS_PASSHOLDERS_READ` to use the `isRedeemableByPassholderId` and `isInterestingForPassholderId` query parameters.


        This endpoint allows authentication with client identification, client access tokens, and user access tokens.'
      security:
      - USER_ACCESS_TOKEN: []
      - CLIENT_ACCESS_TOKEN: []
      - CLIENT_IDENTIFICATION: []
      parameters:
      - $ref: '#/components/parameters/start'
      - $ref: '#/components/parameters/limit'
      - schema:
          type: array
          items:
            type: string
        in: query
        name: organizerId
        description: Include only rewards applicable for this organizer. Can be included more than once to allow multiple values.
        style: form
        explode: true
      - schema:
          type: array
          items:
            type: string
        in: query
        name: organizerPostalCode
        description: Include only rewards applicable for organizers with this postal code. Can be included more than once to allow multiple values.
        style: form
        explode: true
      - schema:
          type: array
          items:
            type: string
        in: query
        name: owningCardSystemId
        description: Include only rewards of this card system. Can be included more than once to allow multiple values.
        style: form
        explode: true
      - schema:
          type: array
          items:
            type: string
        in: query
        name: applicableCardSystemId
        description: Include only rewards applicable to passholders of this card system. Can be included more than once to allow multiple values.
        style: form
        explode: true
      - schema:
          type: string
          enum:
          - POINTS
          - WELCOME
          - ANY
          default: POINTS
        in: query
        name: type
        description: Include only rewards of this type. By default, this is set to `POINTS`. Use `ANY` to include rewards of any type.
        style: form
      - schema:
          type: string
        in: query
        name: text
        description: Free text search in reward name, organizer or city.
        style: form
      - schema:
          type: array
          items:
            type: string
            enum:
            - categories
            - forKids
            - sport
            - online
            - lastChance
            - owningCardSystemId
            - type
        in: query
        name: facets
        description: Request facets of the given field in the response. Can be included more than once to allow multiple values.
        style: form
        explode: true
      - schema:
          type: string
          example: -redeemCount,points
        in: query
        name: sort
        description: 'Sorts the rewards in a specific order. Possible values are: `name`, `creationdate`, `redeemCount`, `featured`, `points`. Multiple values can be combined in a comma separated string so the rewards are first sorted by the first field, then the second and so on. By default the sort uses ascending order. Descending order can be specified by including a `-` sign before the field that needs to be ordered descending. e.g. use `-redeemCount,points` to sort descending on redeemCount, and next ascending on `points`.'
        style: form
      - schema:
          type: string
          enum:
          - asc
          - desc
        in: query
        name: sort[name]
        description: Sorts the rewards by their name in ascending or descending order. This parameter is deprecated. Use the `sort` parameter for more advanced sorting options.
        style: form
        deprecated: true
      - schema:
          type: string
          enum:
          - asc
          - desc
        in: query
        name: sort[creationDate]
        description: Sort on reward creation date. This parameter is deprecated. Use the `sort` parameter for more advanced sorting options.
        style: form
        deprecated: true
      - schema:
          type: string
          enum:
          - asc
          - desc
        in: query
        name: sort[redeemCount]
        description: Sort on redeem count. This parameter is deprecated. Use the `sort` parameter for more advanced sorting options.
        style: form
        deprecated: true
      - schema:
          type: string
          enum:
          - asc
          - desc
        in: query
        name: sort[featured]
        description: Sort on featured. This parameter is deprecated. Use the `sort` parameter for more advanced sorting options.
        style: form
        deprecated: true
      - schema:
          type: string
          enum:
          - asc
          - desc
        in: query
        name: sort[points]
        description: Sort on reward points. This parameter is deprecated. Use the `sort` parameter for more advanced sorting options.
        style: form
        deprecated: true
      - schema:
          type: array
          items:
            type: string
            enum:
            - Goede doel
            - Eten en drinken
            - Doen
            - Gadget of item
        in: query
        name: categories
        description: Include only rewards of this category. Can be included more than once to allow multiple values.
        style: form
        explode: true
      - schema:
          type: integer
        in: query
        name: pointsFrom
        description: Include only rewards with this value (including) or more points.
        style: form
      - schema:
          type: integer
        in: query
        name: pointsTo
        description: Include only rewards with this value (including) or less points.
        style: form
      - schema:
          type: string
          default: ENDUSERS
          enum:
          - ALL
          - ENDUSERS
          - REDEEMABLE
          - REDEEMABLE-FUTURE
          - ENDUSER-FUTURE
        in: query
        name: subset
        description: Include only rewards of a specific subset. Defaults to `ENDUSERS`, which means all active rewards, that are currently published and in its redeem period and are part of a permanent cardsystem. `REDEEMABLE` is the same as `ENDUSER` except filtering on publication date. `ENDUSER-FUTURE` and `REDEEMABLE-FUTURE` is similar to their respective subset, but filters on a redeem date in the future. Set this field to `ALL` to include all rewards.
        style: form
      - schema:
          type: boolean
        in: query
        name: sport
        description: Include only rewards with the sport property true or false. If omitted, rewards with any sport value are included.
      - schema:
          type: boolean
        in: query
        name: forKids
        description: Include only rewards with the forKids property true or false. If omitted, rewards with any forKids value are included.
      - schema:
          type: boolean
        in: query
        name: featured
        description: Include only rewards with the featured property true or false. If omitted, rewards with any featured value are included.
      - schema:
          type: boolean
        in: query
        name: online
        description: Include only rewards with the online property true or false. If omitted, rewards with any online value are included.
      - schema:
          type: boolean
        in: query
        name: lastChance
        description: Include only rewards with the lastChance property true or false. If omitted, rewards with any lastChance value are included.
      - schema:
          type: string
          enum:
          - ACTIVE
          - INACTIVE
          - DELETED
        in: query
        name: status
        description: Include only rewards with this status. Also set `subset=ALL` to include non-ACTIVE rewards.
      - schema:
          type: string
        in: query
        name: isRedeemableByPassholderId
        description: Include only rewards that are redeemable by this passholder ID. This means the reward itself is within its redeem period, and all redeem constraints for the passholder are met. A client using this parameter needs `REWARDS_PASSHOLDERS_READ` permission.
      - schema:
          type: string
        in: query
        name: isInterestingForPassholderId
        description: Include a list of suggested rewards based on the recent activity of this passholder ID. A client using this parameter needs `REWARDS_PASSHOLDERS_READ` permission.
    post:
      x-internal: false
      summary: Create new reward
      operationId: post-rewards
      responses:
        '200':
          description: Reward created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reward'
              examples:
                Points reward:
                  value:
                    id: '1234'
                    type: POINTS
                    title: Gratis koffie
                    owningCardSystem:
                      id: 1
                      name: UiTPAS Dender
                    allCardSystems: true
                    status: ACTIVE
                    maxAvailableUnits: 100
                    unitsTaken: 0
                    promotionalDescription: this is the mandatory description
                    pictures:
                    - https://www.uitpas.be/default-picture-for-points-rewards.png
                    publicationPeriod:
                      begin: '2021-08-24T14:15:22+00:00'
                      end: '2022-08-24T14:15:22+00:00'
                    redeemPeriod:
                      begin: '2021-08-24T14:15:22+00:00'
                      end: '2022-08-24T14:15:22+00:00'
                    moreInfoURL: https://example.org/more-info-about-this-reward
                    inSpotlight: false
                    points: 3
                    categories:
                    - Eten en drinken
                    forKids: false
                    sport: false
                    online: true
                Welcome reward:
                  value:
                    id: '1234'
                    type: WELCOME
                    title: Gratis zwemmen
                    owningCardSystem:
                      id: 1
                      name: UiTPAS Dender
                    allCardSystems: true
                    status: ACTIVE
                    maxAvailableUnits: 100
                    unitsTaken: 0
                    promotionalDescription: this is the mandatory description
                    pictures:
                    - https://www.uitpas.be/default-picture-for-welcome-rewards.png
                    publicationPeriod:
                      begin: '2021-08-24T14:15:22+00:00'
                      end: '2022-08-24T14:15:22+00:00'
                    redeemPeriod:
                      begin: '2021-08-24T14:15:22+00:00'
                      end: '2022-08-24T14:15:22+00:00'
                    grantingPeriod:
                      begin: '2021-08-24T14:15:22+00:00'
                      end: '2022-08-24T14:15:22+00:00'
                    inSpotlight: false
                    forKids: false
                    sport: false
                    online: false
        '400':
          description: 'Bad Request. Possible error types:


            * https://api.publiq.be/probs/body/missing

            * https://api.publiq.be/probs/body/invalid-syntax

            * https://api.publiq.be/probs/body/invalid-data

            * https://api.publiq.be/probs/uitpas/invalid-card-system


            The detail property might include more information for the client developer.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      security:
      - USER_ACCESS_TOKEN: []
      - CLIENT_ACCESS_TOKEN: []
      description: 'Create a new reward.


        The caller of this request must have `REWARDS_WRITE` permission for the given organizer.'
      tags:
      - Rewards
      requestBody:
        description: Details of the new reward to create.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Reward'
            examples:
              Points Reward Example:
                value:
                  title: Free entrance for 10 points on 1 specific event
                  type: POINTS
                  categories:
                  - Doen
                  promotionalDescription: this is the mandatory description
                  publicationPeriod:
                    begin: '2021-08-24T14:15:22+00:00'
                  moreInfoURL: https://example.org/more-info-about-this-reward
                  points: 10
              Welcome Reward Example:
                value:
                  title: Gratis tas koffie
                  type: WELCOME
                  promotionalDescription: this is the mandatory description
                  publicationPeriod:
                    begin: '2021-08-24T14:15:22+00:00'
    servers:
    - url: https://api-test.uitpas.be
      description: Testing
    - url: https://api.uitpas.be
      description: Production
  /rewards/{rewardId}:
    parameters:
    - schema:
        type: string
      name: rewardId
      in: path
      required: true
      description: Unique ID of a single reward.
    get:
      x-internal: false
      summary: Retrieve reward
      tags:
      - Rewards
      responses:
        '200':
          description: Details of the requested reward.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reward'
              examples:
                Example:
                  value:
                    id: '1234'
                    type: POINTS
                    title: Free entrance for 10 points on 1 specific event UPDATE
                    owningCardSystem:
                      id: 1
                      name: UiTPAS Dender
                    allCardSystems: true
                    status: ACTIVE
                    maxAvailableUnits: 0
                    unitsTaken: 0
                    promotionalDescription: this is the mandatory description
                    practicalInfo: this is an optional extra description
                    pictures:
                    - https://www.uitpas.be/default-picture-for-ticketsale-rewards.png
                    publicationPeriod:
                      begin: '2021-08-24T14:15:22+00:00'
                      end: '2022-08-24T14:15:22+00:00'
                    redeemPeriod:
                      begin: '2021-08-24T14:15:22+00:00'
                      end: '2022-08-24T14:15:22+00:00'
                    grantingPeriod:
                      begin: '2021-08-24T14:15:22+00:00'
                      end: '2022-08-24T14:15:22+00:00'
                    moreInfoURL: https://example.org/more-info-about-this-reward
                    inSpotlight: false
                    points: 10
                    categories:
                    - Eten en drinken
                    forKids: false
                    sport: false
                    online: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: 'Not Found. Possible error types:


            * https://api.publiq.be/probs/uitpas/reward-not-found


            The detail property might include more information for the client developer.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: get-rewards-id
      security:
      - USER_ACCESS_TOKEN: []
      - CLIENT_ACCESS_TOKEN: []
      description: 'Retrieve reward by ID.


        The caller of this request must have `REWARDS_READ` permission for the given organizer.'
    put:
      x-internal: false
      summary: Update reward
      operationId: put-rewards-id
      responses:
        '200':
          description: Updated info for the reward with the given ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Reward'
              examples:
                Example:
                  value:
                    id: '1234'
                    type: POINTS
                    title: Gratis toegangsticket voor het Design Museum Brussel
                    owningCardSystem:
                      id: 1
                      name: UiTPAS Dender
                    allCardSystems: true
                    status: ACTIVE
                    maxAvailableUnits: 1000
                    unitsTaken: 0
                    promotionalDescription: this is the mandatory description
                    practicalInfo: this is an optional extra description
                    pictures:
                    - https://www.uitpas.be/default-picture-for-ticketsale-rewards.png
                    publicationPeriod:
                      begin: '2021-08-24T14:15:22+00:00'
                      end: '2022-08-24T14:15:22+00:00'
                    redeemPeriod:
                      begin: '2021-08-24T14:15:22+00:00'
                      end: '2022-08-24T14:15:22+00:00'
                    grantingPeriod:
                      begin: '2021-08-24T14:15:22+00:00'
                      end: '2022-08-24T14:15:22+00:00'
                    moreInfoURL: https://www.uitpas.be/reward/example-more-info
                    inSpotlight: false
                    points: 10
                    categories:
                    - Doen
                    forKids: false
                    sport: false
                    online: false
        '400':
          description: 'Bad Request. Possible error types:


            * https://api.publiq.be/probs/body/missing

            * https://api.publiq.be/probs/body/invalid-syntax

            * https://api.publiq.be/probs/body/invalid-data

            * https://api.publiq.be/probs/uitpas/invalid-card-system

            * https://api.publiq.be/probs/uitpas/reward-not-editable


            The detail property might include more information for the client developer.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: 'Not Found. Possible error types:


            * https://api.publiq.be/probs/uitpas/reward-not-found


            The detail property might include more information for the client developer.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
      - USER_ACCESS_TOKEN: []
      - CLIENT_ACCESS_TOKEN: []
      requestBody:
        description: New details for the reward. Will overwrite the previous details.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Reward'
            examples:
              Example:
                value:
                  title: Gratis toegangsticket voor het Design Museum Brussel
                  type: POINTS
                  maxAvailableUnits: 1000
                  categories:
                  - Doen
                  promotionalDescription: this is the mandatory description
                  practicalInfo: this is an optional extra description
                  publicationPeriod:
                    begin: '2021-08-24T14:15:22+00:00'
                    end: '2022-08-24T14:15:22+00:00'
                  redeemPeriod:
                    begin: '2021-08-24T14:15:22+00:00'
                    end: '2022-08-24T14:15:22+00:00'
                  grantingPeriod:
                    begin: '2021-08-24T14:15:22+00:00'
                    end: '2022-08-24T14:15:22+00:00'
                  moreInfoURL: https://example.org/more-info-about-this-reward
                  points: 10
      tags:
      - Rewards
      description: 'Update reward.

        To update a reward correctly, as a client you will typically `GET` the reward first, make the required changes in the reward json and use this `PUT` request to persist those changes in UiTPAS.


        Do note that the following fields are **not editable** after this reward is redeemed by (for POINTS rewards) or granted to (for WELCOME rewards) a passholder:

        * redeemPeriod.begin

        * grantingPeriod.begin

        * points


        Attempts to edit such rewards will result in an HTTP 400 error with type `https://api.publiq.be/probs/uitpas/reward-not-editable`


        The caller of this request must have `REWARDS_WRITE` permission for the given organizer.'
    servers:
    - url: https://api-test.uitpas.be
      description: Testing
    - url: https://api.uitpas.be
      description: Production
  /rewards/{rewardId}/redeem-status:
    parameters:
    - schema:
        type: string
      name: rewardId
      in: path
      required: true
      description: Unique ID of a single reward.
    get:
      x-internal: false
      summary: Check redeem status of a reward for a passholder
      operationId: get-rewards-id-redeem-status
      responses:
        '200':
          description: Info that indicates if the reward with the given ID is redeemable or not by the passholder with the given UiTPAS number.
          content:
            application/json:
              schema:
                type: object
                properties:
                  redeemable:
                    type: boolean
                    description: Whether this reward can be redeemed by the given passholder.
                    readOnly: true
                  reason:
                    type: string
                    description: 'If redeemable is false, this field contains the reason why:

                      - `INVALID_CARD`: the given `uitpasNumber` is not valid.

                      - `PASSHOLDER_VOLUME`: maximum number of times this reward can be redeemed per passholder has been reached.

                      - `PASSHOLDER_POINTS`: passholder does not have enough points to redeem this reward.

                      - `REWARD_PERIOD`: the current date is outside the redeemPeriod of this reward

                      - `REWARD_VOLUME`: maximum number of times this reward can be redeemed (in general) has been reached.

                      - `PASSHOLDER_APPLICABLE_CARDSYSTEMS`: the passholder is not a member of one of the applicable card systems of this reward.

                      - `PASSHOLDER_NO_ACTIVE_CARDSYSTEMS`: the passholder is not active or has no active card system memberships

                      '
                    enum:
                    - INVALID_CARD
                    - PASSHOLDER_VOLUME
                    - PASSHOLDER_POINTS
                    - REWARD_PERIOD
                    - REWARD_VOLUME
                    - PASSHOLDER_APPLICABLE_CARDSYSTEMS
                    - PASSHOLDER_NO_ACTIVE_CARDSYSTEM
                  message:
                    type: string
                    description: User readable message of the reason (only if redeemable if false)
                    readOnly: true
                required:
                - redeemable
              examples:
                Example redeemable:
                  value:
                    redeemable: true
                Example not redeemable:
                  value:
                    redeemable: false
                    reason: PASSHOLDER_POINTS
                    message: Jammer, je hebt nog niet genoeg punten om dit voordeel om te ruilen.
        '400':
          description: 'Bad Request. Possible error types:


            * https://api.publiq.be/probs/uitpas/invalid-uitpas-number

            * https://api.publiq.be/probs/uitpas/passholder-not-found

            '
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: 'Not Found. Possible error types:


            * https://api.publiq.be/probs/uitpas/reward-not-found'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
      description: 'Check the reward redeem status for a passholder.


        The caller of this request must have `REWARDS_REDEEM` permission for the given organizer.'
      security:
      - CLIENT_ACCESS_TOKEN: []
      - USER_ACCESS_TOKEN: []
      tags:
      - Rewards
      parameters:
      - schema:
          type: string
        in: query
        required: true
        name: uitpasNumber
        description: UiTPAS number identifying the passholder who wants to redeem this reward.
    servers:
    - url: https://api-test.uitpas.be
      description: Testing
    - url: https://api.uitpas.be
      description: Production
  /rewards/redeemed:
    parameters: []
    post:
      x-internal: false
      summary: Redeem reward
      operationId: post-rewards-redeemed
      responses:
        '201':
          description: Info about the redeemed reward.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedeemedReward'
              examples:
                Example:
                  value:
                    id: 7982c147-7cf6-4268-acdf-ffbd3d77a2ca
                    reward:
                      id: 374a166b-9170-4f9e-a797-48fb5bd6840d
                      title: A great reward
                      type: POINTS
                      promotionalDescription: This is a description
                      publicationPeriod:
                        begin: '2019-08-24T14:15:22+00:00'
                        end: '2019-08-24T14:15:22+00:00'
                      grantingPeriod:
                        begin: '2019-08-24T14:15:22+00:00'
                        end: '2019-08-24T14:15:22+00:00'
                      points: 0
                      moreInfoURL: https://www.uitpas.be/reward/example-more-info
                      owningCardSystem:
                        id: 1
                        name: UiTPAS Dender
                      allCardSystems: true
                      organizers:
                      - id: abc12345
                        name: UiTPAS Test Organizer
                      status: ACTIVE
                      maxAvailableUnits: 100
                      unitsTaken: 0
                      practicalInfo: This is information on how to redeem the reward.
                      pictures:
                      - https://www.uitpas.be/default-picture-for-ticketsale-rewards.png
                      redeemPeriod:
                        begin: '2019-08-24T14:15:22+00:00'
                        end: '2019-08-24T14:15:22+00:00'
                      categories:
                      - Eten en drinken
                      forKids: true
                      sport: true
                      online: false
                    redeemDate: '2019-08-24T14:15:22+00:00'
                    redeemInfo:
                      text: Info on how to use the redeem code
                      link: https://example.com/redeem-your-reward-here
                      label: Claim your discount
                    redeemCode: abc123456789
        '400':
          description: 'Bad Request. Possible error types:


            * https://api.publiq.be/probs/body/missing

            * https://api.publiq.be/probs/body/invalid-syntax

            * https://api.publiq.be/probs/body/invalid-data

            * https://api.publiq.be/probs/uitpas/invalid-card

            * https://api.publiq.be/probs/uitpas/invalid-uitpas-number

            * https://api.publiq.be/probs/uitpas/passholder-not-found

            * https://api.publiq.be/probs/uitpas/reward-not-found

            * https://api.publiq.be/probs/uitpas/reward-period-constraint

            * https://api.publiq.be/probs/uitpas/reward-volume-constraint

            * https://api.publiq.be/probs/uitpas/reward-passholder-volume-constraint

            * https://api.publiq.be/probs/uitpas/reward-passholder-points-constraint

            * https://api.publiq.be/probs/uitpas/reward-passholder-no-applicable-cardsystems

            * https://api.publiq.be/probs/uitpas/passholder-no-active-cardsystems

            '
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: 'Not Found. Possible error types:


            * https://api.publiq.be/probs/uitpas/reward-not-found'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
      description: 'Redeem reward.


        The caller of this request must have `REWARDS_REDEEM` permission for the given organizer.'
      tags:
      - Rewards
      requestBody:
        description: Reward (id) to mark as redeemed, and for which UiTPAS number specifically.
        content:
          application/json:
            schema:
              type: object
              properties:
                rewardId:
                  type: string
                  description: ID of reward to redeem
                uitpasNumber:
                  type: string
                  description: UiTPAS number of the passholder exchanging this reward.
              required:
              - rewardId
              - uitpasNumber
            examples:
              Example:
                value:
                  uitpasNumber: 0930012345615
                  rewardId: fce4bd2f-4dca-4a44-9912-6168f0ac7e5e
      security:
      - CLIENT_ACCESS_TOKEN: []
      - USER_ACCESS_TOKEN: []
    get:
      x-internal: false
      summary: Retrieve redeemed rewards
      operationId: get-rewards-redeemed
      responses:
        '200':
          description: Paginated collection of redeemed rewards.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RedeemedRewardsPaginatedResponse'
              examples:
                Example:
                  value:
                    totalItems: 10
                    member:
                    - id: 7982c147-7cf6-4268-acdf-ffbd3d77a2ca
                      reward:
                        id: 374a166b-9170-4f9e-a797-48fb5bd6840d
                        title: A great reward
                        type: POINTS
                        promotionalDescription: This is a description
                        publicationPeriod:
                          begin: '2019-08-24T14:15:22+00:00'
                          end: '2019-08-24T14:15:22+00:00'
                        grantingPeriod:
                          begin: '2019-08-24T14:15:22+00:00'
                          end: '2019-08-24T14:15:22+00:00'
                        points: 0
                        moreInfoURL: https://www.uitpas.be/reward/example-more-info
                        owningCardSystem:
                          id: 1
                          name: UiTPAS Dender
                        allCardSystems: true
                        organizers:
                        - id: abc12345
                          name: UiTPAS Test Organizer
                        status: ACTIVE
                        maxAvailableUnits: 100
                        unitsTaken: 0
                        practicalInfo: This is information on how to redeem the reward.
                        pictures:
                        - https://www.uitpas.be/default-picture-for-ticketsale-rewards.png
                        redeemPeriod:
                          begin: '2019-08-24T14:15:22+00:00'
                          end: '2019-08-24T14:15:22+00:00'
                        categories:
                        - Eten en drinken
                        forKids: true
                        sport: true
                        online: true
                        lastChance: true
                      redeemDate: '2019-08-24T14:15:22+00:00'
                      redeemInfo:
                        text: Info on how to use the redeem code
                        link: https://example.com/redeem-your-reward-here
                        label: Claim your discount
                      redeemCode: abc123456789
        '400':
          description: 'Bad Request. Possible error types:


            * https://api.publiq.be/probs/uitpas/invalid-uitpas-number

            * https://api.publiq.be/probs/url/query-limit-exceeded


            '
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      description: 'Retrieve redeemed rewards for a passholder.


        Exactly one of query parameters `uitpasNumber` or `passholderId` is required. If both are specified an error is returned.


        The caller of this request must have `REWARDS_READ` permission.'
      security:
      - CLIENT_ACCESS_TOKEN: []
      - USER_ACCESS_TOKEN: []
      tags:
      - Rewards
      parameters:
      - schema:
          type: string
        in: query
        name: uitpasNumber
        description: UiTPAS number identifying the passholder. Cannot be used in combination with `passholderId`
      - schema:
          type: string
          enum:
          - POINTS
          - WELCOME
        in: query
        name: rewardType
        description: Type of the redeemed reward.
      - $ref: '#/components/parameters/start'
      - $ref: '#/components/parameters/limit'
      - schema:
          type: string
        in: query
        name: passholderId
        description: ID of the passholder. Cannot be used in combination with `uitpasNumber`. `organizerId` is required when using this filter.
      - schema:
          type: array
          items:
            type: string
        in: query
        name: organizerId
        description: ID of the organizer where the reward was redeemed.
        explode: true
      - schema:
          type: string
        in: query
        name: rewardTitle
        description: Filter redeemed rewards with this (partial) reward title.
    servers:
    - url: https://api-test.uitpas.be
      description: Testing
    - url: https://api.uitpas.be
      description: Production
  /rewards/redeemed/{redeemedRewardId}:
    parameters:
    - schema:
        type: string
      name: redeemedRewardId
      in: path
      required: true
      description: The ID of the redeemed reward
    delete:
      summary: Cancel a redeemed reward
      operationId: delete-rewards-redeemed-redeemedRewardId
      responses:
        '204':
          description: No Content
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Rewards
      description: 'Cancel a previously redeemed reward.


        The caller of this request must have `REWARDS_REDEEM` permission for the organizer of the given reward.'
      security:
      - USER_ACCESS_TOKEN: []
      - CLIENT_ACCESS_TOKEN: []
    servers:
    - url: https://api-test.uitpas.be
      description: Testing
    - url: https://api.uitpas.be
      description: Production
components:
  responses:
    Unauthorized:
      description: 'Unauthorized. Your request is missing the required credentials to authenticate. See the Authentication documentation for more info.


        * type: https://api.publiq.be/probs/auth/unauthorized

        * detail: might contain a developer-readable explanation of the reason'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
          x-examples:
            Unauthorized:
              value:
                type: https://api.publiq.be/probs/auth/unauthorized
                title: Unauthorized
                status: 401
    Forbidden:
      description: 'Forbidden. Your request was successfully authenticated but you do not have permission to perform this particular request.


        * type: https://api.publiq.be/probs/auth/forbidden

        * detail: might contain a developer-readable explanation of the reason'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
          x-examples:
            Forbidden:
              value:
                type: https://api.publiq.be/probs/auth/forbidden
                title: Forbidden
                status: 403
                detail: user must be admin of organiser abcd1234
  schemas:
    RedeemedRewardsPaginatedResponse:
      title: RewardsPaginatedResponse
      type: object
      x-tags:
      - Models
      description: Paginated response object for rewards
      properties:
        totalItems:
          type: integer
          description: Total number of redeemed reward results (can be more than the amount of results in the response).
        member:
          type: array
          description: List of redeemed reward results for this specific (paginated) request.
          items:
            $ref: '#/components/schemas/RedeemedReward'
    Error:
      $ref: https://raw.githubusercontent.com/cultuurnet/apidocs/main/projects/errors/models/Error.json
    CardSystem:
      title: CardSystem
      description: A region, usually one or multiple municipalities in Belgium, that uses UiTPAS and provides discounts and/or rewards. For example "Paspartoe" (Brussels), UiTPAS Leuven, UiTPAS Hasselt, UiTPAS Gent, and so on.
      type: object
      x-tags:
      - Models
      example:
        id: 1
        name: UiTPAS Dender
        branding:
          logo: https://www.uitpas.be/_nuxt/img/1351557.svg
          primaryColor: rgba(0,0,0,1.0)
          secondaryColor: rgba(97,166,14,1.0)
        links:
          website: https://www.uitpas.be
        cities:
        - postalCode: '9300'
          name: Aalst
        - postalCode: '9400'
          name: Ninove
        permanent: true
      properties:
        id:
          type: integer
          description: ID of the card system
        name:
          type: string
          description: Name of the card system. This field is always available in responses.
        branding:
          type: object
          description: Branding information of the card system
          properties:
            logo:
              type: string
              description: URL to the logo of the card system
            primaryColor:
              type: string
              description: Color code of the primary branding color.
            secondaryColor:
              type: string
              description: Color code of the secondary branding color.
        links:
          type: object
          description: Links of the card system
          properties:
            website:
              type: string
              description: URL of the website of the card system
        cities:
          type: array
          description: List of cities that are part of this card system
          items:
            $ref: '#/components/schemas/City'
        permanent:
          type: boolean
          description: Indicates whether this is a permanent card system
        allowsCardlessRegistration:
          type: boolean
          description: Indicates if cardless registration is enabled
        cardlessRegistrationType:
          type: string
          description: Indicates the types of online cardless registrations this cardsystem supports.
          enum:
          - ALL
          - REGULAR
          - SOCIALTARIFF
          - NONE
        socialTariffInfo:
          type: string
          description: Optional information about social tariff entitlement in this card system.
      required:
      - id
    RewardsPaginatedResponse:
      title: RewardsPaginatedResponse
      type: object
      x-tags:
      - Models
      description: Paginated response object for rewards
      properties:
        totalItems:
          type: integer
          description: Total number of reward results (can be more than the amount of results in the response).
        member:
          type: array
          description: List of reward results for this specific (paginated) request.
          items:
            $ref: '#/components/schemas/Reward'
        facet:
          type: object
          description: Facet information for the requested facets.
          properties:
            categories:
              $ref: '#/components/schemas/Facet'
            owningCardSystemId:
              $ref: '#/components/schemas/Facet'
            type:
              $ref: '#/components/schemas/Facet'
            sport:
              $ref: '#/components/schemas/Facet'
            forKids:
              $ref: '#/components/schemas/Facet'
            online:
              $ref: '#/components/schemas/Facet'
            lastChance:
              $ref: '#/components/schemas/Facet'
    Facet:
      title: Facet
      type: object
      description: Each property is a possible filter value, mapping to an object with a human-readable name and amount of results if the filter value is applied in combination with the other active filters.
      additionalProperties:
        type: object
        properties:
          name:
            type: object
            description: Internationalized human-readable name for the filter value.
            properties:
              nl:
                type: string
                description: Human-readable name for the filter value localized in Dutch.
          count:
            type: integer
            description: Amount of results if the filter is applied in combination with the other active filters.
        required:
        - name
        - count
      x-tags:
      - Models
      example:
        option1:
          name:
            nl: Option 1
          count: 3
        option2:
          name:
            nl: Option 2
          count: 4
      x-examples:
        Example:
          option1:
            name:
              nl: Human-readable name for option1
            count: 3
          option2:
            name:
              nl: Human-readable name for option2
            count: 4
    Reward:
      type: object
      title: Reward
      description: Reward model
      x-tags:
      - Models
      properties:
        id:
          type: string
          description: ID of the reward
          readOnly: true
        title:
          type: string
          description: Title of the reward
        type:
          type: string
          description: Type of the reward
          enum:
          - POINTS
          - WELCOME
        promotionalDescription:
          type: string
          description: Promotion description
        publicationPeriod:
          $ref: '#/components/schemas/Period'
        points:
          type: number
          description: Number of points needed to redeem the reward. Required for reward of type POINTS.
        categories:
          type: array
          description: List of categories of this reward. Required for reward of type POINTS.
          items:
            type: string
            enum:
            - Eten en drinken
            - Doen
            - Gadget of item
            - Goede doel
        moreInfoURL:
          type: string
          description: URL where a user can find more info about this reward. Required for reward of type POINTS.
          format: uri
        grantingPeriod:
          $ref: '#/components/schemas/Period'
        owningCardSystem:
          $ref: '#/components/schemas/CardSystem'
        applicableCardSystems:
          type: array
          description: 'List of CardSystems whose members can redeem this reward. '
          items:
            $ref: '#/components/schemas/CardSystem'
        allCardSystems:
          type: boolean
          description: If set to true, `applicableCardSystems` will always contain all UiTPAS CardSystems.
          default: true
        organizers:
          type: array
          description: List of Organizers where this reward can be redeemed.
          items:
            $ref: '#/components/schemas/Organizer'
        status:
          type: string
          enum:
          - ACTIVE
          - INACTIVE
          - DELETED
          description: Status of this reward.
          readOnly: true
        maxAvailableUnits:
          type: integer
          description: Maximum (total) available units of this reward.
        unitsTaken:
          type: integer
          description: Number of rewards already redeemed.
          readOnly: true
        practicalInfo:
          type: string
          description: Practical info for passholders who want to redeem this reward.
        pictures:
          type: array
          description: List of URLs to zero or more images of this reward.
          items:
            type: string
            format: uri
        redeemPeriod:
          $ref: '#/components/schemas/Period'
        forKids:
          type: boolean
          description: true if this reward is specifically targetted to children.
        sport:
          type: boolean
          description: true if this is a sport reward
        featured:
          type: boolean
          description: true if this reward is currently set as 'featured'
        online:
          type: boolean
          description: true if this reward can be redeemed online
        lastChance:
          type: boolean
          description: true if this rewards will not be redeemable anymore in the near future
          readOnly: true
        redeemConstraint:
          type: object
          description: Defines how many times this reward can be redeemed by the same passholder in a specific period.
          properties:
            volume:
              type: integer
              description: The maximum number of times this reward can be redeemed by the same passholder.
            period:
              type: string
              description: 'The calendar period this volume constraint applies to:

                - `ABSOLUTE`: the constraint applies to any period.

                - `DAY`: the constraint applies from 00:00 to 23:59

                - `WEEK`: the constraint applies from Monday 00:00 to Sunday 23:59

                - `MONTH`: the constraint applies from the first of the month at 00:00 to the last day of the month 23:59

                - `QUARTER`: this constraint applies to the first day of the quarter to the last day: January-March, April-June, July-September, October-December.

                - `YEAR`: from the Jan 1st to Dec 31st'
              enum:
              - ABSOLUTE
              - DAY
              - WEEK
              - MONTH
              - QUARTER
              - YEAR
          required:
          - volume
          - period
      required:
      - title
      - type
      - promotionalDescription
      - publicationPeriod
    RedeemedReward:
      type: object
      title: RedeemedReward
      x-tags:
      - Models
      properties:
        id:
          type: string
          description: ID of the redeemed reward.
        reward:
          $ref: '#/components/schemas/Reward'
        redeemDate:
          type: string
          format: date-time
          description: Date of the redeem action.
        redeemInfo:
          type: object
          description: Information about the redeem action.
          properties:
            text:
              type: string
              description: Text to show to the user who redeemed this reward.
            link:
              type: string
              format: uri
              description: Link for a call-to-action for the redeemed reward.
            label:
              type: string
              description: Label for the call-to-action of the redeemed reward.
        redeemCode:
          type: string
          description: Redeem code to show to the user who redeemed this reward. (Only applicable to certain rewards that are configured in the UiTPAS Card System admin)
      required:
      - id
      - reward
      - redeemDate
    City:
      title: City
      type: object
      x-tags:
      - Models
      example:
        postalCode: '9300'
        name: Aalst
      properties:
        postalCode:
          type: string
          description: Postalcode of the city
        name:
          type: string
          description: Name of the city
      required:
      - postalCode
      - name
    Period:
      title: Period
      type: object
      example:
        begin: '2019-08-24T14:15:22+00:00'
        end: '2019-08-24T14:15:22+00:00'
      x-tags:
      - Models
      description: Period entity with a begin and optional end date.
      properties:
        begin:
          type: string
          format: date-time
          description: Start date of the period (inclusive).
        end:
          type: string
          format: date-time
          description: End date of the period (inclusive).
      required:
      - begin
    Organizer:
      title: Organizer
      type: object
      description: An organisation that partners with UiTPAS to provide discounts and/or rewards, and/or allows points to be collected at their events.
      x-tags:
      - Models
      properties:
        id:
          type: string
          description: Unique ID of an UiTPAS organizer. (Same as its ID in UiTdatabank)
        name:
          type: string
          description: Human-readable name of an UiTPAS organizer.
        cardSystems:
          type: array
          description: Card systems linked to this organizer
          items:
            $ref: '#/components/schemas/CardSystem'
        linkedLocationId:
          type: string
          description: ID of the location linked to this organizer.
          readOnly: true
        address:
          type: object
          description: Address of this organizer. This property is alway available in responses.
          required:
          - city
          properties:
            street:
              type: string
              description: Street address of this organizer
            postalCode:
              type: string
              description: Postal code of this organizer
            city:
              type: string
              description: City of this organizer
          readOnly: true
      required:
      - id
    Error_2:
      title: Error
      type: object
      description: RFC7807 error model for all publiq APIs.
      properties:
        type:
          type: string
          description: A URI reference that identifies the problem type. Can be used to recognize specific errors in your application code by comparing the complete URI.
        title:
          type: string
          description: A short, human-readable summary of the problem type (for developers).
        status:
          type: integer
          description: The HTTP status code.
        detail:
          type: string
          description: 'A human-readable explanation specific to this occurrence of the problem (for developers). '
        endUserMessage:
          type: object
          description: A human-readable explanation of the problem, specifically for end-users, in one or more languages. Typically available for domain errors, but not for errors caused by a technical issue in the integration (for example invalid JSON syntax in a request body). An `nl` value is always provided, other languages may be provided depending on the API and its intended audience. When this property is included, it is strongly encouraged to show this to the end-user.
          properties:
            nl:
              type: string
              description: A human-readable explanation of the problem, specifically for end-users, localized in Dutch.
            fr:
              type: string
              description: A human-readable explanation of the problem, specifically for end-users, localized in French.
            de:
              type: string
              description: A human-readable explanation of the problem, specifically for end-users, localized in German.
            en:
              type: string
              description: A human-readable explanation of the problem, specifically for end-users, localized in English.
          required:
          - nl
        schemaErrors:
          type: array
          description: A list of one or more schema validation errors (usually used for error type https://api.publiq.be/probs/body/invalid-data).
          items:
            type: object
            properties:
              jsonPointer:
                type: string
                format: json-pointer
                description: RFC6901 compliant pointer that indicates what property/value was invalid.
              error:
                type: string
                description: A human-readable (but often technical) reason why the property was invalid.
            required:
            - jsonPointer
            - error
      required:
      - type
      - title
      - status
      x-internal: false
  parameters:
    start:
      schema:
        type: integer
        minimum: 0
        default: 0
      in: query
      name: start
      description: Position to start returning results from. When set to `0` the results starting from the very first position will be returned. When set to for example `10` the results 0-9 will be skipped and the ones starting from position 10 will be returned. Can be used in combination with `limit` for pagination.
    limit:
      schema:
        type: integer
        default: 20
        minimum: 0
      in: query
      name: limit
      description: 'Maximum amount of results to return. Can be used in combination with `start` for pagination. **Important**: the maximum value for `limit` is `500`. Exceeding this value will result in an error.'
  securitySchemes:
    USER_ACCESS_TOKEN:
      type: oauth2
      flows: {}
      description: A user access token, obtained by redirecting the end user to publiq's authorization server to login using the **Authorization Code OAuth Flow**. See the [authentication docs about user access tokens](https://docs.publiq.be/docs/authentication/methods/user-access-token) for more info.
    CLIENT_ACCESS_TOKEN:
      type: oauth2
      flows: {}
      description: A client access token, obtained by exchanging your client id and client secret for a token via an HTTP request to publiq's authorization server using the **Client Credentials OAuth Flow**. See the [authentication docs about client access tokens](https://docs.publiq.be/docs/authentication/methods/client-access-token) for more info.
    CLIENT_IDENTIFICATION:
      name: x-client-id
      type: apiKey
      in: header
    CUSTOM_TOKEN:
      name: x-custom-token
      type: apiKey
      in: header
x-refined-from:
- uitpas-uitpas.json
- publiq-uitpas-openapi.yml