TUI Group Vouchers API

openapi: 3.2.0
info:
  title: NewSkies-Digital-Api Vouchers API
  version: 4.8.6.23
  description: Navitaire Digital Api
servers:
- url: https://prod.api.tui/flight/newskies/rest
  description: TUI Prod
- url: https://playground.api.tui/flight/newskies/rest
  description: TUI Playground
security:
- JWT: []
tags:
- name: vouchers
paths:
  /api/nsk/v2/vouchers:
    get:
      tags:
      - vouchers
      summary: Gets vouchers based upon data in the request.
      description: "This endpoint requires agent permissions.\nOnly vouchers from the agent's non-restricted voucher configurations will be returned. To check which voucher\nconfigurations are allowed, kindly use the GET /api/nsk/v1/settings/booking/paymentCodes endpoint.\nIf given a date, one of the following properties are required:\n- CustomerName.LastName\n- CustomerNumber\n- Agent\n\t- Agent.Name\n\t- Agent.Domain\nIf only the begin date is given, the default value of the end date will be the day after the begin date.\nIf only the end date is given, the begin date will be required.\nIf at least one of the market properties is provided, all the other market properties are required.\nIf at least one of the agent properties is provided, the other agent property is required.\nIf the customer first name is provided, the customer last name is required.\n\nGraphQL endpoint: vouchersv3"
      operationId: nsk_v2_vouchers_get
      parameters:
      - name: VoucherIssuanceKey
        in: query
        description: "The unique voucher issuance key.\n            "
        schema:
          type:
          - string
          - 'null'
        x-position: 1
      - name: Market.Destination
        in: query
        description: "Gets or sets the leg arrival station.\n            "
        schema:
          type:
          - string
          - 'null'
          maxLength: 3
          minLength: 0
        x-position: 2
      - name: Market.Origin
        in: query
        description: "Gets or sets the leg departure station.\n            "
        schema:
          type:
          - string
          - 'null'
          maxLength: 3
          minLength: 0
        x-position: 3
      - name: Market.DepartureDate
        in: query
        description: "The departure date.\n            "
        schema:
          type:
          - string
          - 'null'
          format: date-time
        x-position: 4
      - name: Market.Identifier
        in: query
        description: "The unique transportation identifier.\n            "
        schema:
          type:
          - string
          - 'null'
          maxLength: 4
          minLength: 0
        x-position: 5
      - name: Market.CarrierCode
        in: query
        description: "The carrier code.\n            "
        schema:
          type:
          - string
          - 'null'
          maxLength: 3
          minLength: 2
        x-position: 6
      - name: Market.OpSuffix
        in: query
        description: "The op suffix.\nPlease note that this should be a char and not a string.\n            "
        schema:
          type:
          - string
          - 'null'
          maxLength: 1
        x-position: 7
      - name: Agent.Name
        in: query
        description: "The agent name associated with the voucher.\n            "
        schema:
          type:
          - string
          - 'null'
          maxLength: 64
          minLength: 0
        x-position: 8
      - name: Agent.Domain
        in: query
        description: "The domain code associated with the voucher.\n            "
        schema:
          type:
          - string
          - 'null'
          maxLength: 3
          minLength: 0
        x-position: 9
      - name: BeginDate
        in: query
        description: "The starting date.\n            "
        schema:
          type:
          - string
          - 'null'
          format: date-time
        x-position: 10
      - name: EndDate
        in: query
        description: "The ending date.\n            "
        schema:
          type:
          - string
          - 'null'
          format: date-time
        x-position: 11
      - name: PageSize
        in: query
        description: "The Page Size, Default 1000\n            "
        schema:
          type:
          - integer
          - 'null'
          maximum: 5000.0
          minimum: 10.0
        x-position: 12
      - name: LastPageKey
        in: query
        description: "The LastPageKey, where to start paged query.\n            "
        schema:
          type:
          - string
          - 'null'
        x-position: 13
      - name: SortCriteria
        in: query
        description: "Defines the criteria in which the find vouchers result can be sorted. Defaults to `CreatedDateAscending` if not specified or invalid.\n             \nEnumeration values: 0 = CreatedDateAscending, 1 = Name, 2 = CreatedDateDescending"
        schema:
          $ref: '#/components/schemas/FindVoucherSortCriteria'
        x-position: 14
      - name: RecordLocator
        in: query
        description: "The record locator associated with the voucher.\n            "
        schema:
          type:
          - string
          - 'null'
          maxLength: 12
          minLength: 0
        x-position: 15
      - name: CustomerName.FirstName
        in: query
        description: "The first name associated with the voucher.\n            "
        schema:
          type:
          - string
          - 'null'
          maxLength: 64
          minLength: 0
        x-position: 16
      - name: CustomerName.LastName
        in: query
        description: "The last name associated with the voucher.\n            "
        schema:
          type:
          - string
          - 'null'
          maxLength: 64
          minLength: 0
        x-position: 17
      - name: CustomerNumber
        in: query
        description: "The customer number associated with the voucher.\n            "
        schema:
          type:
          - string
          - 'null'
          maxLength: 20
          minLength: 0
        x-position: 18
      - name: ActiveOnly
        in: query
        description: "The flag to indicate if only active items should be returned.\n            "
        schema:
          type: boolean
        x-position: 19
      - name: CultureCode
        in: query
        description: "The culture code of the paged request.\n            "
        schema:
          type:
          - string
          - 'null'
          maxLength: 17
          minLength: 0
        x-position: 20
      responses:
        '200':
          description: OK. Request completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IJsonResponseOfPagedVouchersResponse'
              examples:
                Retrieve Vouchers:
                  description: Successful retrieval of vouchers
                  value:
                    data:
                      lastPageKey: MTAwMA--
                      totalCount: 3
                      vouchers:
                      - createdDate: '2026-07-09T05:55:14.5486216+00:00'
                        voucherKey: NTA2MiExMTcwITEwMDExNzA3MDQxMzAwMDAx
                        reference: '10011707041300001'
                        configurationCode: NOREQ
                        status: 0
                        available: 1000.0
                        firstName: John
                        lastName: Doe
                        personKey: MUNzPRfx
                        voucherIssuanceKey: MTE3MCFHQkFUQ0g-
                        expiration: '9999-12-31T23:59:59.9999999'
                        currencyCode: USD
                        amount: 1000.0
                      - createdDate: '2026-07-09T05:55:14.548623+00:00'
                        voucherKey: QYB3NsFyNUdlSRXyNBXsAyB4JLMyZSFyNEBy
                        reference: '10011707041300002'
                        configurationCode: NOREQ
                        status: 0
                        available: 1000.0
                        firstName: John
                        lastName: Doe
                        personKey: MUNzPRfx
                        voucherIssuanceKey: MTE3MCFHQkFUQ0g-
                        expiration: '9999-12-31T23:59:59.9999999'
                        currencyCode: USD
                        amount: 1000.0
                      - createdDate: '2026-07-09T05:55:14.5486233+00:00'
                        voucherKey: TBS3NlFzLPdyLDRnNDCyMfB4NFFyNjBzFAGg
                        reference: '10011707041300003'
                        configurationCode: NOREQ
                        status: 0
                        available: 1000.0
                        firstName: John
                        lastName: Doe
                        personKey: MUNzPRfx
                        voucherIssuanceKey: MTE3MCFHQkFUQ0g-
                        expiration: '9999-12-31T23:59:59.9999999'
                        currencyCode: USD
                        amount: 1000.0
                Invalid Sort Criteria:
                  description: The provided sort criteria is invalid or not defined in the system.
                  value:
                    messages:
                    - code: core:Validation:MalformedRequest
                      type: Information
                      value: The value 'CreatedTime' is invalid.
                      status: 1
                      details: null
                    data:
                      lastPageKey: MTAwMA--
                      totalCount: 1
                      vouchers:
                      - createdDate: '2026-07-09T05:55:14.5486252+00:00'
                        voucherKey: NTA2MiExMTcwITEwMDExNzA3MDQxMzAwMDAx
                        reference: '10011707041300001'
                        configurationCode: NOREQ
                        status: 0
                        available: 1000.0
                        firstName: John
                        lastName: Doe
                        personKey: MUNzPRfx
                        voucherIssuanceKey: MTE3MCFHQkFUQ0g-
                        expiration: '9999-12-31T23:59:59.9999999'
                        currencyCode: USD
                        amount: 1000.0
        '404':
          description: The item was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IJsonResponse'
        '400':
          description: There was a problem with the request and it could not be completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IJsonResponse'
              examples:
                All matching vouchers are restricted to the agent:
                  description: Example response when all the vouchers that satisfies the search query belongs to the agent's restricted voucher configuration
                  value:
                    errors:
                    - id: null
                      code: nsk-server:AuthorizationSearchVoucherNotAllowed
                      message: nsk-server:AuthorizationSearchVoucherNotAllowed
                      type: Validation
                      details:
                        message: Agent is not authorized to search restricted voucher reference numbers with voucher basis code(s) NOREQ.
                      rawMessage: Agent is not authorized to search restricted voucher reference numbers with voucher basis code(s) NOREQ.
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                    data: null
                No filters specified:
                  description: Example response when no filters are specified.
                  value:
                    errors:
                    - id: null
                      code: nsk-server:VoucherNotFound
                      message: nsk-server:VoucherNotFound
                      type: Validation
                      details: null
                      rawMessage: 'Please specify any of the search criteria: Voucher Details/Passenger Details/Record Locator/Flight Details/Agent Details.'
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                    data: null
                At least one of the market properties is specified and no destination is specified:
                  description: Example response when at least one of the market properties is specified and the destination is set to null or an empty string.
                  value:
                    errors:
                    - id: null
                      code: VoucherMarketInformation.Destination:RequiredAttribute
                      message: VoucherMarketInformation.Destination:RequiredAttribute
                      type: Validation
                      details:
                        validation: RequiredAttribute
                        model: VoucherMarketInformation
                        member: Destination
                      rawMessage: The VoucherMarketInformation field is required.
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                    data: null
                At least one of the market properties is specified and no origin is specified:
                  description: Example response when at least one of the market properties is specified and the origin is set to null or an empty string.
                  value:
                    errors:
                    - id: null
                      code: VoucherMarketInformation.Origin:RequiredAttribute
                      message: VoucherMarketInformation.Origin:RequiredAttribute
                      type: Validation
                      details:
                        validation: RequiredAttribute
                        model: VoucherMarketInformation
                        member: Origin
                      rawMessage: The VoucherMarketInformation field is required.
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                    data: null
                At least one of the market properties is specified and no departure date is specified:
                  description: Example response when at least one of the market properties is specified and the departure date is set to null.
                  value:
                    errors:
                    - id: null
                      code: VoucherMarketInformation.DepartureDate:RequiredAttribute
                      message: VoucherMarketInformation.DepartureDate:RequiredAttribute
                      type: Validation
                      details:
                        validation: RequiredAttribute
                        model: VoucherMarketInformation
                        member: DepartureDate
                      rawMessage: The VoucherMarketInformation field is required.
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                    data: null
                At least one of the market properties is specified and no identifier is specified:
                  description: Example response when at least one of the market properties is specified and the identifier is set to null or an empty string.
                  value:
                    errors:
                    - id: null
                      code: VoucherMarketInformation.Identifier:RequiredAttribute
                      message: VoucherMarketInformation.Identifier:RequiredAttribute
                      type: Validation
                      details:
                        validation: RequiredAttribute
                        model: VoucherMarketInformation
                        member: Identifier
                      rawMessage: The VoucherMarketInformation field is required.
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                    data: null
                At least one of the market properties is specified and no carrier code is specified:
                  description: Example response when at least one of the market properties is specified and the carrier code is set to null or an empty string.
                  value:
                    errors:
                    - id: null
                      code: VoucherMarketInformation.CarrierCode:RequiredAttribute
                      message: VoucherMarketInformation.CarrierCode:RequiredAttribute
                      type: Validation
                      details:
                        validation: RequiredAttribute
                        model: VoucherMarketInformation
                        member: CarrierCode
                      rawMessage: The VoucherMarketInformation field is required.
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                    data: null
                Agent name is specified and agent domain is not specified:
                  description: Example response when the agent name is specified and the agent domain is set to null or an empty string.
                  value:
                    errors:
                    - id: null
                      code: Agent.Domain:RequiredAttribute
                      message: Agent.Domain:RequiredAttribute
                      type: Validation
                      details:
                        validation: RequiredAttribute
                        model: Agent
                        member: Domain
                      rawMessage: The Agent field is required.
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                    data: null
                Agent domain is specified and agent name is not specified:
                  description: Example response when the agent domain is specified and the agent name is set to null or an empty string.
                  value:
                    errors:
                    - id: null
                      code: Agent.Name:RequiredAttribute
                      message: Agent.Name:RequiredAttribute
                      type: Validation
                      details:
                        validation: RequiredAttribute
                        model: Agent
                        member: Name
                      rawMessage: The Agent field is required.
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                    data: null
                Customer first name is specified and customer last name is not specified:
                  description: Example response when the customer first name is specified and the customer last name is set to null or an empty string.
                  value:
                    errors:
                    - id: null
                      code: CustomerName.LastName:RequiredAttribute
                      message: CustomerName.LastName:RequiredAttribute
                      type: Validation
                      details:
                        validation: RequiredAttribute
                        model: CustomerName
                        member: LastName
                      rawMessage: The CustomerName field is required.
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                    data: null
                End date is specified and begin date is not specified:
                  description: Example response when end date is specified and begin date is null.
                  value:
                    errors:
                    - id: null
                      code: nsk:Voucher:VoucherBeginDateRequired
                      message: nsk:Voucher:VoucherBeginDateRequired
                      type: Validation
                      details:
                        beginDate: null
                      rawMessage: Voucher creation begin date is required.
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                    data: null
                End date is earlier than begin date:
                  description: Example response when the end date is earlier than the begin date.
                  value:
                    errors:
                    - id: null
                      code: nsk:EndDate:EndDateBeforeBeginDate
                      message: nsk:EndDate:EndDateBeforeBeginDate
                      type: Validation
                      details: null
                      rawMessage: The requested end date of 4/29/2025 occurs before the requested begin date of 4/30/2025.
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                    data: null
                Begin date or end date is specified but customer name, customer number, agent name, and agent domain is not specified:
                  description: Example response when the Begin date or end date is specified but customer name, customer number, agent name, and agent domain is set to null or an empty string.
                  value:
                    errors:
                    - id: null
                      code: nsk:Voucher:VoucherSearchRequirementsUnmet
                      message: nsk:Voucher:VoucherSearchRequirementsUnmet
                      type: Validation
                      details:
                        customerName: null
                        customerNumber: null
                        agentName: null
                        agentDomainCode: null
                      rawMessage: 'Requirements unmet: Enter one - Customer Name, Customer Number or Agent Name.'
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                    data: null
      deprecated: true
  /api/nsk/v1/vouchers/{voucherKey}:
    get:
      tags:
      - vouchers
      summary: Gets a specific voucher based upon the voucher key.
      description: 'This endpoint requires agent permissions.


        GraphQL endpoint: voucher'
      operationId: nsk_v1_vouchers_voucherKey_get
      parameters:
      - name: voucherKey
        in: path
        required: true
        description: The voucher key.
        schema:
          type: string
        x-position: 1
      responses:
        '200':
          description: OK. Request completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IJsonResponseOfVoucher'
        '404':
          description: The item was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IJsonResponse'
    patch:
      tags:
      - vouchers
      summary: Changes the voucher status, type, or expiration date.
      description: 'This endpoint requires agent permissions.

        Due to system limitations only one field can be updated per call.

        Voucher types of 0 and 2 (Credit and Service) have been removed from the request for this endpoint

        as they are not valid type to be updated to.


        GraphQL endpoint: voucherModify'
      operationId: nsk_v1_vouchers_voucherKey_patch
      parameters:
      - name: voucherKey
        in: path
        required: true
        description: The voucher key
        schema:
          type: string
        x-position: 1
      requestBody:
        x-name: request
        description: The voucher update request.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VoucherUpdateRequestv2'
        required: true
        x-position: 2
      responses:
        '200':
          description: OK. Request completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IJsonResponse'
        '400':
          description: There was a problem with the request and it could not be completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IJsonResponse'
              examples:
                Multiple field update:
                  description: Example error if more than one field is being updated
                  value:
                    errors:
                    - id: null
                      code: nsk-server:Vouchers
                      message: Changing VoucherType when changing the Status on a Voucher to Void is not supported
                      type: Error
                      details:
                        voucherWarningMessage: Changing VoucherType when changing the Status on a Voucher to Void is not supported
                      rawMessage: null
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                    - id: null
                      code: nsk-server:Vouchers
                      message: Changing ExpirationDate when changing the Status on a Voucher to Void is not supported
                      type: Error
                      details:
                        voucherWarningMessage: Changing ExpirationDate when changing the Status on a Voucher to Void is not supported
                      rawMessage: null
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                    - id: null
                      code: nsk-server:Vouchers
                      message: Changing VoucherType when reinstating a Voucher is not supported
                      type: Error
                      details:
                        voucherWarningMessage: Changing VoucherType when reinstating a Voucher is not supported
                      rawMessage: null
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                    - id: null
                      code: nsk-server:Vouchers
                      message: Changing ExpirationDate when reinstating a Voucher is not supported
                      type: Error
                      details:
                        voucherWarningMessage: Changing ExpirationDate when reinstating a Voucher is not supported
                      rawMessage: null
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                    - id: null
                      code: nsk-server:Vouchers
                      message: Changing the Status of a Voucher when extending the ExpirationDate is not supported
                      type: Error
                      details:
                        voucherWarningMessage: Changing the Status of a Voucher when extending the ExpirationDate is not supported
                      rawMessage: null
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                    - id: null
                      code: nsk-server:Vouchers
                      message: Changing the VoucherType of a Voucher when extending the ExpirationDate is not supported
                      type: Error
                      details:
                        voucherWarningMessage: Changing the VoucherType of a Voucher when extending the ExpirationDate is not supported
                      rawMessage: null
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                    - id: null
                      code: nsk-server:Vouchers
                      message: Changing the Status of a Voucher when changing the VoucherType is not supported
                      type: Error
                      details:
                        voucherWarningMessage: Changing the Status of a Voucher when changing the VoucherType is not supported
                      rawMessage: null
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                    - id: null
                      code: nsk-server:Vouchers
                      message: Changing ExpirationDate of a Voucher when changing a VoucherType is not supported
                      type: Error
                      details:
                        voucherWarningMessage: Changing ExpirationDate of a Voucher when changing a VoucherType is not supported
                      rawMessage: null
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                    data: null
                Invalid voucher type:
                  description: Example error if an invalid voucher type is used
                  value:
                    errors:
                    - id: null
                      code: nsk:Exceptions:OutOfRange
                      message: 'The value ''2'' is out of range for ''VoucherUpdateRequestv2.Type''.Expected values: (1,3,4,5,6)'
                      type: Validation
                      details: null
                      rawMessage: null
                      exception: null
                      debugMode: The API is currently running in debug mode. In production the 'rawMessage' and 'exception' nodes will not be returned. These are for troubleshooting development issues only.
                    data: null
  /api/nsk/v1/vouchers/{voucherKey}/owner:
    patch:
      tags:
      - vouchers
      summary: Changes the voucher owner.
      description: 'This endpoint requires agent permissions.

        If the personKey is populated, the vou

# --- truncated at 32 KB (137 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tui-group/refs/heads/main/openapi/tui-group-vouchers-api-openapi.yml