For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Logo
Get supportSee a Demo
HomeAPI ReferenceSDKs
HomeAPI ReferenceSDKs
    • SDKs
    • WebView
  • API Reference
      • POSTCreate Incoming Transactions
      • POSTCreate Bulk Transactions Upload URL
      • POSTCreate Audits
      • GETGet Earned Rewards
Get supportSee a Demo
API ReferenceTransactions

Get Earned Rewards

GET
/v2/issuers/:organizationId/users/:userId/earned-rewards
GET
/v2/issuers/:organizationId/users/:userId/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
1{
2  "data": [
3    {
4      "type": "approvedTransaction",
5      "attributes": {
6        "status": "APPROVED",
7        "transactionId": "TXN-20241001-F21-127964",
8        "transactionAmountInCents": 12796,
9        "transactionTimestamp": "2024-10-01T01:36:57Z"
10      },
11      "id": "fcabf024-3870-41f3-9fbd-b43ea85a3d19",
12      "relationships": {
13        "user": {
14          "data": {
15            "type": "user",
16            "id": "8c52423a-c319-44ee-8fc7-508e97b43892"
17          }
18        },
19        "merchant": {
20          "data": {
21            "type": "merchant",
22            "id": "633ed2ab30dcb60009dd5699"
23          }
24        },
25        "offer": {
26          "data": {
27            "type": "offer",
28            "id": "OFF-F21-INSTORE-2024Q4-001"
29          }
30        }
31      }
32    },
33    {
34      "type": "rewardedTransaction",
35      "attributes": {
36        "status": "SETTLED",
37        "transactionId": "TXN-20240928-TGT-778813",
38        "transactionAmountInCents": 8800,
39        "transactionTimestamp": "2024-09-28T14:11:22Z",
40        "paidToIssuer": "PAID_IN_FULL",
41        "commissionEarned": {
42          "user": {
43            "type": "cents",
44            "value": 220
45          }
46        },
47        "payoutTimestamp": "2024-09-29T10:15:00Z"
48      },
49      "id": "7bcbdb95-f3a5-4f56-a9be-4c25f313eb0a",
50      "relationships": {
51        "user": {
52          "data": {
53            "type": "user",
54            "id": "8c52423a-c319-44ee-8fc7-508e97b43892"
55          }
56        },
57        "merchant": {
58          "data": {
59            "type": "merchant",
60            "id": "5f3e2d1c40abc50008cc4821"
61          }
62        },
63        "offer": {
64          "data": {
65            "type": "offer",
66            "id": "OFF-TGT-ONLINE-2024Q4-002"
67          }
68        }
69      }
70    }
71  ],
72  "links": {
73    "self": "/v2/issuers/org-123/users/user-456/earned-rewards?page[size]=10",
74    "next": "/v2/issuers/org-123/users/user-456/earned-rewards?page[size]=10&page[after]=eyJpZCI6ImZjYWJmMDI0LTM4NzAtNDFmMy05ZmJkLWI0M2VhODVhM2QxOSIsInRzIjoiMjAyNC0xMC0wMVQwMTozNjo1N1oifQ=="
75  },
76  "meta": {
77    "lifetimeRewardsInCents": 540
78  },
79  "included": [
80    {
81      "type": "merchant",
82      "attributes": {
83        "name": "Forever 21",
84        "assets": [
85          {
86            "type": "IMG_VIEW",
87            "url": "https://attribution.getkard.com/public/logos/forever21.jpg?subtype=IMG_VIEW&offerId=OFF-F21-INSTORE-2024Q4-001&token=signed-token",
88            "alt": "Forever 21 Logo Image"
89          },
90          {
91            "type": "BANNER_VIEW",
92            "url": "https://attribution.getkard.com/public/banners/forever21.jpg?subtype=BANNER_VIEW&offerId=OFF-F21-INSTORE-2024Q4-001&token=signed-token",
93            "alt": "Forever 21 Banner Image"
94          }
95        ]
96      },
97      "id": "633ed2ab30dcb60009dd5699"
98    },
99    {
100      "type": "merchant",
101      "attributes": {
102        "name": "Target",
103        "assets": [
104          {
105            "type": "IMG_VIEW",
106            "url": "https://attribution.getkard.com/public/logos/target.jpg?subtype=IMG_VIEW&offerId=OFF-TGT-ONLINE-2024Q4-002&token=signed-token",
107            "alt": "Target Logo Image"
108          }
109        ]
110      },
111      "id": "5f3e2d1c40abc50008cc4821"
112    },
113    {
114      "type": "offer",
115      "attributes": {
116        "purchaseChannel": [
117          "INSTORE"
118        ]
119      },
120      "id": "OFF-F21-INSTORE-2024Q4-001"
121    },
122    {
123      "type": "offer",
124      "attributes": {
125        "purchaseChannel": [
126          "ONLINE"
127        ]
128      },
129      "id": "OFF-TGT-ONLINE-2024Q4-002"
130    }
131  ]
132}
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[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.
Was this page helpful?
Previous

Create Upload

Next
Built with

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[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.
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
Related links to the API call
metaobject
Additional metadata for the earned rewards response.
includedlist of objects
Additional resources referenced in the response

Errors

400
Invalid Request
401
Unauthorized Error
404
Does Not Exist Error
500
Internal Server Error

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.