> 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 Offers By User GET https://rewards-api.getkard.com/v2/issuers/{organizationId}/users/{userId}/offers Retrieve national brand offers that a specified user is eligible for. Call this endpoint to build out your [targeted offers UX experience](/2024-10-01/api/getting-started#b-discover-a-lapsed-customer-clo). Local offers details can be found by calling the [Get Eligible Locations](/2024-10-01/api/rewards/locations). Required scopes: `rewards:read` Reference: https://docs.getkard.com/api/rewards/offers ## 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[size]` (integer, optional) - `page[after]` (string, optional) - `page[before]` (string, optional) - `filter[search]` (string, optional) — Case-insensitive substring search. Returns offers whose offer name or category name contains the search string. - `filter[purchaseChannel]` (list of enum, optional) - Allowed values: `INSTORE`, `ONLINE` - `filter[category]` (enum, optional) — Category of merchant. Please use URL Encode for non single word categories. (Food & Beverage should be Food%20%26%20Beverage) - Allowed values: `Arts & Entertainment`, `Baby, Kids & Toys`, `Books & Digital Media`, `Clothing, Shoes & Accessories`, `Computers, Electronics & Software`, `Convenience`, `Gas`, `Department Stores`, `Food & Beverage`, `Health & Beauty`, `Home & Garden`, `Miscellaneous`, `Occasions & Gifts`, `Pets`, `Sports & Outdoors`, `Supplies & Services`, `Travel` - `filter[isTargeted]` (boolean, optional) - `sort` (enum, optional) — If provided, response will be sorted by the specified fields - Allowed values: `startDate`, `-startDate`, `expirationDate`, `-expirationDate`, `name`, `-name` - `include` (string, optional) — CSV list of included resources in the response (e.g "categories"). Allowed value is `categories`. - `supportedComponents` (enum, optional) — UI component types to include in the response. - Allowed values: `shortDescription`, `longDescription`, `baseReward`, `boostedReward`, `cta`, `tags`, `detailTags`, `logoFlare`, `progressBar` ## Response ### 200 - `data` (list of OfferDataUnion, required) - `links` (Links, required) — Related links to the API call - `included` (list of EligibilityOfferIncluded, optional) - `meta` (OffersMeta, optional) — Metadata about the full result set across all pages ## Errors ### 500 Internal Server Error - `errors` (list of ErrorObject, required) ### 400 Invalid Request - `errors` (list of ErrorObject, required) ### 404 Does Not Exist Error - `errors` (list of ErrorObject, required) ### 401 Unauthorized Error - `errors` (list of ErrorObject, required) ## Types ### OfferDataUnion - `type`: `standardOffer` - `attributes` (StandardOfferFields, required) - `id` (string, required) — Offer ID in Kard's system - `relationships` (EligibilityOfferRelationship, optional) ### Links Related links to the API call - `self` (string, required) - `prev` (string, optional) - `next` (string, optional) ### EligibilityOfferIncluded ### OffersMeta Metadata about the full result set across all pages - `availableCategories` (list of CategoryIncluded, optional) — All distinct categories available across the entire filtered result set, not just the current page - `placementName` (string, optional) — Display name of the placement, resolved server-side from its id. Populated only on the Get Placement Content endpoint; absent on the Get Offers By User endpoint. ### 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. ### StandardOfferFields - `assets` (list of Asset, required) — Assets associated with offer - `expirationDate` (datetime, required) — Expiration date of offer if applicable (UTC) - `isTargeted` (boolean, required) — True returns only targeted offers, false returns only non-targeted offers - `name` (string, required) — Name of offer - `purchaseChannel` (list of enum, required) - Allowed values: `INSTORE`, `ONLINE` - `startDate` (datetime, required) — Beginning date of offer (UTC) - `terms` (string, required) — Terms and conditions on offer - `userReward` (Commission, required) - `components` (OfferComponents, optional) — UI component data for the offer, returned when supportedComponents query parameter is provided - `description` (string, optional) — Description of the offer - `maxRedemptions` (integer, optional) — Maximum times cardholder can redeem offer, if applicable - `maxRewardAmount` (Amount, optional) — Maximum Reward Amount, if available on offer - `maxTransactionAmount` (Amount, optional) — Maximum Transaction Amount allowed to redeem offer, if available on offer - `minRewardAmount` (Amount, optional) — Minimum Reward Amount, if available on offer - `minTransactionAmount` (Amount, optional) — Minimum Transaction Amount required to redeem offer, if available on offer - `websiteUrl` (string, optional) — URL to the website of the offer provider ### EligibilityOfferRelationship ### CategoryIncluded - `attributes` (CategoryFields, required) - `id` (string, required) — id of the category - `type` ("category", required) ### 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 ### Asset - `type` (string, required) — What the asset shows. `IMG_VIEW` is the merchant logo, `BANNER_VIEW` a promotional banner, and `LOCATION_IMG_VIEW` a photo of the location. New values may be added over time. - `url` (string, required) — URL of the asset containing an attribution token - `alt` (string, required) — Alt text of the asset ### Commission - `type` (enum, required) — Type of commission on offer (% or a flat $) - Allowed values: `FLAT`, `PERCENT` - `value` (double, 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 ### Amount - `type` (enum, required) - Allowed values: `CENTS` - `value` (integer, required) ### CategoryRelationshipObject - `category` (CategoryRelationship, required) ### CategoryFields - `name` (enum, required) — Name of the category - Allowed values: `Arts & Entertainment`, `Baby, Kids & Toys`, `Books & Digital Media`, `Clothing, Shoes & Accessories`, `Computers, Electronics & Software`, `Convenience`, `Gas`, `Department Stores`, `Food & Beverage`, `Health & Beauty`, `Home & Garden`, `Miscellaneous`, `Occasions & Gifts`, `Pets`, `Sports & Outdoors`, `Supplies & Services`, `Travel` ### 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 ### CategoryRelationship - `data` (list of CategoryData, required) ### 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 ### CategoryData - `id` (string, required) — id of the category - `type` ("category", required) ### 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": "standardOffer", "attributes": { "assets": [ { "type": "IMG_VIEW", "url": "http://attribution.getkard.com/logos/breakfastbunny_logo.png?eventCode=IMPRESSION&type=offerAttribution&medium=BROWSE&offerId=629fc220b7a4290009a188ec&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZWZlcnJpbmdQYXJ0bmVyVXNlcklkIjoiNDM4MTAzIiwiaXNzdWVySWQiOiIwMDAwNDMyMSIsInR5cGUiOiJPRkZFUiIsInBheWxvYWQiOnsiand0VGltZXN0YW1wIjoiMjAyNi0wNC0yMyJ9fQ.4f9QmoGpgXVIXu9Tq8XFVcx7Rz0jptsYNYpmaIBszyc&state=eyJyYW5rIjoxLCJmaWx0ZXJzIjpbXX0%3D", "alt": "" }, { "type": "BANNER_VIEW", "url": "https://attribution.getkard.com/public/banners/breakfast-bunny-banner.jpg?eventCode=VIEW&type=offerAttribution&medium=BROWSE&offerId=629fc220b7a4290009a188ec&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZWZlcnJpbmdQYXJ0bmVyVXNlcklkIjoiNDM4MTAzIiwiaXNzdWVySWQiOiIwMDAwNDMyMSIsInR5cGUiOiJPRkZFUiIsInBheWxvYWQiOnsiand0VGltZXN0YW1wIjoiMjAyNi0wNC0yMyJ9fQ.4f9QmoGpgXVIXu9Tq8XFVcx7Rz0jptsYNYpmaIBszyc&state=eyJyYW5rIjoxLCJmaWx0ZXJzIjpbXX0%3D", "alt": "" } ], "expirationDate": "2025-03-17T05:00:00Z", "isTargeted": true, "name": "Worlds Greatest Chicken", "purchaseChannel": [ "INSTORE" ], "startDate": "2024-11-17T05:00:00Z", "terms": "Worlds Greatest Chicken offers are only available within US Locations.", "userReward": { "type": "PERCENT", "value": 5.7 }, "description": "Worlds Greatest Chicken brings you the tastiest crispy, double fried spicy chicken in the world.", "maxRedemptions": 1, "maxRewardAmount": { "type": "CENTS", "value": 2000 }, "maxTransactionAmount": { "type": "CENTS", "value": 10000 }, "minRewardAmount": { "type": "CENTS", "value": 500 }, "minTransactionAmount": { "type": "CENTS", "value": 500 }, "websiteUrl": "http://worldsgreatestchickent.test.com" }, "id": "5e27318c9b346f00087fbb5c", "relationships": { "category": { "data": [ { "type": "category", "id": "65920081b524d126068de24a" }, { "type": "category", "id": "65920081b524d126068de24c" } ] } } } ], "links": { "self": "/v2/issuers/{organizationId}/users/{userId}/offers?page[size]=1?sort=-startDate", "prev": null, "next": "/v2/issuers/{organizationId}/users/{userId}/offers?page[after]=NDMyNzQyODI3OTQw&page[size]=1?&sort=-startDate" }, "included": [ { "type": "category", "id": "65920081b524d126068de24a", "attributes": { "name": "Food & Beverage" } }, { "type": "category", "id": "65920081b524d126068de24c", "attributes": { "name": "Department Stores" } } ], "meta": { "availableCategories": [ { "attributes": { "name": "Food & Beverage" }, "id": "65920081b524d126068de24a", "type": "category" }, { "attributes": { "name": "Department Stores" }, "id": "65920081b524d126068de24c", "type": "category" } ] } } ``` **SDK Code** ```python import requests url = "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/offers" querystring = {"page[size]":"1","filter[isTargeted]":"true","sort":"-startDate"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/offers?page%5Bsize%5D=1&filter%5BisTargeted%5D=true&sort=-startDate'; 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 package main import ( "fmt" "net/http" "io" ) func main() { url := "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/offers?page%5Bsize%5D=1&filter%5BisTargeted%5D=true&sort=-startDate" 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 require 'uri' require 'net/http' url = URI("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/offers?page%5Bsize%5D=1&filter%5BisTargeted%5D=true&sort=-startDate") 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 import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/offers?page%5Bsize%5D=1&filter%5BisTargeted%5D=true&sort=-startDate") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/offers?page%5Bsize%5D=1&filter%5BisTargeted%5D=true&sort=-startDate', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/offers?page%5Bsize%5D=1&filter%5BisTargeted%5D=true&sort=-startDate"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/offers?page%5Bsize%5D=1&filter%5BisTargeted%5D=true&sort=-startDate")! 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() ```