openapi: 3.2.0
info:
  title: Rewards Earn History API
  description: API for retrieving reward earned information of an account
  version: '1.0'
tags:
- name: RewardsEarnHistory
  description: Rewards Earn History Details
paths:
  /cards/accounts/external/{externalAccountId}/rewards-earn/history:
    summary: Get Rewards Earn History Details
    description: Get Rewards Earn History Details
    get:
      tags:
      - RewardsEarnHistory
      summary: Get Rewards Earn History Details
      description: 'Retrieves a list of reward posted for a specific external account.


        **Query Parameters:**

        - `numberOfPastCycles`: Number of past cycles required


        **Response includes:**

        - List of Reward Earned'
      operationId: getRewardsEarnHistoryDetails
      parameters:
      - name: Correlation-ID
        in: header
        description: "Unique end-to-end trace ID. The initiating system (such as a Channel or \nBatch Job), must generate this unique ID, then this must be passed \nthrough the API call stack. This is required to maintain compliance with the current Barclays REST Standard."
        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: externalAccountId
        in: path
        description: A unique id (similar to UUID) created for each customer account
        required: true
        schema:
          type: string
          format: uuid
          example: 0dbcb7ee-6c59-483b-966a-44d11557665b
          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}$
        example: 0dbcb7ee-6c59-483b-966a-44d11557665b
      - name: numberOfPastCycles
        in: query
        description: Number of past billing cycles to retrieve (excluding current cycle). Maximum 24 cycles allowed.
        required: false
        schema:
          type: integer
          default: 24
          maximum: 24
          minimum: 0
        example: 24
      - name: Authorization
        in: header
        description: TIAA-US External token
        required: true
        deprecated: false
        schema:
          type: string
        example: Bearer <token>
      responses:
        '200':
          $ref: '#/components/responses/RewardEarnHistoryRes'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      deprecated: false
components:
  schemas:
    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
    RewardInformation:
      type: object
      properties:
        description:
          type: string
          description: Description of the reward
          example: All Off Partner Purchases
          maxLength: 255
          minLength: 0
          pattern: ^[a-zA-Z0-9\s\-.,&()'/]+$
        type:
          type: string
          description: Type of reward
          enum:
          - BASE_EARN
          - BONUS
          - ADJ
          example: BASE_EARN
        earnedAwardValue:
          type: number
          format: double
          description: Reward amount
          example: 10
          maximum: 10000000
          minimum: -10000000
      required:
      - description
      - earnedAwardValue
      - type
    RewardInformationSummaryResponse:
      type: object
      properties:
        statementDate:
          type: string
          format: date
          description: Statement date for the cycle
          example: '2025-11-01'
        isCurrent:
          type: boolean
          description: cycle type
          example: true
        totalEarnedAwardValue:
          type: number
          format: double
          description: Reward amount
          example: 10
          maximum: 10000000
          minimum: -10000000
        rewardInformationList:
          type: array
          description: summary of reward earned by award description
          items:
            $ref: '#/components/schemas/RewardInformation'
          maxItems: 200
          minItems: 0
      required:
      - isCurrent
      - rewardInformationList
      - statementDate
      - totalEarnedAwardValue
    ErrorType:
      type: object
      additionalProperties: true
      description: Message details - additional operation execution information.
      properties:
        id:
          type: string
          description: Generated message identifier for particular request, helping to locate server logs.
          example: 9709-4675-2456-7801
          maxLength: 50
          minLength: 1
          pattern: ^[a-zA-Z0-9\-]{1,50}$
        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}$
        meta:
          type: object
          additionalProperties: true
          description: Object containing non-standard meta-information about the error.
      required:
      - code
      - id
      - title
    RewardsEarnHistoryData:
      type: object
      deprecated: false
      properties:
        rewardCurrency:
          type: string
          description: Currency type for the reward
          example: cash rewards
          maxLength: 255
          minLength: 1
          pattern: ^[a-zA-Z0-9®™$\s_\-\.]+$
        rewardHistory:
          type: array
          description: List of reward earned by statementDate
          items:
            $ref: '#/components/schemas/RewardInformationSummaryResponse'
          maxItems: 100
          minItems: 0
      required:
      - rewardCurrency
      - rewardHistory
      nullable: false
    RewardsEarnHistoryResponse:
      type: object
      deprecated: false
      properties:
        data:
          $ref: '#/components/schemas/RewardsEarnHistoryData'
      required:
      - data
      nullable: false
  examples:
    example-error-429:
      value:
        errors:
        - id: 9709-4675-2456-7801
          code: TOO_MANY_REQUESTS
          title: Too many requests
    example-error-403:
      value:
        errors:
        - id: 9709-4675-2456-7801
          code: ACCESS_FORBIDDEN
          title: The user is not permitted to access the requested operation and it cannot be completed.
    rewards-earn-history:
      value:
        data:
          rewardCurrency: cash rewards
          rewardHistory:
          - statementDate: '2026-02-26'
            isCurrent: true
            totalEarnedAwardValue: 125.5
            rewardInformationList:
            - description: Samsung On partner
              type: BASE_EARN
              earnedAwardValue: 25.5
            - description: Welcome Bonus
              type: BONUS
              earnedAwardValue: 100
          - statementDate: '2026-01-26'
            isCurrent: false
            totalEarnedAwardValue: 50
            rewardInformationList:
            - description: Samsung On partner
              type: BASE_EARN
              earnedAwardValue: 20
            - description: Samsung Off partner
              type: BASE_EARN
              earnedAwardValue: 30
          - statementDate: '2026-12-26'
            isCurrent: false
            totalEarnedAwardValue: 0
            rewardInformationList: []
          - statementDate: '2025-11-26'
            isCurrent: false
            totalEarnedAwardValue: 40
            rewardInformationList:
            - description: Samsung On partner
              type: BASE_EARN
              earnedAwardValue: 20
            - description: Adhoc Rewards
              type: ADJ
              earnedAwardValue: 20
    example-error-500:
      value:
        errors:
        - id: 9709-4675-2456-7801
          code: INTERNAL_SERVER_ERROR
          title: The request failed due to an internal error.
    example-error-401:
      value:
        errors:
        - id: 9709-4675-2456-7801
          code: AUTHENTICATION_ERROR
          title: The user could not be authenticated for this request.
    example-error-503:
      value:
        errors:
        - id: 9709-4675-2456-7801
          code: SERVICE_UNAVAILABLE
          title: The server is currently unavailable
    example-error-404:
      value:
        errors:
        - id: 9709-4675-2456-7801
          code: RESOURCE_NOT_FOUND
          title: The requested operation failed because a resource associated with the request could not be found.
    example-error-400-bad-request:
      value:
        errors:
        - id: 9709-4675-2456-7801
          code: BAD_REQUEST
          title: The request is invalid or not properly formed.
  responses:
    BadRequest:
      description: "The request could not be understood by the server due to malformed \nsyntax. The client SHOULD NOT repeat the request without \nmodifications.\n"
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            example-error-400-bad-request:
              $ref: '#/components/examples/example-error-400-bad-request'
    InternalServerError:
      description: "Server encountered an error processing request. This should not \nhappen normally, but it is a generic error message, given when \nno more specific message is suitable.\n"
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            example-error-500:
              $ref: '#/components/examples/example-error-500'
    ServiceUnavailable:
      description: "temporary maintenance of service, try again later. The implication \nis that this is a temporary condition which will be alleviated \nafter some delay. If known, the length of the delay will be \nindicated in a Retry-After header. If no Retry-After is given, \nthe client SHOULD handle the response as it would for a 500 response. \nNote: The existence of the 503 status code does not imply that a \nserver will use it when becoming overloaded. Servers may simply \nrefuse the connection.\n"
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            example-error-503:
              $ref: '#/components/examples/example-error-503'
    NotFound:
      description: "Server has not found a resource with that URI. This may be \ntemporary and permanent condition. This status code is \ncommonly used when the server does not wish to reveal \nexactly why the request has been refused, or when no other \nresponse is applicable.\n"
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            example-error-404:
              $ref: '#/components/examples/example-error-404'
    RewardEarnHistoryRes:
      description: Successful response.
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RewardsEarnHistoryResponse'
          examples:
            multipleRewards:
              summary: Multiple reward earned
              $ref: '#/components/examples/rewards-earn-history'
    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:
            example-error-403:
              $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:
            example-error-401:
              $ref: '#/components/examples/example-error-401'
    TooManyRequests:
      description: "When a server is under attack or just receiving a very \nlarge number of requests from a single party, responding \nto each with a 429 status code will consume resources. \nTherefore, servers may drop connections or take other steps\ninstead of responding with the 429 status code, when limiting\nresource usage.\n"
      headers:
        Cache-Control:
          $ref: '#/components/headers/Cache-Control'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponseType'
          examples:
            example-error-429:
              $ref: '#/components/examples/example-error-429'
  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