--- title: "Get Placement Content" method: GET path: "/v2/issuers/{organizationId}/users/{userId}/placements/{placementId}/content" tags: ["users > Rewards"] --- # Get Placement Content `GET /v2/issuers/{organizationId}/users/{userId}/placements/{placementId}/content` ## Request - Base URL: `https://rewards-api.getkard.com` - URL: `https://rewards-api.getkard.com/v2/issuers/{organizationId}/users/{userId}/placements/{placementId}/content` - Auth: HTTP bearer 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 also return `standardOffer` resources, as a preview of a send: up to `availableSlots` offers for email and up to one offer for push.
Required scopes: `rewards:read` ## 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 - `supportedComponents` 'shortDescription' | 'longDescription' | 'baseReward' | 'boostedReward' | 'cta' | 'tags' | 'detailTags' | 'logoFlare' | 'progressBar': Available UI component types for offers ## Response `200` Response with status 200 - union: Combined placement-content response. The placement is resolved server-side and the response is returned verbatim as one of two variants: a standard placement yields the offers response (`standardOffer` resources with `links`, optional `included` categories, and `meta`), while a batch-activation or group placement yields the batches response (`placementBatch` slot resources). Callers distinguish the two by each resource's `type` rather than a separate discriminator. - UsersRewardsOffersResponseObject - `data` UsersRewardsOfferDataUnion[], required - `type` 'standardOffer', required: Discriminator value: standardOffer - `id` string, required: The unique identifier for a document in the database - `attributes` UsersRewardsStandardOfferFields, required - `terms` string, required: Terms and conditions on offer - `maxRedemptions` integer: Maximum times cardholder can redeem offer, if applicable - `name` string, required: Name of offer - `purchaseChannel` CommonsPurchaseChannel[], required - `userReward` UsersRewardsCommission, required - `type` 'FLAT' | 'PERCENT', required: Type of commission on offer (% or a flat $) - `value` number, double, required - `assets` UsersRewardsAsset[], required: Assets associated with offer - `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 - `startDate` string, date-time, required: Beginning date of offer (UTC) - `expirationDate` string, date-time, required: Expiration date of offer if applicable (UTC) - `isTargeted` boolean, required: True returns only targeted offers, false returns only non-targeted offers - `minTransactionAmount` UsersRewardsAmount - `type` 'CENTS', required - `value` integer, required - `maxTransactionAmount` UsersRewardsAmount - `type` 'CENTS', required - `value` integer, required - `minRewardAmount` UsersRewardsAmount - `type` 'CENTS', required - `value` integer, required - `maxRewardAmount` UsersRewardsAmount - `type` 'CENTS', required - `value` integer, required - `websiteUrl` string: URL to the website of the offer provider - `description` string: Description of the offer - `components` CommonsOfferComponents: UI component data for rendering offer details - `shortDescription` string: Short description for the offer - `longDescription` string: Long description for the offer - `baseReward` string: Formatted reward string - `boostedReward` string: Formatted boosted reward string - `cta` CommonsCtaComponent: Call-to-action button component for offers - `buttonText` string, required: Text to display on the button - `buttonStyle` 'PRIMARY' | 'SECONDARY' | 'DISABLED', required: Available button styles for CTA components - `action` CommonsCtaAction: Action configuration for CTA button - … - `startIcon` string: Icon identifier to display on the button - `tags` string[]: Tags for the offer - `detailTags` string[]: Detail tags for the offer - `logoFlare` CommonsLogoFlare: Logo flare configuration for offer display - `borderColor` 'PRIMARY' | 'SECONDARY', required: Available border color options for logo flare - `badge` CommonsLogoFlareBadge: Badge configuration for logo flare - … - `progressBar` CommonsProgressBar: 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 - `label` string, required: Formatted label for the progress bar - `segmented` boolean, required: Whether the progress bar should be displayed as segmented - `segments` CommonsProgressBarSegments: Segment configuration for the progress bar in different layouts - … - `labels` CommonsProgressBarLabels, required: Labels to render around the progress bar in different layouts - … - `relationships` UsersRewardsEligibilityOfferRelationship - `category` UsersRewardsCategoryRelationship, required - `data` UsersRewardsCategoryData[], required - `id` string, required: id of the category - `type` 'category', required - `locations` CommonsRelationshipMultiple - `data` CommonsRelationshipData[], required - `type` string, required: Type of document returned - `id` string, required: The ID of the related resource - `links` CommonsLinks, required: Related links to the API call - `self` string, required - `prev` string - `next` string - `included` UsersRewardsEligibilityOfferIncluded[] - `id` string, required: id of the category - `type` 'category', required - `attributes` UsersRewardsCategoryFields, required - `name` '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', required: Category of merchant. Please use URL Encode for non single word categories. (Food & Beverage should be Food%20%26%20Beverage) - `meta` UsersRewardsOffersMeta: Metadata about the full result set across all pages - `availableCategories` UsersRewardsCategoryIncluded[]: All distinct categories available across the entire filtered result set, not just the current page - `id` string, required: id of the category - `type` 'category', required - `attributes` UsersRewardsCategoryFields, required - `name` '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', required: Category of merchant. Please use URL Encode for non single word categories. (Food & Beverage should be Food%20%26%20Beverage) - `placementName` string: 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. - UsersRewardsBatchesResponseObject: Ordered list of slots for a batch-activation or group placement, with freshness fields and per-slot offer sets. - `data` UsersRewardsPlacementBatchData[], required - `id` string, required: Stable identifier for the slot within the placement - `type` 'placementBatch', required - `attributes` UsersRewardsPlacementBatchAttributes, required: 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. - `lastActivatedAt` string, date-time: Timestamp of the most recent placementSlotAttribution ACTIVATE event for this (user, placement, slot). Absent for cold slots that have never been activated. - `expiresAt` string, date-time: Computed as `lastActivatedAt + placement.refreshInterval`. Absent for cold slots that have never been activated. - `components` CommonsOfferComponents: UI component data for rendering offer details - `shortDescription` string: Short description for the offer - `longDescription` string: Long description for the offer - `baseReward` string: Formatted reward string - `boostedReward` string: Formatted boosted reward string - `cta` CommonsCtaComponent: Call-to-action button component for offers - `buttonText` string, required: Text to display on the button - `buttonStyle` 'PRIMARY' | 'SECONDARY' | 'DISABLED', required: Available button styles for CTA components - `action` CommonsCtaAction: Action configuration for CTA button - … - `startIcon` string: Icon identifier to display on the button - `tags` string[]: Tags for the offer - `detailTags` string[]: Detail tags for the offer - `logoFlare` CommonsLogoFlare: Logo flare configuration for offer display - `borderColor` 'PRIMARY' | 'SECONDARY', required: Available border color options for logo flare - `badge` CommonsLogoFlareBadge: Badge configuration for logo flare - … - `progressBar` CommonsProgressBar: 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 - `label` string, required: Formatted label for the progress bar - `segmented` boolean, required: Whether the progress bar should be displayed as segmented - `segments` CommonsProgressBarSegments: Segment configuration for the progress bar in different layouts - … - `labels` CommonsProgressBarLabels, required: Labels to render around the progress bar in different layouts - … - `assets` UsersRewardsAsset[]: Slot-level visual assets. Currently a single `IMG_VIEW` SVG showing the slot's initials, themed via the `--icon-fill` CSS custom property. - `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 - `offers` UsersRewardsOfferDataUnion[], required: The set of offers eligible for the user under this slot's content strategy. - `type` 'standardOffer', required: Discriminator value: standardOffer - `id` string, required: The unique identifier for a document in the database - `attributes` UsersRewardsStandardOfferFields, required - `terms` string, required: Terms and conditions on offer - `maxRedemptions` integer: Maximum times cardholder can redeem offer, if applicable - `name` string, required: Name of offer - `purchaseChannel` CommonsPurchaseChannel[], required - `userReward` UsersRewardsCommission, required - … - `assets` UsersRewardsAsset[], required: Assets associated with offer - … - `startDate` string, date-time, required: Beginning date of offer (UTC) - `expirationDate` string, date-time, required: Expiration date of offer if applicable (UTC) - `isTargeted` boolean, required: True returns only targeted offers, false returns only non-targeted offers - `minTransactionAmount` UsersRewardsAmount - … - `maxTransactionAmount` UsersRewardsAmount - … - `minRewardAmount` UsersRewardsAmount - … - `maxRewardAmount` UsersRewardsAmount - … - `websiteUrl` string: URL to the website of the offer provider - `description` string: Description of the offer - `components` CommonsOfferComponents: UI component data for rendering offer details - … - `relationships` UsersRewardsEligibilityOfferRelationship - `category` UsersRewardsCategoryRelationship, required - … - `locations` CommonsRelationshipMultiple - … - `meta` UsersRewardsBatchesMeta: Metadata about the placement. - `placementName` string: Display name of the placement, resolved server-side from its id. ## Other responses - `400`: Error response with status 400 - `401`: Error response with status 401 - `404`: Error response with status 404 - `429`: The issuer's traffic grew faster than its allowed rate, or the endpoint's own limit was reached. If the response includes a `Retry-After` header, wait that many seconds before retrying. See [Rate Limits](/2024-10-01/api/integration-guides/rate-limits). - `500`: Error response with status 500 ## Changes - **2026-10-22** `4e87fc8b018b`: 3 info - added the non-success response with the status `429` - added the optional property `oneOf[subschema #1: OffersResponseObject]/data/items/oneOf[subschema #1]/relationships/oneOf[subschema #1: CategoryRelationshipObject]/locations` to the response with the `200` status - added the optional property `oneOf[subschema #2: BatchesResponseObject]/data/items/attributes/offers/items/oneOf[subschema #1]/relationships/oneOf[subschema #1: CategoryRelationshipObject]/locations` to the response with the `200` status [Operation history](https://skmtc.dev/getkard/apis/getkard-2/changes/v2/issuers/:organizationId/users/:userId/placements/:placementId/content/get.md) --- [API](https://skmtc.dev/getkard/apis/getkard-2.md) - [All operations](https://skmtc.dev/getkard/apis/getkard-2/llms.txt) - [OpenAPI document](https://skmtc.dev/getkard/apis/getkard-2/revisions/bd47764afa21?raw)