> This page is for version 2024-10-01 (default). > For other versions, use one of these documentation indexes: > - 2024-10-01 (default): https://docs.getkard.com/2024-10-01/llms.txt > - Legacy: https://docs.getkard.com/legacy/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.getkard.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getkard.com/_mcp/server. # Get Earned Rewards GET https://rewards-api.getkard.com/v2/issuers/{organizationId}/users/{userId}/earned-rewards 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. Reference: https://docs.getkard.com/api/transactions/get-earned-rewards ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Servers - `https://rewards-api.getkard.com` (Production, default) - `https://test-rewards-api.getkard.com` (Sandbox) ## Request ### Path parameters - `organizationId` (string, required) — Your issuer organization ID, provided by Kard - `userId` (string, required) — The ID of the user as defined on the issuers system ### Query parameters - `page[after]` (string, optional) — Cursor for next page (base64-encoded timestamp + transaction ID) - `page[before]` (string, optional) — Cursor for previous page (base64-encoded timestamp + transaction ID) - `page[size]` (integer, optional) — Number of results per page - `filter[status]` (enum, optional) — 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: `APPROVED`, `SETTLED` - `filter[paidInFullOnly]` (boolean, optional) — 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]` (enum, optional) — 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: `12M`, `6M`, `3M`, `YTD` - `include` (string, optional) — Comma-separated list of related resources to include in the response. Supported values are `merchant` and `offer`. ## Response ### 200 - `data` (list of RewardedTransactionUnion, required) - `links` (Links, required) — Related links to the API call - `meta` (GetEarnedRewardsMeta, required) — Additional metadata for the earned rewards response. - `included` (list of TransactionIncludedResource, optional) — Additional resources referenced in the response ## Errors ### 400 Invalid Request - `errors` (list of ErrorObject, required) ### 401 Unauthorized Error - `errors` (list of ErrorObject, required) ### 404 Does Not Exist Error - `errors` (list of ErrorObject, required) ### 500 Internal Server Error - `errors` (list of ErrorObject, required) ## Types ### RewardedTransactionUnion - `type`: `rewardedTransaction` - `attributes` (RewardedTransactionAttributes, required) - `id` (string, required) — Unique transaction identifier - `relationships` (RewardedTransactionRelationships, required) - `type`: `approvedTransaction` - `attributes` (ApprovedTransactionAttributes, required) - `id` (string, required) — Unique transaction identifier - `relationships` (RewardedTransactionRelationships, required) ### Links Related links to the API call - `self` (string, required) - `prev` (string, optional) - `next` (string, optional) ### GetEarnedRewardsMeta - `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`). ### TransactionIncludedResource - `type`: `merchant` - `attributes` (TransactionMerchantAttributes, required) — Merchant attributes - `id` (string, required) — Merchant identifier - `type`: `offer` - `attributes` (TransactionOfferAttributes, required) — Offer attributes - `id` (string, required) — Offer identifier ### ErrorObject - `status` (string, required) — Status code returned from the request - `title` (string, required) — Name of error - `detail` (string, required) — Description of the specific occurance of the error - `source` (ErrorSource, optional) — An object containing a reference to the primary source of the error - `id` (string, optional) — The id of the resource which caused the error. Always returned for multi-status errors. ### RewardedTransactionAttributes - `status` ("SETTLED", required) — Status of the rewarded transaction - `transactionId` (string, required) — The transaction identifier - `transactionAmountInCents` (integer, required) — Transaction amount in cents - `transactionTimestamp` (datetime, required) — Timestamp of the transaction in ISO 8601 format - `paidToIssuer` (enum, required) — Payment status to issuer - Allowed values: `UNPAID`, `PAID_IN_FULL` - `commissionEarned` (CommissionEarnedDetails, required) - `payoutTimestamp` (datetime, optional) — Timestamp representing the month when the transaction has been paid out to issuer - `components` (OfferComponents, optional) — UI component data for the reward, built from the offer state persisted on the matched transaction (e.g. a progress bar for progressive and punch-card offers). Omitted when the reward carries no persisted state. ### RewardedTransactionRelationships - `user` (RelationshipSingle, required) - `merchant` (RelationshipSingle, required) - `offer` (RelationshipSingle, required) ### ApprovedTransactionAttributes - `status` ("APPROVED", required) — Status of the approved transaction - `transactionId` (string, required) — The transaction identifier - `transactionAmountInCents` (integer, required) — Transaction amount in cents - `transactionTimestamp` (datetime, required) — Timestamp of the transaction in ISO 8601 format ### TransactionMerchantAttributes - `name` (string, required) — Merchant name - `assets` (list of MerchantAsset, optional) — 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. ### TransactionOfferAttributes - `purchaseChannel` (list of string, required) — Purchase channels ### ErrorSource - `pointer` (string, optional) — A JSON pointer to the value in the request document that caused the error - `parameter` (string, optional) — A string indicating which URI query parameter caused the error - `header` (string, optional) — A string indicating the name of a single request header which caused the error ### CommissionEarnedDetails - `user` (CommissionValue, required) ### OfferComponents UI component data for rendering offer details - `shortDescription` (string, optional) — Short description for the offer - `longDescription` (string, optional) — Long description for the offer - `baseReward` (string, optional) — Formatted reward string - `boostedReward` (string, optional) — Formatted boosted reward string - `cta` (CtaComponent, optional) — Call-to-action button component - `tags` (list of string, optional) — Tags for the offer - `detailTags` (list of string, optional) — Detail tags for the offer - `logoFlare` (LogoFlare, optional) — Logo flare configuration for the offer - `progressBar` (ProgressBar, optional) — Progress bar component for tracking offer redemptions ### RelationshipSingle - `data` (RelationshipData, required) ### MerchantAsset - `type` (enum, required) — The type of asset being tracked. - Allowed values: `IMG_VIEW`, `BANNER_VIEW` - `url` (string, required) — Attribution-signed URL for loading the asset. - `alt` (string, optional) — Alt text describing the asset for accessibility. ### CommissionValue - `type` (enum, required) — The type of commission - Allowed values: `cents` - `value` (integer, required) — The commission value. ### CtaComponent Call-to-action button component for offers - `buttonText` (string, required) — Text to display on the button - `buttonStyle` (enum, required) — Style of the button - Allowed values: `PRIMARY`, `SECONDARY`, `DISABLED` - `action` (CtaAction, optional) — Action to perform when the button is clicked - `startIcon` (string, optional) — Icon identifier to display on the button ### LogoFlare Logo flare configuration for offer display - `borderColor` (enum, required) — Border color style for the logo flare - Allowed values: `PRIMARY`, `SECONDARY` - `badge` (LogoFlareBadge, optional) — Optional badge to display on the logo ### ProgressBar Progress bar component for tracking offer redemption progress - `total` (integer, required) — Total number of redemptions allowed - `currentProgress` (integer, required) — Number of redemptions the user has completed - `labels` (ProgressBarLabels, required) — Labels to render around the progress bar in different layouts - `label` (string, required, deprecated) — Formatted label for the progress bar - `segmented` (boolean, required, deprecated) — Whether the progress bar should be displayed as segmented - `segments` (ProgressBarSegments, optional) — Segment configuration for the progress bar in different layouts ### RelationshipData - `type` (string, required) — Type of document returned - `id` (string, required) — The ID of the related resource ### CtaAction Action configuration for CTA button - `url` (string, required) — URL endpoint to call when button is clicked - `method` (string, required) — HTTP method to use (e.g., POST) ### LogoFlareBadge Badge configuration for logo flare - `icon` (string, required) — Icon identifier for the badge - `position` (enum, required) — Position of the badge on the logo - Allowed values: `TOP_RIGHT`, `TOP_LEFT`, `BOTTOM_RIGHT`, `BOTTOM_LEFT` ### ProgressBarLabels Labels to render around the progress bar in different layouts - `default` (ProgressBarLabelPair, required) — Label configuration for the default view - `details` (ProgressBarLabelPair, optional) — Label configuration for the details view ### ProgressBarSegments Segment configuration for the progress bar in different layouts - `default` (ProgressBarSegment, required) — Segment configuration for the default view - `progress` (list of ProgressBarSegmentProgress, required) — Per-segment fill state: one entry per segment node, index-aligned with the nodes (length equals the progress bar total). Reached nodes report 1 of 1 and not-yet-reached nodes 0 of 1; for a punch-card offer the in-progress node reports qualifying-purchase progress toward the next reward (Q mod N of N). - `details` (ProgressBarSegment, optional) — Segment configuration for the details view ### ProgressBarLabelPair Left and right label configuration for a specific layout - `left` (string, optional) — Text content for the left label - `right` (string, optional) — Text content for the right label ### ProgressBarSegment Segment configuration for a specific layout - `position` (enum, required) — Position of the segment within the layout - Allowed values: `LEFT`, `RIGHT`, `FULL_WIDTH` - `icon` (string, optional) — SVG icon to use for each segment - `separator` (enum, optional) — Separator style to render between segment nodes - Allowed values: `LINE` - `labels` (list of ProgressBarSegmentLabel, optional) — Label configuration for each node in the segment - `selection` (enum, optional) — Which segment nodes the UI should render as selected based on currentProgress - Allowed values: `CURRENT`, `CURRENT_AND_BELOW` ### ProgressBarSegmentProgress Fill state of a single segment node, expressed as completed of total. - `completed` (integer, required) — Units completed within the current segment. - `total` (integer, required) — Total units required to complete the current segment. ### ProgressBarSegmentLabel Label configuration for a single node within a segment - `title` (string, required) — Title text for the segment node - `description` (string, required) — Description text for the segment node ## Examples **Response** ```json { "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" } ] } ``` **SDK Code** ```python Get Earned Rewards import requests url = "https://rewards-api.getkard.com/v2/issuers/org-123/users/user-456/earned-rewards" querystring = {"page[size]":"10","filter[status]":"APPROVED","include":"merchant,offer"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript Get Earned Rewards const url = 'https://rewards-api.getkard.com/v2/issuers/org-123/users/user-456/earned-rewards?page%5Bsize%5D=10&filter%5Bstatus%5D=APPROVED&include=merchant%2Coffer'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Get Earned Rewards package main import ( "fmt" "net/http" "io" ) func main() { url := "https://rewards-api.getkard.com/v2/issuers/org-123/users/user-456/earned-rewards?page%5Bsize%5D=10&filter%5Bstatus%5D=APPROVED&include=merchant%2Coffer" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Get Earned Rewards require 'uri' require 'net/http' url = URI("https://rewards-api.getkard.com/v2/issuers/org-123/users/user-456/earned-rewards?page%5Bsize%5D=10&filter%5Bstatus%5D=APPROVED&include=merchant%2Coffer") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java Get Earned Rewards import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://rewards-api.getkard.com/v2/issuers/org-123/users/user-456/earned-rewards?page%5Bsize%5D=10&filter%5Bstatus%5D=APPROVED&include=merchant%2Coffer") .header("Authorization", "Bearer ") .asString(); ``` ```php Get Earned Rewards request('GET', 'https://rewards-api.getkard.com/v2/issuers/org-123/users/user-456/earned-rewards?page%5Bsize%5D=10&filter%5Bstatus%5D=APPROVED&include=merchant%2Coffer', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp Get Earned Rewards using RestSharp; var client = new RestClient("https://rewards-api.getkard.com/v2/issuers/org-123/users/user-456/earned-rewards?page%5Bsize%5D=10&filter%5Bstatus%5D=APPROVED&include=merchant%2Coffer"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift Get Earned Rewards import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/v2/issuers/org-123/users/user-456/earned-rewards?page%5Bsize%5D=10&filter%5Bstatus%5D=APPROVED&include=merchant%2Coffer")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```