openapi: 3.2.0
info:
  title: Benefits Redemption Rewards Redemption History API
  description: Enables users to view and redeem their rewards
  version: '3.0'
tags:
- name: Rewards-Redemption-History
paths:
  /cards/accounts/external/{externalAccountID}/redemption/history:
    summary: Get rewards redemption history for externalAccountId
    description: Get rewards redemption history for externalAccountId
    get:
      tags:
      - Rewards-Redemption-History
      summary: Get rewards redemption history for externalAccountId
      operationId: getRedemptionHistory
      parameters:
      - name: externalAccountID
        in: path
        description: A unique id (similar to UUID) created for each customer account.
        required: true
        deprecated: false
        schema:
          type: string
          maxLength: 36
          minLength: 1
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
        example: 0dbcb7ee-6c59-483b-966a-44d11557665b
      - name: Correlation-ID
        in: header
        description: 'Unique identifier for each incoming request. The API caller must pass this in the header, which will be cascaded through the API call stack.

          This is required to maintain compliance with the current Barclays REST standards.'
        required: true
        deprecated: false
        allowEmptyValue: false
        schema:
          type: string
          maxLength: 36
          minLength: 36
          pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
        example: 7d444840-9dc0-11d1-b245-5ffdce74fad2
      - name: redemptionType
        in: query
        description: List of redemption types which will be included in response
        required: false
        deprecated: false
        allowEmptyValue: false
        schema:
          type: array
          items:
            type: string
            description: Type of redemption.
            example: CASH_BACK
            maxLength: 50
            minLength: 1
            pattern: ^[a-zA-Z_]{1,50}$
          maxItems: 50
          minItems: 1
        example:
        - CASH_BACK
        - PAY_WITH_POINTS
      - name: includeFailures
        in: query
        description: Include failed redemptions in response
        required: false
        deprecated: false
        allowEmptyValue: false
        schema:
          type: boolean
          default: true
        example: true
      - name: fromDate
        in: query
        description: Fetch redemption history starting from this date
        required: false
        deprecated: false
        allowEmptyValue: false
        schema:
          type: string
          maxLength: 10
          minLength: 10
          pattern: ^\d{4}-\d{2}-\d{2}$
        example: '2024-02-21'
      - name: toDate
        in: query
        description: Fetch redemption history till this date
        required: false
        deprecated: false
        allowEmptyValue: false
        schema:
          type: string
          maxLength: 10
          minLength: 10
          pattern: ^\d{4}-\d{2}-\d{2}$
        example: '2026-02-21'
      - name: Authorization
        in: header
        description: TIAA-US External token
        required: true
        deprecated: false
        schema:
          type: string
        example: Bearer <token>
      responses:
        '200':
          $ref: '#/components/responses/RedemptionHistoryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/500_redemption'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      deprecated: false
components:
  examples:
    example-error-500_ACCOUNT_INELIGIBLE:
      value:
        errors:
        - id: 1c4717c4-e3f3-4071-8b86-b868908763ff
          code: ACCOUNT_INELIGIBLE
          title: Account is not eligible for this program
          detail: Request cannot be processed, account is not eligible for this program
    ResponseWhenIncludeFailures_true:
      value:
        data:
          redemptionHistory:
          - redemptionType: PAY_WITH_POINTS
            redemptionId: '345523423'
            redemptionTimestamp: 08/29/2025 10:15:00
            lineItems:
            - lineItemId: '23423432'
              fulfillmentMethod: STMNT_CR
              rewardName: Pay with Points - Statement Credit
              rewardsRedeemed: 10000
              redemptionAmount:
                currency: USD
                amount: 100
              replenishedRewards: 0
              quantity: 1
              redemptionStatus: COMPLETED
              purchaseDetails:
                authorizationCode: AUTH2342
          - redemptionType: CASH_BACK
            redemptionId: '25322352'
            redemptionTimestamp: 08/29/2025 10:15:00
            lineItems:
            - lineItemId: '35234423'
              fulfillmentMethod: RW_ACH
              rewardName: Direct Deposit to account
              rewardsRedeemed: 10000
              redemptionAmount:
                currency: USD
                amount: 100
              replenishedRewards: 0
              quantity: 1
              redemptionStatus: FAILURE
              redemptionStatusDetail: redemption failure reason
              achDetails:
                accountAlias: Primary Checking
                bankName: Chase Bank
                last4Digits: 5678
    example-error-429:
      value:
        errors:
        - id: 1c4717c4-e3f3-4071-8b86-b868908763ff
          code: TOO_MANY_REQUESTS
          title: Too many requests
          detail: The client sent too many requests and server is not able to serve them all at the moment
    example-error-403:
      value:
        errors:
        - id: 1c4717c4-e3f3-4071-8b86-b868908763ff
          code: ACCESS_FORBIDDEN
          title: The user is not permitted to access the requested operation and it cannot be completed
          detail: The user is not permitted to access the requested operation and it cannot be completed
    example-error-500_BAD_STATUS_ACCOUNT:
      value:
        errors:
        - id: 1c4717c4-e3f3-4071-8b86-b868908763ff
          code: BAD_STATUS_ACCOUNT
          title: Account is in bad status
          detail: Account is in CLOSED status, request cannot be processed
    example-error-500_TEMPORARY_UNPROCESSABLE:
      value:
        errors:
        - id: 1c4717c4-e3f3-4071-8b86-b868908763ff
          code: TEMPORARY_UNPROCESSABLE
          title: Request unprocessable momentarily
          detail: Request cannot be processed momentarily
    example-error-500:
      value:
        errors:
        - id: 1c4717c4-e3f3-4071-8b86-b868908763ff
          code: INTERNAL_SERVER_ERROR
          title: The request failed due to an internal error
          detail: Downstream service call failure while retrieving rewards balance
    example-error-500_INSUFFICIENT_BALANCE:
      value:
        errors:
        - id: 1c4717c4-e3f3-4071-8b86-b868908763ff
          code: INSUFFICIENT_BALANCE
          title: Insufficient reward balance on the account
          detail: Request cannot be processed due to insufficient reward balance
    example-error-401:
      value:
        errors:
        - id: 1c4717c4-e3f3-4071-8b86-b868908763ff
          code: UNAUTHORIZED
          title: The authorization credentials required for this request are invalid
          detail: The authorization credentials required for this request are invalid
    example-error-503:
      value:
        errors:
        - id: 1c4717c4-e3f3-4071-8b86-b868908763ff
          code: SERVICE_UNAVAILABLE
          title: The server is currently unavailable
          detail: Scheduled service outage starting from Wednesday, 04 Jul 2050 0100 GMT until Wednesday, 04 Jul 2050 0500 GMT
    ResponseNonCashRedemption:
      value:
        data:
          redemptionHistory:
          - redemptionType: THIRD_PARTY_REDEMPTION
            redemptionId: OSQEPC371143
            redemptionTimestamp: 08/29/2025 14:30:00
            lineItems:
            - lineItemId: ZFDKKH363591
              rewardName: Samsung Gift Card $50
              rewardsRedeemed: 5000
              fulfillmentMethod: ELECTRONIC
              replenishedRewards: 10
              quantity: 2
              redemptionStatus: COMPLETED
            - lineItemId: SFDKKZ363591
              rewardName: Amazon Gift Card $50
              rewardsRedeemed: 5000
              fulfillmentMethod: PHYSICAL
              shippingDate: 08/29/2025
              replenishedRewards: 0
              quantity: 1
              redemptionStatus: COMPLETED
    example-error-404:
      value:
        errors:
        - id: 1c4717c4-e3f3-4071-8b86-b868908763ff
          code: RESOURCE_NOT_FOUND
          title: The requested operation failed because a resource associated with the request could not be found
          detail: Couldn't locate the account
    example-error-500_BUSINESS_VALIDATION_FAILED:
      value:
        errors:
        - id: 1c4717c4-e3f3-4071-8b86-b868908763ff
          code: BUSINESS_VALIDATION_FAILED
          title: Request failed while validating the account
          detail: Request cannot be processed, account validation failure
    example-error-400-bad-request:
      value:
        errors:
        - id: 1c4717c4-e3f3-4071-8b86-b868908763ff
          code: BAD_REQUEST
          title: The request is invalid or not properly formed
          detail: Invalid request, field name does not match with the API spec
  schemas:
    RedemptionHistoryResponseData:
      type: object
      additionalProperties: false
      deprecated: false
      description: Redemption History Response Data
      properties:
        data:
          $ref: '#/components/schemas/RedemptionHistoryResponse'
      required:
      - data
      nullable: false
    ErrorResponseType:
      type: object
      additionalProperties: false
      deprecated: false
      description: 'An API error response.

        '
      properties:
        meta:
          type: object
          additionalProperties: true
          description: Contains Non-standard meta information
        errors:
          type: array
          description: 'Contains one or more error messages and is mutually exclusive with the data item.

            This will not be returned in success scenarios.

            '
          items:
            $ref: '#/components/schemas/ErrorType'
          maxItems: 50
          minItems: 0
      nullable: false
    RedemptionHistoryResponse:
      type: object
      additionalProperties: false
      deprecated: false
      description: Redemption history Response
      properties:
        redemptionHistory:
          type: array
          description: List of rewards redeemed
          items:
            $ref: '#/components/schemas/Redemption'
          maxItems: 200
          minItems: 0
      required:
      - redemptionHistory
      nullable: false
    TransactionInfo:
      type: object
      additionalProperties: false
      description: Optional metadata supplied by partner for pay with points redemption.
      properties:
        authorizationCode:
          type: string
          description: Authorization code generated by merchant at point of sale.
          example: 5R20BK11W6
          maxLength: 50
          minLength: 1
          pattern: ^[a-zA-Z0-9]{1,50}$
        transactionDesc:
          type: string
          description: Free-text description of the source transaction tied to redemption.
          example: Online order placed at Expedia.com for a hotel booking
          maxLength: 200
          minLength: 1
          pattern: ^.{1,200}$
          nullable: true
      nullable: true
    ErrorType:
      type: object
      additionalProperties: false
      description: Message details - additional operation execution information.
      properties:
        id:
          type: string
          description: Generated message identifier for particular request, helping to locate server logs.
          example: 1c4717c4-d4a5-e3f3-4a71-b868908763ff
          maxLength: 36
          minLength: 36
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
        code:
          type: string
          description: Machine readable, unique code of the message related to particular case within operation execution.
          example: ACCOUNT_NUMBER_NOT_FOUND
          maxLength: 100
          minLength: 1
          pattern: ^[a-zA-Z0-9_]{1,100}$
        title:
          type: string
          description: Short description of the error. Not for displaying purposes.
          example: The authorization credentials required for this request are invalid
          maxLength: 250
          minLength: 1
          pattern: ^[a-zA-Z0-9\s"=,']{1,250}$
        detail:
          type: string
          description: Provides additional low-level details about the error to assist with troubleshooting. Not for displaying purposes.
          maxLength: 250
          minLength: 1
          pattern: ^[a-zA-Z0-9\s"=,']{1,250}$
      required:
      - code
      - id
      - title
    RedemptionAmount:
      type: object
      additionalProperties: false
      deprecated: false
      description: Dollar value of rewards to be applied to the account via statement credit or ACH
      properties:
        currency:
          type: string
          description: Currency
          example: USD
          maxLength: 10
          minLength: 1
          pattern: ^.{1,10}$
        amount:
          type: number
          description: Amount
          example: 20
      nullable: true
    ACHDetails:
      type: object
      additionalProperties: false
      deprecated: false
      description: Contains details of external bank account to which ACH was applied
      properties:
        accountAlias:
          type: string
          description: User-defined account alias
          example: AAA Bank
          maxLength: 200
          minLength: 1
          pattern: ^.{1,200}$
          nullable: false
        bankName:
          type: string
          description: Name of the bank
          example: Barclays
          maxLength: 200
          minLength: 1
          pattern: ^.{1,200}$
          nullable: false
        last4Digits:
          type: number
          description: Last 4 digits of account number
          example: 1234
      nullable: true
    Redemption:
      type: object
      additionalProperties: false
      deprecated: false
      description: Contains redemption history information.
      properties:
        redemptionType:
          type: string
          description: Type of redemption.
          example: CASH_BACK
          maxLength: 30
          minLength: 1
          pattern: ^[a-zA-Z_]{1,30}$
        redemptionId:
          type: string
          description: Unique id generated by Barclays for a redemption
          example: 1c4717c4-d4a5-e3f3-4a71-b868908763ff
          maxLength: 36
          minLength: 1
          pattern: ^[0-9a-zA-Z-]{1,36}$
        redemptionTimestamp:
          type: string
          description: Redemption timestamp in EST
          example: 06/28/2024 03:19:05
          maxLength: 19
          minLength: 19
          pattern: ^\d{2}/\d{2}/\d{4} \d{2}:\d{2}:\d{2}$
        lineItems:
          type: array
          description: List of line items redeemed for a redemption type
          items:
            $ref: '#/components/schemas/LineItem'
          maxItems: 50
          minItems: 1
      required:
      - lineItems
      - redemptionId
      - redemptionTimestamp
      - redemptionType
      nullable: false
    LineItem:
      type: object
      additionalProperties: false
      deprecated: false
      properties:
        lineItemId:
          type: string
          description: line item id
          example: S16705z
          maxLength: 36
          minLength: 1
          pattern: ^[a-zA-Z0-9-]{1,36}$
        rewardName:
          type: string
          description: Reward name
          example: Points Payback Credit
          maxLength: 200
          minLength: 1
          pattern: ^.{1,200}$
        rewardsRedeemed:
          type: number
          description: Rewards redeemed
          example: 11
        fulfillmentMethod:
          type: string
          description: Method of fulfillment or delivery
          example: RW_ACH
          maxLength: 20
          minLength: 1
          pattern: ^.{1,20}$
        shippingDate:
          type: string
          description: Delivery date of Non-Cash gift card/merchandise
          example: 07/25/2025
          maxLength: 10
          minLength: 10
          pattern: ^\d{2}/\d{2}/\d{4}$
          nullable: true
        redemptionAmount:
          $ref: '#/components/schemas/RedemptionAmount'
        replenishedRewards:
          type: number
          description: Rewards replenished during redemption
          example: 11
        quantity:
          type: number
          description: Redeemed quantity of a line item
          example: 10
        redemptionStatus:
          type: string
          description: Redemption status
          enum:
          - ACCEPTED
          - IN_PROCESS
          - COMPLETED
          - FAILURE
          - CANCELLED
          - RETURNED
          example: COMPLETED
        redemptionStatusDetail:
          type: string
          description: Redemption status detail populated if includeFailures is true for failed redemptions
          example: T&C not met
          maxLength: 400
          minLength: 1
          pattern: ^.{1,400}$
          nullable: true
        purchaseDetails:
          $ref: '#/components/schemas/TransactionInfo'
        achDetails:
          $ref: '#/components/schemas/ACHDetails'
      required:
      - fulfillmentMethod
      - lineItemId
      - quantity
      - redemptionStatus
      - rewardName
      - rewardsRedeemed
      nullable: false
  responses:
    BadRequest:
      description: 'The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.

        '
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            BadRequest:
              $ref: '#/components/examples/example-error-400-bad-request'
    ServiceUnavailable:
      description: 'Temporary maintenance of service, try again later. This is a temporary condition which will be alleviated after some delay.

        '
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            ServiceUnavailable:
              $ref: '#/components/examples/example-error-503'
    NotFound:
      description: 'Server was unable to locate a resource to complete the operation. This may be temporary or permanent.

        '
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            NotFound:
              $ref: '#/components/examples/example-error-404'
    500_redemption:
      description: 'Server encountered an error during processing the request. It''s s a generic error message, given when a more specific message is not available.

        '
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            INTERNAL_SERVER_ERROR:
              $ref: '#/components/examples/example-error-500'
            BAD_STATUS_ACCOUNT:
              $ref: '#/components/examples/example-error-500_BAD_STATUS_ACCOUNT'
            INSUFFICIENT_BALANCE:
              $ref: '#/components/examples/example-error-500_INSUFFICIENT_BALANCE'
            ACCOUNT_INELIGIBLE:
              $ref: '#/components/examples/example-error-500_ACCOUNT_INELIGIBLE'
            BUSINESS_VALIDATION_FAILED:
              $ref: '#/components/examples/example-error-500_BUSINESS_VALIDATION_FAILED'
            TEMPORARY_UNPROCESSABLE:
              $ref: '#/components/examples/example-error-500_TEMPORARY_UNPROCESSABLE'
    Forbidden:
      description: 'The user is not permitted to access the requested operation and it cannot be completed.

        '
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            Forbidden:
              $ref: '#/components/examples/example-error-403'
    Unauthorized:
      description: 'The user could not be authenticated for this request.

        '
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            Unauthorized:
              $ref: '#/components/examples/example-error-401'
    TooManyRequests:
      description: 'Server received a large number of requests from a single party in a given amount of time. Client is advised to retry after the agreed cool down period.

        '
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            TooManyRequests:
              $ref: '#/components/examples/example-error-429'
    RedemptionHistoryResponse:
      description: Redemption History Response Data
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RedemptionHistoryResponseData'
          examples:
            Response_NON_CASH_Redemption:
              $ref: '#/components/examples/ResponseNonCashRedemption'
            Response_CASH_Redemption_IncludeFailures_True:
              $ref: '#/components/examples/ResponseWhenIncludeFailures_true'
  headers:
    Cache-Control:
      description: GIS mandatory response header. This is added by the Cognac sidecar.
      schema:
        type: string
        default: no-cache, no-store, must-revalidate
        deprecated: false
        example: no-cache, no-store, must-revalidate
        maxLength: 35
        minLength: 35
        pattern: ^no-cache, no-store, must-revalidate$
        nullable: false
  securitySchemes:
    ExternalTiaaUsCCAuth:
      type: oauth2
      description: OAuth2.0 Client Credentials Grant authentication using TIAA-US for external APIs
      flows:
        clientCredentials:
          tokenUrl: https://token.tiaa-dev.us.barclays.intranet:8443/as/token.oauth2
          scopes:
            read: read only
            write: write only