Get Earned Rewards

curl -G https://rewards-api.getkard.com/v2/issuers/org-123/users/user-456/earned-rewards \
     -H "Authorization: Bearer <token>" \
     -d "page[size]=10" \
     -d "filter[status]=APPROVED" \
     --data-urlencode include=merchant,offer

{
  "data": [
    {
      "type": "approvedTransaction",
      "attributes": {
        "status": "APPROVED",
        "transactionId": "TXN-20241001-F21-127964",
        "transactionAmountInCents": 12796,
        "transactionTimestamp": "2024-10-01T01:36:57Z"
      },
      "id": "fcabf024-3870-41f3-9fbd-b43ea85a3d19",
      "relationships": {
        "user": {
          "data": {
            "type": "user",
            "id": "8c52423a-c319-44ee-8fc7-508e97b43892"
          }
        },
        "merchant": {
          "data": {
            "type": "merchant",
            "id": "633ed2ab30dcb60009dd5699"
          }
        },
        "offer": {
          "data": {
            "type": "offer",
            "id": "OFF-F21-INSTORE-2024Q4-001"
          }
        }
      }
    },
    {
      "type": "rewardedTransaction",
      "attributes": {
        "status": "SETTLED",
        "transactionId": "TXN-20240928-TGT-778813",
        "transactionAmountInCents": 8800,
        "transactionTimestamp": "2024-09-28T14:11:22Z",
        "paidToIssuer": "PAID_IN_FULL",
        "commissionEarned": {
          "user": {
            "type": "cents",
            "value": 220
          }
        },
        "payoutTimestamp": "2024-09-29T10:15:00Z"
      },
      "id": "7bcbdb95-f3a5-4f56-a9be-4c25f313eb0a",
      "relationships": {
        "user": {
          "data": {
            "type": "user",
            "id": "8c52423a-c319-44ee-8fc7-508e97b43892"
          }
        },
        "merchant": {
          "data": {
            "type": "merchant",
            "id": "5f3e2d1c40abc50008cc4821"
          }
        },
        "offer": {
          "data": {
            "type": "offer",
            "id": "OFF-TGT-ONLINE-2024Q4-002"
          }
        }
      }
    }
  ],
  "links": {
    "self": "/v2/issuers/org-123/users/user-456/earned-rewards?page[size]=10",
    "next": "/v2/issuers/org-123/users/user-456/earned-rewards?page[size]=10&page[after]=eyJpZCI6ImZjYWJmMDI0LTM4NzAtNDFmMy05ZmJkLWI0M2VhODVhM2QxOSIsInRzIjoiMjAyNC0xMC0wMVQwMTozNjo1N1oifQ=="
  },
  "meta": {
    "lifetimeRewardsInCents": 540
  },
  "included": [
    {
      "type": "merchant",
      "attributes": {
        "name": "Forever 21",
        "assets": [
          {
            "type": "IMG_VIEW",
            "url": "https://attribution.getkard.com/public/logos/forever21.jpg?subtype=IMG_VIEW&offerId=OFF-F21-INSTORE-2024Q4-001&token=signed-token",
            "alt": "Forever 21 Logo Image"
          },
          {
            "type": "BANNER_VIEW",
            "url": "https://attribution.getkard.com/public/banners/forever21.jpg?subtype=BANNER_VIEW&offerId=OFF-F21-INSTORE-2024Q4-001&token=signed-token",
            "alt": "Forever 21 Banner Image"
          }
        ]
      },
      "id": "633ed2ab30dcb60009dd5699"
    },
    {
      "type": "merchant",
      "attributes": {
        "name": "Target",
        "assets": [
          {
            "type": "IMG_VIEW",
            "url": "https://attribution.getkard.com/public/logos/target.jpg?subtype=IMG_VIEW&offerId=OFF-TGT-ONLINE-2024Q4-002&token=signed-token",
            "alt": "Target Logo Image"
          }
        ]
      },
      "id": "5f3e2d1c40abc50008cc4821"
    },
    {
      "type": "offer",
      "attributes": {
        "purchaseChannel": [
          "INSTORE"
        ]
      },
      "id": "OFF-F21-INSTORE-2024Q4-001"
    },
    {
      "type": "offer",
      "attributes": {
        "purchaseChannel": [
          "ONLINE"
        ]
      },
      "id": "OFF-TGT-ONLINE-2024Q4-002"
    }
  ]
}

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).

Required scopes: transaction:read

Query Limit: Maximum of 12 months of transaction data can be queried.

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`). Required scopes: `transaction:read` Query Limit: Maximum of 12 months of transaction data can be queried.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

organizationIdstringRequired

Your issuer organization ID, provided by Kard

userIdstringRequired

The ID of the user as defined on the issuers system

Query parameters

page[after]stringOptional

Cursor for next page (base64-encoded timestamp + transaction ID)

page[before]stringOptional

Cursor for previous page (base64-encoded timestamp + transaction ID)

page[size]integerOptional

Number of results per page

filter[status]enumOptional

Filter by transaction status. Supported values are APPROVED and SETTLED. Defaults to SETTLED when omitted. When APPROVED is specified, only approved transactions that do not yet have a corresponding settled transaction are returned.

Allowed values:

filter[paidInFullOnly]booleanOptional

When true, only return transactions that have been paid in full to the issuer (paidToIssuer is PAID_IN_FULL). By default (false), any matched transaction is returned regardless of payment status. This also controls whether unpaid transactions contribute to lifetimeRewardsInCents. Has no effect on APPROVED transactions, which are always returned when requested.

When `true`, only return transactions that have been paid in full to the issuer (`paidToIssuer` is `PAID_IN_FULL`). By default (`false`), any matched transaction is returned regardless of payment status. This also controls whether unpaid transactions contribute to `lifetimeRewardsInCents`. Has no effect on `APPROVED` transactions, which are always returned when requested.

filter[range]enumOptional

Time window for the returned transactions, ending now. Supported values are 12M, 6M, 3M, and YTD (since January 1 of the current year). Defaults to 12M when omitted. Also scopes lifetimeRewardsInCents, so the meta total always matches the returned rows.

Allowed values:

includestringOptional

Comma-separated list of related resources to include in the response. Supported values are merchant and offer.

Response

This endpoint returns an object.

datalist of objects

linksobject

Errors

400

Invalid Request

401

Unauthorized Error

404

Does Not Exist Error

500

Internal Server Error