Kard’s Extended API feature enhances our existing rewards endpoints with dynamic, per-user offer data. By requesting UI components through the supportedComponents query parameter, you can surface richer offer experiences to your end users including dynamic descriptions, call-to-action buttons, and contextual tags without building custom logic to interpret raw offer data.
This guide covers how to request and render extended offer fields from the Get Offers by User and Get Locations by User endpoints.
The Extended API uses a component-based model to deliver dynamic offer data. You tell Kard which UI components your app supports, and the API returns the relevant data for each offer.
Coming soon: Offer activations. Some offers will require explicit user action to redeem such as tapping a call-to-action button to boost, renew, or activate an offer. Integrating with the cta component is strongly recommended to ensure the best end-user experience, making it clear to your users what actions are available and driving engagement with offers. Building support for this now gives you a head start so you’re ready when these offers go live.
The components included in the response depend on what you request via the supportedComponents query parameter:
shortDescription, longDescription, cta, tags, detailTags, baseReward): The full experience. Provides dynamic descriptions, call-to-action buttons, contextual tags, and a formatted reward string for both list and detail views. Best for apps that support interactive elements.shortDescription, longDescription, cta): Provides dynamic descriptions that reflect per-user offer state along with a call-to-action button for actions like offer activation or offer boosts. Best for apps that want actionable offers without rendering tag-based UI.shortDescription, longDescription): Provides dynamic descriptions without interactive elements. Best for apps that cannot render buttons or tags. In this case, Kard uses a VIEW event on the offer as the activation signal. When a user views an offer detail page, you fire a VIEW attribution event. After the event, re-fetch the offer to display the updated descriptions reflecting the new user state.You can request any combination of components. Kard evaluates each offer independently and returns the appropriate data based on what you request.
supportedComponents Query ParameterAppend the supportedComponents query parameter to your existing Get Offers by User or Get Locations by User requests. Use repeated parameters for multiple component types.
Get Offers by User with all components:
Get Offers by User with description + call-to-action components:
Get Locations by User with all components:
Get Locations by User with description + call-to-action components:
Get Offers by User with description-only components:
Get Locations by User with description-only components:
For Get Locations by User, you must include include=offers in the query to receive offer data with components.
components ObjectWhen supportedComponents is provided and an offer is eligible for extended data, the response includes a components object within the offer attributes.
Example Response with all components (offer not yet activated):
Example Response with all components (offer already activated):
Note that when the offer is already activated, the cta component is not included in the response.
How you render the components depends on which ones you requested:
If you requested all components (shortDescription, longDescription, cta, tags, detailTags, and baseReward)
shortDescription on offer cards in list/browse viewslongDescription on the offer detail pagecta is present and buttonStyle is PRIMARY, display the call-to-action button using buttonText — when tapped, call the URL in cta.action.url using the specified cta.action.method (see Step 4a)cta is absent, the offer has already been activated — hide the call-to-action buttontags as overlays or badges on the offer card in list/browse views (may be empty)detailTags as labels on the offer detail pagebaseReward as the formatted reward amount on the offer card (e.g., “5.7% cash back”)All components, offer not activated:
All components, offer is activated:
If you requested a subset of components (shortDescription, longDescription, and cta):
longDescription on the offer detail pageshortDescription on offer cards in list viewscta is present and buttonStyle is PRIMARY, display the call-to-action button using buttonText — when tapped, call the URL in cta.action.url using the specified cta.action.method (see Step 4a)cta is absent, the offer has already been activated — hide the call-to-action buttonDescription + call-to-action components, offer not activated:
Description + call-to-action components, offer is activated:
If you requested description-only components (shortDescription and longDescription):
This approach is for issuers that cannot render interactive call-to-action buttons. Instead of using a call-to-action button to activate or boost offers, the VIEW event serves as the activation signal.
shortDescription on offer cards in list/browse viewslongDescription on the offer detail pageshortDescription and longDescriptionImportant: Without a call-to-action button, the user has no explicit activation action. The VIEW event acts as a proxy for activation. You must re-fetch and re-render the offer after firing the VIEW event to display the updated state to the user.
Activations are an upcoming feature. Some offers will require user action before the offer can be redeemed. Supporting the call-to-action flow is key to delivering a clear, intuitive experience for your end users by surfacing actionable next steps directly in the UI. Integrating now means you’ll be ready to support these offers as soon as they launch.
When a user taps a PRIMARY call-to-action button, call the activation endpoint provided in cta.action:
You can include supportedComponents and include=offer as query parameters to receive the updated offer in the response:
Response (201 Created):
Use the updated offer from included to immediately refresh your UI without re-fetching the full offer list.
If you are only using shortDescription and longDescription (no cta), use the VIEW attribution event to signal that a user has engaged with an offer. This acts as the activation trigger.
When a user opens an offer detail page, fire a VIEW event:
After a successful VIEW event, re-fetch the offer with your supported components to get the updated descriptions:
The descriptions will now reflect the updated user state:
Re-render the offer detail page with the updated longDescription, and update the offer card with the new shortDescription in your list views.
We recommend integrating with call-to-action components when possible. The call-to-action flow gives users a clear, explicit action to activate and boost offers and provides a better user experience than the implicit VIEW event approach.
components Objectcta ObjectComponent availability is per-offer. Different offers in the same response may return different components depending on their configuration.
The components object is additive. Existing fields like name, userReward, terms, and assets are always returned regardless of whether you request components.
components before rendering. Not every offer will include it — your UI should gracefully fall back to standard offer fields.cta.action exactly as provided. The URL and method are pre-configured by Kard. Do not modify the URL path or method.included array to update your UI without waiting for a full list refresh.shortDescription and longDescription instead of cta, tags, and detailTags.cta after activation. When an offer has been activated, the cta component is not included in the response. Your UI should hide the call-to-action button when cta is absent.