> 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 Placement Content GET https://rewards-api.getkard.com/v2/issuers/{organizationId}/users/{userId}/placements/{placementId}/content Retrieve the content for a placement. The placement type is resolved server-side so callers no longer pick an endpoint by placement type. Returns a JSON:API document whose `data` resources are self-describing by `type`: a standard placement returns `standardOffer` resources (with `links`, optional `included` categories, and `meta`); a batch-activation or group placement returns `placementBatch` slot resources. Distinguish the two by each resource's `type`. Email and push-notification placements are not servable through this endpoint and respond with a `400`. Required scopes: `rewards:read` Reference: https://docs.getkard.com/api/rewards/placement-content ## 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 - `placementId` (string, required) ### Query parameters - `include` (string, optional) — CSV list of included resources in the response (e.g "categories"). Allowed value is `categories`. Only applies to standard placements (those returning `standardOffer` resources). - `supportedComponents` (enum, optional) — UI component types to include in the response. - Allowed values: `shortDescription`, `longDescription`, `baseReward`, `boostedReward`, `cta`, `tags`, `detailTags`, `logoFlare`, `progressBar` ## Response ### 200 - `PlacementContentResponse` ## 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 ### OffersResponseObject - `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 ### BatchesResponseObject Ordered list of slots for a batch-activation or group placement, with freshness fields and per-slot offer sets. - `data` (list of PlacementBatchData, required) - `meta` (BatchesMeta, optional) — Metadata about the placement. ### 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. ### 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. ### PlacementBatchData One slot in a batch-activation or group placement, with freshness fields and the offers that resolve under the slot's content strategy. - `id` (string, required) — Stable identifier for the slot within the placement - `type` ("placementBatch", required) - `attributes` (PlacementBatchAttributes, required) — Attributes of a placement batch slot. ### BatchesMeta Metadata about the placement. - `placementName` (string, optional) — Display name of the placement, resolved server-side from its id. ### 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 ### 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) ### PlacementBatchAttributes Attributes of a placement batch slot. - `name` (string, required) — Display name for the slot. Falls back to the slot's customer-defined alias, or — when the alias is absent — the name of the placement referenced by the slot. - `isActive` (boolean, required) — Whether the slot is still considered "fresh" for the user. Set to false only when the slot's `expiresAt` is in the past AND the slot resolves to a non-empty offer set; an empty offer set keeps the slot active so partner UIs do not promote "tap to refresh" with nothing to show. Always true for slots of a group placement, which has no activation cycle. - `offers` (list of OfferDataUnion, required) — The set of offers eligible for the user under this slot's content strategy. - `lastActivatedAt` (datetime, optional) — Timestamp of the most recent placementSlotAttribution ACTIVATE event for this (user, placement, slot). Absent for cold slots that have never been activated. - `expiresAt` (datetime, optional) — Computed as `lastActivatedAt + placement.refreshInterval`. Absent for cold slots that have never been activated. - `components` (OfferComponents, optional) — Slot-level UI components. Carries `shortDescription` and `longDescription` (activation copy derived from the parent placement's `refreshInterval`), plus either a `cta` (POST to the slot's activate endpoint) when the slot has no active (non-expired) activation, or a `logoFlare` decoration when it does — `cta` and `logoFlare` are mutually exclusive on a single slot. Omitted for slots of a group placement, which has no activation cycle. - `assets` (list of Asset, optional) — Slot-level visual assets. Currently a single `IMG_VIEW` SVG showing the slot's initials, themed via the `--icon-fill` CSS custom property. ### 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 ### Standard placement (offers) **Response** ```json { "data": [ { "type": "standardOffer", "id": "5e27318c9b346f00087fbb5c", "attributes": { "name": "World's Greatest Chicken", "terms": "Offer valid at US locations only.", "purchaseChannel": [ "INSTORE" ], "userReward": { "type": "PERCENT", "value": 5.7 }, "startDate": "2024-11-17T05:00:00Z", "expirationDate": "2025-03-17T05:00:00Z", "isTargeted": true, "assets": [ { "type": "IMG_VIEW", "url": "https://attribution.getkard.com/logos/wgc_logo.png?token=example", "alt": "" } ], "websiteUrl": "https://worldsgreatestchicken.test.com", "description": "Crispy, double-fried spicy chicken." }, "relationships": { "category": { "data": [ { "type": "category", "id": "65920081b524d126068de24a" } ] } } } ], "included": [ { "type": "category", "id": "65920081b524d126068de24a", "attributes": { "name": "Food & Beverage" } } ], "links": { "self": "/v2/issuers/organization-123/users/user-123/placements/placement-homepage-banner/content", "prev": null, "next": null }, "meta": { "placementName": "Homepage Banner", "availableCategories": [ { "type": "category", "id": "65920081b524d126068de24a", "attributes": { "name": "Food & Beverage" } } ] } } ``` **SDK Code** ```python Standard placement (offers) import requests url = "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/placements/placement-homepage-banner/content" querystring = {"include":"categories"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript Standard placement (offers) const url = 'https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/placements/placement-homepage-banner/content?include=categories'; 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 Standard placement (offers) package main import ( "fmt" "net/http" "io" ) func main() { url := "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/placements/placement-homepage-banner/content?include=categories" 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 Standard placement (offers) require 'uri' require 'net/http' url = URI("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/placements/placement-homepage-banner/content?include=categories") 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 Standard placement (offers) 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/placements/placement-homepage-banner/content?include=categories") .header("Authorization", "Bearer ") .asString(); ``` ```php Standard placement (offers) request('GET', 'https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/placements/placement-homepage-banner/content?include=categories', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp Standard placement (offers) using RestSharp; var client = new RestClient("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/placements/placement-homepage-banner/content?include=categories"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift Standard placement (offers) import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/placements/placement-homepage-banner/content?include=categories")! 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() ``` ### Batch-activation / group placement (batches) **Response** ```json { "data": [ { "type": "placementBatch", "id": "slot-newly-live", "attributes": { "name": "Newly Live", "isActive": true, "lastActivatedAt": "2026-05-20T06:00:00Z", "expiresAt": "2026-05-21T06:00:00Z", "assets": [], "offers": [ { "type": "standardOffer", "id": "5e27318c9b346f00087fbb5c", "attributes": { "name": "World's Greatest Chicken", "terms": "Offer valid at US locations only.", "purchaseChannel": [ "INSTORE" ], "userReward": { "type": "PERCENT", "value": 5.7 }, "startDate": "2024-11-17T05:00:00Z", "expirationDate": "2025-03-17T05:00:00Z", "isTargeted": false, "assets": [] } } ] } }, { "type": "placementBatch", "id": "slot-travel", "attributes": { "name": "Travel", "isActive": true, "assets": [], "offers": [] } } ], "meta": { "placementName": "Weekly Bundles" } } ``` **SDK Code** ```python Batch-activation / group placement (batches) import requests url = "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/placements/placement-weekly-bundles/content" querystring = {"supportedComponents":"baseReward"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript Batch-activation / group placement (batches) const url = 'https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/placements/placement-weekly-bundles/content?supportedComponents=baseReward'; 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 Batch-activation / group placement (batches) package main import ( "fmt" "net/http" "io" ) func main() { url := "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/placements/placement-weekly-bundles/content?supportedComponents=baseReward" 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 Batch-activation / group placement (batches) require 'uri' require 'net/http' url = URI("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/placements/placement-weekly-bundles/content?supportedComponents=baseReward") 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 Batch-activation / group placement (batches) 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/placements/placement-weekly-bundles/content?supportedComponents=baseReward") .header("Authorization", "Bearer ") .asString(); ``` ```php Batch-activation / group placement (batches) request('GET', 'https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/placements/placement-weekly-bundles/content?supportedComponents=baseReward', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp Batch-activation / group placement (batches) using RestSharp; var client = new RestClient("https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/placements/placement-weekly-bundles/content?supportedComponents=baseReward"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift Batch-activation / group placement (batches) import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/v2/issuers/organization-123/users/user-123/placements/placement-weekly-bundles/content?supportedComponents=baseReward")! 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() ```