Changelog

12.2.2 - 2026-06-23

Added

• BatchesMeta — new type providing metadata about placements in batch responses, including an optional placementName field.
• placementName field added to BatchesMeta and OffersMeta to expose the display name of a placement resolved server-side.

12.2.1 - 2026-06-23

• SDK regeneration
• Unable to analyze changes with AI, incrementing PATCH version.

12.2.0 - 2026-06-22

Added

• RewardsClient.placementContent() and AsyncRewardsClient.placementContent() — new unified endpoint method (with RequestOptions and GetPlacementContentRequest overloads) that retrieves content for any placement type, returning standardOffer or placementBatch resources.
• GetPlacementContentRequest — new request type with optional include (CSV resource list) and supportedComponents (ComponentType list) builder fields.
• PlacementContentResponse — new response type carrying a data list of PlacementContentData, optional links, included, and meta fields.
• PlacementContentData — new union type wrapping either an OfferDataUnion or PlacementBatchData variant, with a Visitor<T> interface for exhaustive handling.

12.1.0 - 2026-06-17

Added

• TransactionsAttributes.getAccountId() — new optional String field that returns an account identifier associated with a transaction; exposed via accountId(String) and accountId(Optional<String>) builder methods.

12.0.0 - 2026-06-11

Added

• CreateEmailAttributes and CreateEmailPlacementData — new types for constructing email placement creation request bodies, carrying name, availableSlots, cadence, and an optional contentStrategyId.
• CreateGroupAttributes and CreateGroupPlacementData — new types for constructing group placement creation request bodies, carrying name and a list of CreateBatchActivationSlot slots.
• UpdateEmailAttributes and UpdateEmailPlacementData — new types for constructing email placement update (PUT) request bodies with required name, availableSlots, and cadence fields plus an optional contentStrategyId.
• UpdateGroupAttributes and UpdateGroupPlacementData — new types for constructing group placement update request bodies; slots absent from the provided list are removed from the prior state.
• EmailPlacementAttributes, GroupPlacementAttributes, GroupPlacementData, and PlacementData — new response-side types representing the full attributes and resource structures for email and group placements.

11.2.0 - 2026-06-10

Added

• NotificationDataUnion — new factory methods pushNotificationPlacementFile() and emailNotificationPlacementFile() to construct union variants, with matching is*, get* accessors for each variant.
• NotificationType — new enum constants PUSH_NOTIFICATION_PLACEMENT_FILE and EMAIL_NOTIFICATION_PLACEMENT_FILE, with corresponding visit* methods added to the Visitor interface.
• PushNotificationPlacementFileData, PushNotificationPlacementFileAttributes, and PushNotificationPlacementFileRelationships — new types representing push placement-file notification payloads, including placement name, available slots, cadence, and a presigned gzipped JSONL download URL.
• EmailNotificationPlacementFileData, EmailNotificationPlacementFileAttributes, and EmailNotificationPlacementFileRelationships — new types representing email placement-file notification payloads, including placement name, organization ID, available slots, cadence, and a presigned download URL.

11.1.0 - 2026-06-10

Added

• UpdateUserRequestAttributes.getHistoricalTransactionsSent() — new optional Boolean field that, when set to true, confirms historical transactions have been sent for the user; this is a one-way flag and cannot be reverted once set.

11.0.0 - 2026-06-01

Breaking Changes

• PlacementBatchAttributes.getShortDescription() and getShortDescription() — both methods are removed; access these values via getComponents() → OfferComponents instead.
• PlacementBatchAttributes.getLongDescription() — removed; access this value via getComponents() → OfferComponents instead.
• PlacementBatchAttributes builder — ShortDescriptionStage and LongDescriptionStage are removed; name() now returns IsActiveStage directly. Existing builder chains calling .name(...).shortDescription(...).longDescription(...).isActive(...) will fail to compile — remove the .shortDescription(...) and .longDescription(...) calls.

10.0.0 - 2026-06-01

Breaking Changes

• PlacementBatchAttributes builder — two new required stages (ShortDescriptionStage and LongDescriptionStage) are inserted between NameStage and IsActiveStage; any existing builder chain calling .name(...).isActive(...) will fail to compile. Migrate by inserting .shortDescription("...") and .longDescription("...") between those two calls.

Added

• PlacementBatchAttributes.getShortDescription() — new required String field containing a short, human-readable description of how long the slot stays activated after a user taps activate (e.g. "Activated for 24 hours").
• PlacementBatchAttributes.getLongDescription() — new required String field containing a longer description of the slot’s activation behavior, clarifying which offers will be activated and for how long.

9.0.0 - 2026-06-01

Breaking Changes

• BatchSlotData — renamed to PlacementBatchAttributes; getSlotId() and getAlias() are removed, replaced by getName(); update all references and builder chains (slotId(...).alias(...)) to use PlacementBatchAttributes.builder().name(...) instead.
• BatchesResponseObject.getData() — return type changed from List<BatchSlotData> to List<PlacementBatchData>; update all code that reads or builds the data list to use the new PlacementBatchData wrapper type.
• BatchSlotData builder stages SlotIdStage and AliasStage — removed; the builder now starts at NameStage with a single name(String) step; replace two-step slotId(...).alias(...) chains with name(...).

Added

• PlacementBatchData — new JSON:API resource wrapper exposing getId(), getType() (always "placementBatch"), and getAttributes() (PlacementBatchAttributes); used as the element type in BatchesResponseObject.getData().

8.0.0 - 2026-06-01

Breaking Changes

• BatchActivationSlot — renamed to BatchActivationSlotAttributes; getSlotId() and getContentStrategyId() removed; replace all references and builder chains with the new type name.
• CreateBatchActivationSlot / UpdateBatchActivationSlot — getContentStrategyId() replaced by getPlacementId() and ContentStrategyIdStage renamed to PlacementIdStage; replace contentStrategyId(...) calls with placementId(...).
• BatchActivationPlacementAttributes.getSlots() — removed; slots are now accessed via BatchActivationPlacementData.getRelationships() (now required) using the new BatchActivationPlacementRelationships type.
• PlacementListResponse.getIncluded() / PlacementResource.getIncluded() — return type changed from Optional<List<ContentStrategyResponse>> to Optional<List<IncludedResource>>; update all code that reads or builds the included list.

Added

• IncludedResource — new sealed union type (visitor pattern) discriminating between contentStrategy, batchActivationSlot, placementMainPage, and placementPushNotification variants in the JSON:API included array; also introduces ResourceIdentifier for type/id pointers.
• BatchActivationPlacementRelationships, BatchActivationSlotRelationships, and PlacementRelationships — new relationship types exposing JSON:API relationships objects for placements and slots; surfaced via new getRelationships() fields on BatchActivationPlacementData, MainPagePlacementData, and PushNotificationPlacementData.
• ToManyRelationship / ToOneRelationship — new types representing JSON:API to-many and to-one relationships with fluent builders.
• BatchActivationSlotAttributes.getShortDescription() and corresponding fields on CreateBatchActivationSlot / UpdateBatchActivationSlot — new optional String (max 50 chars) for a slot short description.
• BatchActivationSlotInclusion / ContentStrategyInclusion — new inclusion types representing embedded batchActivationSlot and contentStrategy resources in the JSON:API included array.

7.2.0 - 2026-05-28

Added

• BatchSlotData.getComponents() — new optional OfferComponents field exposing slot-level UI components; carries a cta when the slot has no active activation, or a logoFlare decoration when it does.
• BatchSlotData.getAssets() — new optional List<Asset> field exposing slot-level visual assets (currently a single IMG_VIEW SVG showing the slot’s initials).
• BatchSlotData builder — new components(OfferComponents), components(Optional<OfferComponents>), assets(List<Asset>), and assets(Optional<List<Asset>>) builder methods on _FinalStage.

7.1.0 - 2026-05-28

Added

• GetEarnedRewardsRequest.filterPaidInFullOnly — new optional Boolean filter that, when true, restricts the rewarded transaction history to transactions paid in full to the issuer (paidToIssuer is PAID_IN_FULL) and limits which transactions contribute to lifetimeRewardsInCents in the response metadata.

Changed

• GetEarnedRewardsMeta.getLifetimeRewardsInCents() — Javadoc updated to clarify that by default all matched transactions are included regardless of payment status, and that passing filter[paidInFullOnly]=true restricts the lifetime total to fully-paid transactions.

7.0.1 - 2026-05-28

• chore: update child organization name validation docs
• Refresh Javadoc across all child organization clients and types to
• reflect the updated name validation rule: names must now contain at
• least one letter and may contain only letters and spaces, replacing
• the previous “uppercase, no spaces” constraint.
• Key changes:
• Update create() Javadoc in ChildrenClient, AsyncChildrenClient, RawChildrenClient, and AsyncRawChildrenClient
• Update getName() and NameStage.name() Javadoc in ChildOrganizationAttributes and CreateChildAttributes
• Update getName() and Builder.name() Javadoc in UpdateChildAttributes
• 🌿 Generated with Fern

7.0.0 - 2026-05-27

Breaking Changes

• EarnedRewardRelationships builder — a new required offer (RelationshipSingle) step has been inserted into the staged builder between user() and transaction(). Existing call chains of the form .user(…).transaction(…) will not compile; migrate by inserting .offer(…) between the two calls: .user(…).offer(…).transaction(…).
• EarnedRewardRelationships.UserStage.user() — return type changed from TransactionStage to the new OfferStage interface; any code that stores or casts the return value of user() as TransactionStage must be updated to OfferStage.

6.4.1 - 2026-05-27

• chore: update Javadoc links in uploads clients to versioned API paths
• Correct stale documentation hyperlinks across all four uploads client
• classes (UploadsClient, AsyncUploadsClient, RawUploadsClient,
• AsyncRawUploadsClient). The old unversioned paths have been replaced
• with their canonical versioned equivalents under /2024-10-01/.
• Key changes:
• Replace /api/uploads/create-upload-part with /2024-10-01/api/transactions/uploads/create-part in create() Javadoc
• Replace /api/uploads/create-upload with /2024-10-01/api/transactions/uploads/create in addPart() Javadoc
• Fix line-break in “Add Upload Part” anchor text so it renders as a single inline link
• 🌿 Generated with Fern

6.4.0 - 2026-05-26

Added

• AttributionsClient.activatePlacementSlot() and AsyncAttributionsClient.activatePlacementSlot() — new methods to record a user’s activation of a batch-activation placement slot, writing slot-level and per-offer ACTIVATE events.
• RawAttributionsClient.activatePlacementSlot() and AsyncRawAttributionsClient.activatePlacementSlot() — raw HTTP response variants of the slot activation methods, returning KardApiHttpResponse<ActivatePlacementSlotResponse>.
• ActivatePlacementSlotResponse, ActivatePlacementSlotResponseData, and ActivatePlacementSlotResponseAttributes — new response types carrying the slot-level event id, type, and resolved offerIds returned by the activation endpoint.
• PlacementSlotAttributionRequest, PlacementSlotAttributionAttributes, and PlacementSlotMedium — new request types and medium enum for submitting placement slot attribution events.
• CreateAttributionRequestUnion.placementSlotAttribution() — new factory method, predicate, accessor, and visitor arm for the placementSlotAttribution union variant; AttributionState gains optional getPlacementId() and getSlotId() fields.

6.3.0 - 2026-05-26

Added

• RewardsClient.placementBatches() and AsyncRewardsClient.placementBatches() — new methods to retrieve batch-activation placement slots in slot order, including offer set, alias, and freshness fields.
• RawRewardsClient.placementBatches() and AsyncRawRewardsClient.placementBatches() — raw HTTP response variants of the batch retrieval methods, returning KardApiHttpResponse<BatchesResponseObject>.
• GetBatchesByPlacementRequest — new request type with an optional supportedComponents field (List<ComponentType>) to filter UI component types in the batch response.
• BatchesResponseObject — new response wrapper type containing a List<BatchSlotData> returned by batch activation reward queries.
• BatchSlotData — new type representing a single placement slot, exposing slotId, alias, isActive, lastActivatedAt, expiresAt, and offers via a staged builder.

6.2.0 - 2026-05-26

Added

• BatchActivationPlacementData and BatchActivationPlacementAttributes — new types representing a batch activation placement, exposing name, organization ID, refresh interval, and slots via staged builders and accessors.
• BatchActivationSlot, CreateBatchActivationSlot, and UpdateBatchActivationSlot — new types describing individual slots within a batch activation placement, carrying contentStrategyId, alias, and an optional slotId for update identity.
• CreateBatchActivationPlacementData and UpdateBatchActivationPlacementData — new request wrapper types for creating and updating batch activation placements, bundling their respective attributes types.
• PlacementFormatUnion, CreatePlacementDataUnion, and UpdatePlacementDataUnion — each extended with a placementBatchActivation() factory method, isPlacementBatchActivation() predicate, getPlacementBatchActivation() accessor, and visitPlacementBatchActivation() visitor arm.
• PlacementTypeFilter.PLACEMENT_BATCH_ACTIVATION — new filter constant, Value enum entry, and Visitor.visitPlacementBatchActivation() method for filtering and visiting batch activation placements.

6.1.0 - 2026-05-22

Added

• ProgressBarSegment.getSeparator() — new optional accessor returning Optional<ProgressBarSegmentSeparator> that specifies the separator style to render between segment nodes.
• ProgressBarSegment.getLabels() — new optional accessor returning Optional<List<ProgressBarSegmentLabel>> for per-node label configuration on a progress bar segment.
• ProgressBarSegment.getSelection() — new optional accessor returning Optional<ProgressBarSegmentSelection> indicating which segment nodes the UI should render as selected based on current progress.
• ProgressBarSegmentLabel — new type with required getTitle() and getDescription() fields representing label text for a segment node.
• ProgressBarSegmentSeparator and ProgressBarSegmentSelection — new enum-like types supporting LINE and CURRENT/CURRENT_AND_BELOW values respectively, used by the new ProgressBarSegment fields.

6.0.0 - 2026-05-21

Breaking Changes

• ContentStrategyFilter — class removed and replaced by ContentStrategySort; update all references from ContentStrategyFilter to ContentStrategySort.
• ContentStrategyAttributes.getFilter(), CreateContentStrategyAttributes.getFilter(), and UpdateContentStrategyAttributes.getFilter() — removed; replaced by getSort() returning Optional<ContentStrategySort>. Update all call sites to use getSort().
• _FinalStage.filter(ContentStrategyFilter) and _FinalStage.filter(Optional<ContentStrategyFilter>) — removed from the builder interfaces of all three attributes types; replace with sort(ContentStrategySort) or sort(Optional<ContentStrategySort>).
• The serialized JSON field name changed from "filter" to "sort" on all three attributes types; any code constructing or parsing raw JSON payloads must be updated accordingly.

5.0.0 - 2026-05-20

Breaking Changes

• PushNotificationPlacementAttributes.getCreatedAt() and getLastModified() — removed; these fields are no longer returned by the API. Remove any call sites that read these values.
• PushNotificationPlacementAttributes.Builder staged interfaces CreatedAtStage and LastModifiedStage — removed from the builder chain; calls to .createdAt(...) and .lastModified(...) must be deleted, and the builder now advances directly from CadenceStage to _FinalStage.

Added

• PlacementResource — new response type wrapping a single placement (getData()) with an optional getIncluded() list of ContentStrategyResponse objects, populated when include=contentStrategy is requested.
• GetPlacementRequest — new request type with an optional include parameter for embedding related content strategy resources in a single-placement response.
• PlacementListResponse.getIncluded() — new optional accessor returning Optional<List<ContentStrategyResponse>> with content strategies embedded when include=contentStrategy is supplied on list requests.

4.0.0 - 2026-05-20

Breaking Changes

• ContentStrategyAttributes.getFilters(), CreateContentStrategyAttributes.getFilters(), and UpdateContentStrategyAttributes.getFilters() — removed; replaced by getFilter() returning Optional<ContentStrategyFilter>. Update all call sites to use getFilter() and handle the Optional wrapper.
• _FinalStage.filters(List<ContentStrategyFilter>), addFilters(), and addAllFilters() — removed from all three attributes builder interfaces; replace with filter(ContentStrategyFilter) or filter(Optional<ContentStrategyFilter>).
• The serialized JSON field name changed from "filters" (array) to "filter" (single value); any code that constructs or parses raw JSON payloads must be updated accordingly.

3.2.0 - 2026-05-19

Added

• getContentStrategyId() — new optional accessor on MainPagePlacementAttributes and PushNotificationPlacementAttributes returning the ID of the content strategy linked to a placement.
• contentStrategyId() — new builder method on CreateMainPageAttributes, CreatePushNotificationAttributes, UpdateMainPageAttributes, and UpdatePushNotificationAttributes for linking a placement to a content strategy on create or update.
• ListPlacementsRequest.filterContentStrategyId() — new optional filter that scopes list-placements results to placements associated with a specific content strategy ID.

3.1.0 - 2026-05-19

Added

• ContentStrategiesClient and AsyncContentStrategiesClient — new sub-clients for managing organization content strategies, accessible via OrganizationsClient.contentStrategies(), with full CRUD support (create(), list(), get(), update(), delete()).
• RawContentStrategiesClient and AsyncRawContentStrategiesClient — raw variants of the content strategies sub-clients returning KardApiHttpResponse-wrapped results with full HTTP metadata access.
• ContentStrategyAttributes, ContentStrategyResponse, and ContentStrategyListResponse — new model types representing a content strategy resource, its single-item response envelope, and its paginated list response respectively.
• ContentStrategyFilter — new enum-like class with constants EXPIRING_SOON, PERSONALIZED, HIGHEST_CASHBACK, and NEWLY_LIVE, supporting a Visitor<T> pattern for exhaustive handling.
• CreateContentStrategyRequestBody, UpdateContentStrategyRequestBody, and ListContentStrategiesRequest — new request types for creating, updating, and paginated-listing of content strategies, each with staged builders.

3.0.0 - 2026-05-14

Breaking Changes

• LocationAttributes.getPartnerIds() — return type changed from Optional<List<LocationPartnerId>> to List<LocationPartnerId>; update all call sites to remove Optional unwrapping (an absent value is now represented as an empty list).
• _FinalStage.partnerIds(Optional<List<LocationPartnerId>>) — the Optional-accepting builder overload is removed; replace calls with partnerIds(List<LocationPartnerId>), addPartnerIds(LocationPartnerId), or addAllPartnerIds(List<LocationPartnerId>).

Added

• LocationAttributes.Builder.addPartnerIds() and addAllPartnerIds() — new convenience builder methods for appending individual or multiple LocationPartnerId entries without replacing the existing list.

2.0.0 - 2026-05-14

Breaking Changes

• EarnedRewardAttributes — class removed; replace all usages with RewardNotificationAttributes.
• EarnedRewardApprovedData.getAttributes() — return type changed from EarnedRewardAttributes to RewardNotificationAttributes; update variable declarations and builder calls accordingly.
• RewardNotificationAttributes.Builder and EarnedRewardSettledAttributes.Builder — two new required staged-builder steps (TransactionIdStage → TransactionAmountInCentsStage) inserted after attributionUrl(…); chain .transactionId(…).transactionAmountInCents(…) before proceeding to _FinalStage.
• ValidTransactionAttributes staged builder — two new required stages (TransactionIdStage → TransactionAmountInCentsStage) inserted between AttributionUrlStage and CommissionEarnedStage; chain .transactionId(…).transactionAmountInCents(…) after .attributionUrl(…).
• IRewardNotificationAttributes — three new methods (getTransactionId(), getTransactionAmountInCents(), getTransactionTimestamp()) added to the interface; all custom implementations must add these methods.

Added

• getTransactionId(), getTransactionAmountInCents(), and getTransactionTimestamp() — new accessors added to RewardNotificationAttributes and ValidTransactionAttributes exposing the originating transaction ID, amount in cents, and ISO timestamp.

1.6.0 - 2026-05-12

Added

• LocationPartnerId — new public class representing a third-party partner identifier (e.g. a Google Place ID) associated with a reward location; exposes getType() and getId() accessors with a staged builder.
• LocationPartnerIdType — new enum-like class with a GOOGLE constant and Visitor<T> pattern for exhaustive handling of partner ID types.
• LocationAttributes.getPartnerIds() — new optional Optional<List<LocationPartnerId>> field exposing partner IDs for LOCAL locations; builder gains partnerIds(List<LocationPartnerId>) and partnerIds(Optional<List<LocationPartnerId>>) overloads.

1.5.2 - 2026-05-07

• chore: update required scope for createBulkTransactionsUploadUrl to files:write
• Correct the documented OAuth scope required to call createBulkTransactionsUploadUrl
• across all four transaction client variants. The Javadoc previously stated
• transaction:write as the required scope; the correct scope is files:write.
• No public API signatures, return types, or runtime behavior are changed.
• Key changes:
• Update Javadoc in TransactionsClient.createBulkTransactionsUploadUrl() to reflect files:write scope
• Update Javadoc in AsyncTransactionsClient.createBulkTransactionsUploadUrl() to reflect files:write scope
• Update Javadoc in RawTransactionsClient.createBulkTransactionsUploadUrl() to reflect files:write scope
• Update Javadoc in AsyncRawTransactionsClient.createBulkTransactionsUploadUrl() to reflect files:write scope
• 🌿 Generated with Fern

17.1.1 - 2026-04-30

• chore: update Javadoc for bulk upload and uploads client deprecation
• Refresh documentation across all transaction and uploads client variants
• to reflect expanded bulk upload support and mark the legacy uploads API
• as deprecated.
• Key changes:
• Update createBulkTransactionsUploadUrl Javadoc to document support for both incomingTransactionsFile and historicalTransactionsFile types (sync, async, raw, and async-raw clients)
• Mark UploadsClient.create(), createPart(), and update() (and all async/raw variants) as deprecated in favor of the bulk transactions upload URL endpoint
• Add deprecation notice pointing consumers to the Historical Transaction Uploads integration guide
• 🌿 Generated with Fern

17.1.0 - 2026-04-23

Added

• EarnedRewardAttributes.getTransactionTimestamp() — new optional OffsetDateTime field exposing the ISO-formatted timestamp of the originating transaction; builder gains transactionTimestamp(OffsetDateTime) and transactionTimestamp(Optional<OffsetDateTime>) methods.
• EarnedRewardSettledAttributes.getTransactionTimestamp() — new optional OffsetDateTime field exposing the ISO-formatted timestamp of the originating transaction; builder gains transactionTimestamp(OffsetDateTime) and transactionTimestamp(Optional<OffsetDateTime>) methods.

17.0.0 - 2026-04-17

Breaking Changes

• CommissionEarnedDetails.getIssuer() — the issuer field and IssuerStage builder stage are removed; update all construction call chains to start from UserStage (call CommissionEarnedDetails.builder().user(...)).
• RewardedTransactionAttributes.getStatus() — return type changed from RewardedTransactionStatus to String (hardcoded "SETTLED"); update variable declarations and switch/if logic that expected a RewardedTransactionStatus enum value.
• RewardedTransactionAttributes.getCardBin() and getCardLastFour() — these optional fields and their builder methods (cardBin(), cardLastFour()) are removed; delete all references to them.
• RewardedTransactionAttributes.Builder — the StatusStage entry point is removed; builder construction now begins at TransactionIdStage.
• RewardedTransactionUnion.Visitor — a new required method visitApprovedTransaction(ApprovedTransaction) has been added to the Visitor interface; all existing visitor implementations must add this method.

Added

• ApprovedTransaction and ApprovedTransactionAttributes — new types representing approved (non-settled) transactions with id, transactionId, transactionAmountInCents, and transactionTimestamp fields.
• RewardedTransactionUnion.approvedTransaction() — new factory method and getApprovedTransaction() accessor to construct and unwrap the new approvedTransaction union variant.

16.0.0 - 2026-04-17

Breaking Changes

• OrganizationsClient.get() / AsyncOrganizationsClient.get() — the organizationId parameter has been removed; the endpoint now resolves to v2/issuer automatically. Remove the organizationId argument from all call sites.
• ChildrenClient.create(), .get(), .update() (and async / raw variants) — return type changed from ExternalOrganizationResponse to ChildOrganizationResponse. Update variable declarations and type references accordingly.
• MerchantNetwork — public class removed with no replacement; delete any references or usages.
• MerchantNetworkName — public enum-like class removed with no replacement; delete any references or usages.

15.4.0 - 2026-04-16

Added

• MerchantAsset — new type representing a tracked asset image (logo, banner, etc.) for a merchant, with required type and url fields and an optional alt accessibility string.
• MerchantAssetType — new enum-like type with IMG_VIEW and BANNER_VIEW constants used with MerchantAsset, supporting a Visitor pattern for exhaustive handling.
• TransactionMerchantAttributes.getAssets() — new optional List<MerchantAsset> field exposing attribution-signed asset URLs; builder gains assets(List<MerchantAsset>) and assets(Optional<List<MerchantAsset>>) methods.

15.3.0 - 2026-04-16

Added

• ListPlacementsRequest.filterType() — new optional builder method to filter placements by type (placementMainPage or placementPushNotification) via the filter[type] query parameter.
• ListPlacementsRequest.filterName() — new optional builder method to filter placements by exact name (unique within an organization per type) via the filter[name] query parameter.
• PlacementTypeFilter — new enum type with PLACEMENT_MAIN_PAGE and PLACEMENT_PUSH_NOTIFICATION values used with filterType().

Changed

• PlacementsClient / AsyncPlacementsClient — HTTP 400 responses from the list endpoint now throw InvalidRequest instead of being silently unhandled.

15.2.0 - 2026-04-16

Added

• RewardsClient.placementOffers() / AsyncRewardsClient.placementOffers() — new sync and async methods (plus raw-response variants) that retrieve offers for a specific placement slot via GET /v2/issuers/{organizationId}/users/{userId}/placements/{placementId}/offers, returning results sorted by highest cash back and limited to the placement’s available slots.
• GetOffersByPlacementRequest — new request type for placementOffers() with optional filter parameters: filterSearch, filterPurchaseChannel, filterCategory, filterIsTargeted, include, and supportedComponents.

15.1.0 - 2026-04-16

Added

• KardApiClient.organizations() / AsyncKardApiClient.organizations() — new top-level accessors returning the new OrganizationsClient / AsyncOrganizationsClient for retrieving organization details.
• OrganizationsClient / AsyncOrganizationsClient — new sync and async clients (plus raw-response variants) for managing organizations via GET /v2/issuers/{organizationId}, including sub-client accessors children() and placements().
• ChildrenClient / AsyncChildrenClient — new sync and async clients (plus raw-response variants) for managing child (sub-issuer) organizations via v2/issuers/{organizationId}/children, exposing list(), create(), get(), update(), and delete() methods with cursor-based pagination via ListChildrenRequest.
• PlacementsClient / AsyncPlacementsClient — new sync and async clients (plus raw-response variants) for managing organization placements via v2/issuers/{organizationId}/placements, exposing list(), create(), get(), update(), and delete() methods with ListPlacementsRequest pagination support.
• New domain types — ExternalOrganizationResponse, ExternalOrganizationAttributes, ChildOrganizationListResponse, PlacementListResponse, PlacementFormatUnion, CreatePlacementDataUnion, UpdatePlacementDataUnion, Cadence, CadenceFrequency, DayOfWeek, and supporting request/response types across the organizations, organizations.children, and organizations.placements packages.

15.0.0 - 2026-04-16

Breaking Changes

• GetEarnedRewardsRequest.getFilterStatus() — now returns Optional<RewardedTransactionStatus> instead of Optional<String>; update any code that reads this value to use the enum type.
• GetEarnedRewardsRequest.Builder.filterStatus() — both overloads now accept RewardedTransactionStatus (or Optional<RewardedTransactionStatus>) instead of String; replace raw string literals such as "APPROVED" with RewardedTransactionStatus.APPROVED.

Changed

• GetEarnedRewardsRequest filterStatus documentation — clarifies that when APPROVED is specified, only approved transactions that do not yet have a corresponding settled transaction are returned.

14.0.0 - 2026-04-15

Breaking Changes

• GetEarnedRewardsResponse.Builder — links() now returns the new MetaStage interface instead of _FinalStage, inserting a mandatory .meta(GetEarnedRewardsMeta) call into every builder chain. Update all callsites from .links(l).build() to .links(l).meta(meta).build().
• RewardedTransactionStatus.Visitor — a new required visitApproved() method has been added to the Visitor<T> interface; any class implementing this interface must add the method or it will fail to compile.

Added

• GetEarnedRewardsMeta — new response type in com.kard.api.resources.transactions.types that carries lifetimeRewardsInCents, representing the lifetime rewards earned by a user across all matched transactions.
• GetEarnedRewardsResponse.getMeta() — returns the new GetEarnedRewardsMeta object embedded in every earned-rewards response.
• GetEarnedRewardsRequest.Builder.filterStatus() — new optional builder method that maps to the filter[status] query parameter; pass "APPROVED", "SETTLED", or a comma-separated combination to control which transaction statuses are returned (defaults to SETTLED when omitted).

13.2.0 - 2026-04-14

• [ADDED] Configurable SDK logging via the new LogConfig, LogLevel, ILogger, Logger, and ConsoleLogger types in com.kard.api.core. Pass a LogConfig to KardApiClientBuilder.logging(LogConfig) or AsyncKardApiClientBuilder.logging(LogConfig) to capture HTTP request/response activity at your desired level (DEBUG, INFO, WARN, ERROR). Logging is silent by default — no output is produced unless explicitly enabled. Supply a custom ILogger implementation to redirect output to any logging framework.
• [FIXED] Query-parameter getters on several request types (GetFilesMetadataRequest, GetEarnedRewardsRequest, GetLocationsByUserRequest, GetOffersByUserRequest, GetSubscriptionsRequest, ActivateOfferRequest, BoostOfferRequest) were annotated with @JsonProperty instead of @JsonIgnore. They are now correctly marked @JsonIgnore, preventing these fields from being unintentionally serialized into a request body.

13.1.0 - 2026-04-10

• GetEarnedRewardsRequest now supports an optional include parameter that accepts a comma-separated list of related resources (merchant, offer) to embed in the earned-rewards response. Pass the value via the builder with .include("merchant,offer") — existing builder chains require no changes.

13.0.0 - 2026-04-10

• The CardNetwork class has been moved from com.kard.api.resources.transactions.types to com.kard.api.resources.commons.types. Existing code that imports CardNetwork from the old package will fail to compile. Update all import statements from import com.kard.api.resources.transactions.types.CardNetwork; to import com.kard.api.resources.commons.types.CardNetwork;.

12.1.0 - 2026-04-07

• Two new types — AttributionState and AttributionFilter — are now available in the com.kard.api.resources.users.attributions.types package. NotificationAttributionAttributes and OfferAttributionAttributes each expose a new optional getState() method that returns placement context (offer rank and active filters) recorded at the time of the attribution event. Existing builder chains require no changes.

12.0.0 - 2026-04-07

• The getType() method on CreateFileUploadData and FileUploadUrlData now returns a FileUploadType enum instead of a hardcoded String. The new FileUploadType enum exposes constants INCOMING_TRANSACTIONS_FILE and HISTORICAL_TRANSACTIONS_FILE and a Visitor<T> interface for exhaustive handling. Additionally, type is now a required first step in both classes’ staged builders — code that calls CreateFileUploadData.builder().attributes(...) or FileUploadUrlData.builder().id(...) directly will fail to compile and must be updated to call .type(FileUploadType.INCOMING_TRANSACTIONS_FILE) (or the appropriate variant) first.

11.0.0 - 2026-04-06

• Four NotificationType constants — LOCATION, USER_OFFER, OFFER, and MERCHANT — have been removed, along with their corresponding Value enum entries and Visitor interface methods (visitLocation(), visitUserOffer(), visitOffer(), visitMerchant()). Any exhaustive visitor implementations or switch statements referencing these values must be updated. Additionally, the following public classes have been deleted: BrokerAmount, BrokerAmountType, BrokerAsset, BrokerAssetType, BrokerOperationHours, BrokerOperationPeriod, BrokerPurchaseChannel, and BrokerReward. Code that references any of these removed types will fail to compile and must be migrated accordingly.
• The offer, merchant, location, and userOffer variants have been removed from NotificationDataUnion. The corresponding factory methods (offer(), merchant(), location(), userOffer()), accessors (getOffer(), getMerchant(), getLocation(), getUserOffer()), type-check methods (isOffer(), isMerchant(), isLocation(), isUserOffer()), and Visitor interface methods (visitOffer(), visitMerchant(), visitLocation(), visitUserOffer()) have all been removed. Additionally, the public classes BrokerRewardType, LocationAddress, LocationCoordinates, LocationStatus, MerchantSource, OfferStatus, OfferType, and TimePeriod have been deleted. Existing code that references any of these APIs will fail to compile and must be updated.
• The UserOfferStatus, WebhookLocationsAttributes, WebhookLocationsData, and WebhookLocationsRelationships classes have been removed from the com.kard.api.resources.notifications.types package. Existing code that references any of these types will fail to compile and must be updated — remove all usages and consult the updated API documentation for any replacement types.
• The WebhookMerchantAttributes, WebhookMerchantData, and WebhookMerchantRelationships classes have been removed from the com.kard.api.resources.notifications.types package. Existing code that references these classes or their builder stage interfaces (such as MerchantIdStage, NameStage, AttributesStage, etc.) will fail to compile and must be updated. Review the updated API definition for replacement types to handle webhook merchant payloads.
• The WebhookOfferAttributes and WebhookOfferData classes have been removed from the SDK. Code that references either class — including their staged builder interfaces and getter methods — will fail to compile. Remove all usages of these types; replacement types may be introduced in a future release.
• The following public classes have been removed from the com.kard.api.resources.notifications.types package: WebhookOfferRelationships, WebhookUserOfferAttributes, WebhookUserOfferData, and WebhookUserOfferRelationships, along with all of their associated builder interfaces and getter methods. Existing code that references any of these types will fail to compile and must be updated to remove or replace those usages.

10.0.0 - 2026-04-03

• The getFinancialInstitutionName() method on CoreTransactionAttributes now returns Optional<String> instead of String. Existing code that calls this method without unwrapping the Optional will fail to compile and must be updated. Additionally, the FinancialInstitutionNameStage builder interface has been removed — financialInstitutionName is no longer a required builder step and is instead set via optional overloaded methods on _FinalStage. Builder chains that previously passed through FinancialInstitutionNameStage must be updated accordingly.

9.1.0 - 2026-04-02

• The CoreTransactionAttributes class now includes an optional financialInstitutionId field that provides a unique identifier for the financial institution. The existing financialInstitutionName field has been deprecated — consumers should migrate to financialInstitutionId going forward.

9.0.0 - 2026-03-30

• The cardLastFour field in CoreTransactionAttributes has been renamed to cardLastFours and changed from Optional<String> to Optional<List<String>>. This supports cases where multiple card candidates may be provided when the issuer cannot determine which specific card was used. Existing code accessing getCardLastFour() must be updated to use getCardLastFours() and handle the list type.

8.0.0 - 2026-03-27

• The xKardTargetIssuer configuration method has been moved from the main client builders (KardApiClientBuilder and AsyncKardApiClientBuilder) to the authentication builders. When using credential-based authentication, call xKardTargetIssuer() on the credentials builder returned by .credentials() instead of on the main client builder.

7.1.0 - 2026-03-25

• The CoreTransactionAttributes class now includes an optional cardLastFour field that provides the last four digits of the card used for the transaction.

7.0.0 - 2026-03-18

• Breaking Changes

• User operations now return UserResponseObject instead of UpdateUserObject. Update your variable types and field access patterns.

• Added

• UpdateUserRequestDataUnion type for enhanced user data operations.
• historicalTransactionsSent optional field when updating user attributes.

6.0.0 - 2026-03-18

• The ProgressBar API has been restructured with breaking changes. The segmentIcon field has been replaced with a segments configuration object. The ProgressBarLabel class has been renamed to ProgressBarSegment, and ProgressBarLabels now uses ProgressBarLabelPair objects instead of ProgressBarLabel. Update your code to use the new type names and field structures when working with progress bar configurations.

5.0.0 - 2026-03-17

• The ProgressBar class now includes a new required ‘labels’ field that enables configurable label placement for different layout views. Three new types are available: ProgressBarLabels (containing details and default view configurations), ProgressBarLabel (with text and position properties), and ProgressBarLabelPosition enum (supporting LEFT and RIGHT positions).

4.3.0 - 2026-03-17

• The ProgressBar type now includes an optional segmentIcon field for specifying custom SVG icons when the progress bar is segmented.

4.2.0 - 2026-03-16

• The SDK now supports configuring the X-Kard-Target-Issuer header through the client builders. Use the xKardTargetIssuer() method on KardApiClientBuilder or AsyncKardApiClientBuilder to set this header for all requests.

4.1.0 - 2026-03-16

• New ProgressBar component support added to offer rewards, allowing tracking of redemption progress with configurable display options including total count, current progress, labels, and segmented views.

4.0.0 - 2026-03-13

• The financialInstitutionName field in CoreTransactionAttributes has been changed from a custom enum type to a String. Existing code that uses FinancialInstitutionName constants or methods will need to be updated to use String values directly.

3.5.0 - 2026-03-13

• The SDK now supports metadata in offers API responses. The OffersResponseObject includes a new optional meta field that provides additional context about available categories across the entire filtered result set.

3.4.0 - 2026-03-09

• The GetOffersByUserRequest now supports filtering offers by merchant name using the new filterSearch parameter. Pass a case-insensitive search string to filter offers based on merchant names.

3.3.1 - 2026-03-09

• fix: correct API endpoint path for transaction uploads
• Update the transaction upload endpoint path from “transactions/upload” to
• “transactions/uploads” to match the correct API specification. This change
• affects both synchronous and asynchronous transaction clients.
• Key changes:
• Update endpoint path in AsyncRawTransactionsClient from upload to uploads
• Update endpoint path in RawTransactionsClient from upload to uploads
• Ensure consistency with server-side API expectations
• 🌿 Generated with Fern

3.3.0 - 2026-03-04

• feat: add logo flare component and secondary button style support
• This update introduces logo flare functionality for enhanced offer presentation and adds secondary button style support. The changes expand UI component customization capabilities while removing outdated component type documentation.
• Key changes:
• Add LogoFlare, LogoFlareBadge, and related position/color enums for offer logo customization
• Add SECONDARY button style option to ButtonStyle enum
• Add BOOSTED_REWARD and LOGO_FLARE component types to ComponentType enum
• Add boostedReward and logoFlare fields to OfferComponents
• Remove specific valid values documentation from supportedComponents parameter descriptions
• 🌿 Generated with Fern

3.2.0 - 2026-03-03

• feat: add bulk transactions file upload API endpoint
• Add new API endpoint for generating presigned URLs to upload JSONL transaction files directly to storage. This feature enables bulk transaction uploads with support for up to 10 files per request, each up to 5GB.
• Key changes:
• Add createBulkTransactionsUploadUrl method to transactions client
• Create new data types for file upload requests and responses
• Move ForbiddenError to commons errors package for reuse
• Add comprehensive documentation and usage examples
• Support for gzip-compressed files and 15-minute URL expiration
• 🌿 Generated with Fern

3.1.0 - 2026-03-03

• feat: add file processing result notification support
• This change extends the notification system to handle file processing results by introducing a new notification type and associated data structures. The implementation enables the API to properly communicate file processing outcomes to clients through the existing notification framework.
• Key changes:
• Add FILE_PROCESSING_RESULT notification type to NotificationType enum with visitor pattern support
• Create FileResultData class to encapsulate file processing notification data with ID and file metadata attributes
• Extend NotificationDataUnion to support file processing result notifications with serialization support
• Add optional errors field to NotificationPayload for improved error reporting in notifications
• 🌿 Generated with Fern

3.0.0 - 2026-03-03

• refactor: replace string-based financial institution name with enum type
• Replace the String-based financialInstitutionName field with a new FinancialInstitutionName enum type to provide better type safety and validation for transaction data. This change strengthens the API by preventing invalid financial institution names and provides a comprehensive list of supported institutions.
• Key changes:
• Create new FinancialInstitutionName enum with 33 predefined financial institution constants
• Update CoreTransactionAttributes field type from String to FinancialInstitutionName
• Implement visitor pattern for type-safe enum handling
• Add JSON serialization/deserialization support with fallback for unknown values
• Update all method signatures and builders to use the new enum type
• 🌿 Generated with Fern

2.1.0 - 2026-03-02

• feat: add startIcon property to CtaComponent
• Add optional startIcon field to the CtaComponent class to support displaying icons on buttons. This backward-compatible enhancement allows specifying an icon identifier that will be displayed on the button.
• Key changes:
• Add startIcon field as Optional<String> to CtaComponent
• Update constructor, builder methods, equals(), and hashCode() to include startIcon
• Add getter method with proper documentation
• Add builder methods for both Optional<String> and String variants
• 🌿 Generated with Fern

2.0.1 - 2026-02-27

• chore: update Fern CLI version to 3.93.2
• Updated the Fern CLI version from 3.79.2 to 3.93.2 in the project metadata. This update brings the latest improvements and bug fixes from the Fern CLI toolchain to the project build process.
• Key changes:
• Update cliVersion from 3.79.2 to 3.93.2 in .fern/metadata.json
• Maintain existing generator configuration and version
• Keep publish-to-central configuration unchanged
• 🌿 Generated with Fern

2.0.0 - 2026-02-27

• Initial release of the Java SDK.
• Provides core client functionality, authentication support, and documented usage examples to help you get started quickly.