---
title: "Get Earned Rewards"
method: GET
path: "/v2/issuers/{organizationId}/users/{userId}/earned-rewards"
tags: ["transactions"]
---

# Get Earned Rewards

`GET /v2/issuers/{organizationId}/users/{userId}/earned-rewards`

## Request

- Base URL: `https://rewards-api.getkard.com`
- URL: `https://rewards-api.getkard.com/v2/issuers/{organizationId}/users/{userId}/earned-rewards`
- Auth: HTTP bearer

Retrieve rewarded transaction history for a specific user. By default this returns only SETTLED transactions within the last 12 months regardless of payment status. Pass `filter[range]` to narrow the window to the last 6 months (`6M`), last 3 months (`3M`), or year to date (`YTD`). Pass `filter[paidInFullOnly]=true` to restrict the response to matched transactions that have been paid in full to the issuer (`paidToIssuer` is `PAID_IN_FULL`).
<br/>
<b>Required scopes:</b> `transaction:read`
<br/>
<b>Query Limit:</b> Maximum of 12 months of transaction data can be queried.

## Path parameters

- `organizationId` string, required: Your issuer organization ID, provided by Kard
- `userId` string, required

## Query parameters

- `page[after]` string
- `page[before]` string
- `page[size]` integer
- `filter[status]` 'APPROVED' | 'SETTLED'
- `filter[paidInFullOnly]` boolean
- `filter[range]` '12M' | '6M' | '3M' | 'YTD': Time window for earned rewards queries, ending now. `YTD` starts at January 1 of the current year (UTC).
- `include` string

## Response `200`

Response with status 200

- TransactionsGetEarnedRewardsResponse
  - `data` TransactionsRewardedTransactionUnion[], required
    - union
      - object
        - `type` 'rewardedTransaction', required: Discriminator value: rewardedTransaction
        - `id` string, required: Unique transaction identifier
        - `attributes` TransactionsRewardedTransactionAttributes, required
          - `status` 'SETTLED', required: Status of the rewarded transaction
          - `transactionId` string, required: The transaction identifier
          - `transactionAmountInCents` integer, required: Transaction amount in cents
          - `transactionTimestamp` string, date-time, required: Timestamp of the transaction in ISO 8601 format
          - `paidToIssuer` 'UNPAID' | 'PAID_IN_FULL', required
          - `commissionEarned` TransactionsCommissionEarnedDetails, required
            - `user` CommonsCommissionValue, required
              - …
          - `payoutTimestamp` string, date-time: Timestamp representing the month when the transaction has been paid out to issuer
          - `components` CommonsOfferComponents: UI component data for rendering offer details
            - `shortDescription` string: Short description for the offer
            - `longDescription` string: Long description for the offer
            - `baseReward` string: Formatted reward string
            - `boostedReward` string: Formatted boosted reward string
            - `cta` CommonsCtaComponent: Call-to-action button component for offers
              - …
            - `tags` string[]: Tags for the offer
            - `detailTags` string[]: Detail tags for the offer
            - `logoFlare` CommonsLogoFlare: Logo flare configuration for offer display
              - …
            - `progressBar` CommonsProgressBar: Progress bar component for tracking offer redemption progress
              - …
        - `relationships` TransactionsRewardedTransactionRelationships, required
          - `user` CommonsRelationshipSingle, required
            - `data` CommonsRelationshipData, required
              - …
          - `merchant` CommonsRelationshipSingle, required
            - `data` CommonsRelationshipData, required
              - …
          - `offer` CommonsRelationshipSingle, required
            - `data` CommonsRelationshipData, required
              - …
      - object
        - `type` 'approvedTransaction', required: Discriminator value: approvedTransaction
        - `id` string, required: Unique transaction identifier
        - `attributes` TransactionsApprovedTransactionAttributes, required
          - `status` 'APPROVED', required: Status of the approved transaction
          - `transactionId` string, required: The transaction identifier
          - `transactionAmountInCents` integer, required: Transaction amount in cents
          - `transactionTimestamp` string, date-time, required: Timestamp of the transaction in ISO 8601 format
        - `relationships` TransactionsRewardedTransactionRelationships, required
          - `user` CommonsRelationshipSingle, required
            - `data` CommonsRelationshipData, required
              - …
          - `merchant` CommonsRelationshipSingle, required
            - `data` CommonsRelationshipData, required
              - …
          - `offer` CommonsRelationshipSingle, required
            - `data` CommonsRelationshipData, required
              - …
  - `links` CommonsLinks, required: Related links to the API call
    - `self` string, required
    - `prev` string
    - `next` string
  - `meta` TransactionsGetEarnedRewardsMeta, required
    - `lifetimeRewardsInCents` integer, required: Lifetime rewards earned by the user across matched transactions in cents, within the window selected by `filter[range]` (default last 12 months). By default all matched transactions are included regardless of payment status; pass `filter[paidInFullOnly]=true` to restrict the total to transactions paid in full to the issuer (`paidToIssuer` is `PAID_IN_FULL`).
  - `included` TransactionsTransactionIncludedResource[]: Additional resources referenced in the response
    - union
      - object
        - `type` 'merchant', required: Discriminator value: merchant
        - `id` string, required: Merchant identifier
        - `attributes` TransactionsTransactionMerchantAttributes, required
          - `name` string, required: Merchant name
          - `assets` TransactionsMerchantAsset[]: Tracked asset images for the merchant (logo, banner, etc.). Each asset URL is signed for attribution tracking and should be loaded as-is by the client.
            - `type` 'IMG_VIEW' | 'BANNER_VIEW', required
            - `url` string, required: Attribution-signed URL for loading the asset.
            - `alt` string: Alt text describing the asset for accessibility.
      - object
        - `type` 'offer', required: Discriminator value: offer
        - `id` string, required: Offer identifier
        - `attributes` TransactionsTransactionOfferAttributes, required
          - `purchaseChannel` string[], required: Purchase channels

## Other responses

- `400`: Error response with status 400
- `401`: Error response with status 401
- `404`: Error response with status 404
- `429`: The issuer's traffic grew faster than its allowed rate, or the endpoint's own limit was reached. If the response includes a `Retry-After` header, wait that many seconds before retrying. See [Rate Limits](/2024-10-01/api/integration-guides/rate-limits).
- `500`: Error response with status 500

## Changes

- **2026-10-22** `4e87fc8b018b`: 1 info
  - added the non-success response with the status `429`

[Operation history](https://skmtc.dev/getkard/apis/getkard-2/changes/v2/issuers/:organizationId/users/:userId/earned-rewards/get.md)

---

[API](https://skmtc.dev/getkard/apis/getkard-2.md) - [All operations](https://skmtc.dev/getkard/apis/getkard-2/llms.txt) - [OpenAPI document](https://skmtc.dev/getkard/apis/getkard-2/revisions/bd47764afa21?raw)