> 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. ## 31.0.1 - 2026-10-06 * chore: update child organization name validation docs * Update Javadoc across all child organization clients and types to reflect * the revised name validation rule: names now require at least two letters * or numbers (previously at least one letter) and may contain letters, * numbers, and spaces (previously letters and spaces only). * Key changes: * Updated method-level Javadoc on `ChildrenClient.create()` and `AsyncChildrenClient.create()` overloads * Updated Javadoc on `RawChildrenClient.create()` and `AsyncRawChildrenClient.create()` overloads * Updated `@return` and builder Javadoc in `ChildOrganizationAttributes`, `CreateChildAttributes`, and `UpdateChildAttributes` * 🌿 Generated with Fern ## 31.0.0 - 2026-09-25 ### Breaking Changes * **`RejectedReason.Visitor`** — a new required method `visitMaxRedemptionLimitReached()` has been added to the visitor interface; all existing implementations must add this method or the code will not compile. ## 30.0.0 - 2026-09-21 ### Breaking Changes * **`RewardNotificationAttributes`** and **`IRewardNotificationAttributes`** — both the class and interface have been removed; delete all imports, instantiations, and implementations of these types. * **`EarnedRewardNotificationAttributes.getUserReward()`** and **`EarnedRewardSettledAttributes.getUserReward()`** — return type changed from `Optional` to `UserReward`; remove all `Optional` unwrapping (`.get()`, `.orElse()`, etc.) at call sites. * **`EarnedRewardNotificationAttributes.Builder`** and **`EarnedRewardSettledAttributes.Builder`** — a new mandatory `UserRewardStage` step is now required in the builder chain; insert a `.userReward(value)` call after `.transactionAmountInCents(...)` or the code will not compile. * **`_FinalStage.userReward(UserReward)`** and **`_FinalStage.userReward(Optional)`** — both overloads removed from `_FinalStage`; use `UserRewardStage.userReward(@NotNull UserReward)` instead. * **`EarnedRewardNotificationAttributes`**, **`EarnedRewardSettledAttributes`**, and **`IEarnedRewardNotificationAttributes`** — no longer implement or extend `IRewardNotificationAttributes`; update any casts, assignments, or interface hierarchies that relied on this relationship. ## 29.1.0 - 2026-09-15 ### Added * **`CreateStandardAttributes.getDisplayName()`** — new optional `Optional` field representing the cardholder-facing title for a placement section; set via `Builder.displayName(String)` or `Builder.displayName(Optional)`. * **`UpdateStandardAttributes.getDisplayName()`** — new optional `Optional` field for the cardholder-facing placement section title; omit to clear the value on PUT requests. * **`PlacementAttributes.getDisplayName()`** — new optional `Optional` field surfacing the stored cardholder-facing title on placement responses; absent when no display name was set. ## 29.0.1 - 2026-09-10 * chore: improve Javadoc for GetLocationsByUserRequest sort field * Expand the `getSort()` and `Builder.sort()` Javadoc to document the * default sort behavior and the distance-based ordering that applies when * latitude/longitude filters are provided. No public API surface changes. * Key changes: * `getSort()` Javadoc now describes the default sort order (descending `createdDate`) and the distance-first ordering when geo-filters are active * `Builder.sort()` Javadoc updated with the same clarifying detail * 🌿 Generated with Fern ## 29.0.0 - 2026-08-31 ### Breaking Changes * **`LocationAttributes.getPriceLevel()`** — return type changed from `Optional` to `Optional`; price level is now expressed as dollar-sign strings (`"$"` through `"$$$$"`) instead of integers 1–4. Update any code reading this field to handle `String` values. * **`LocationAttributes.Builder.priceLevel()`** — all three overloads (`priceLevel(Integer)`, `priceLevel(Optional)`, `priceLevel(Nullable)`) now require `String`, `Optional`, and `Nullable` respectively; update all builder call sites to pass string values. ## 28.0.0 - 2026-08-31 ### Breaking Changes * **`UsersClient.uploads()` and `AsyncUsersClient.uploads()`** — both methods have been removed; migrate to the transactions-level bulk upload endpoint. * **`UploadsClient`, `AsyncUploadsClient`, `RawUploadsClient`, and `AsyncRawUploadsClient`** — all uploads client classes (including `create()`, `createPart()`, and `update()` methods) have been deleted entirely; remove all direct references and replace with the bulk transactions upload flow. * **`UploadPartMultiStatus`** — exception class removed from `com.kard.api.resources.users.uploads.errors`; remove any catch blocks referencing this type. * **Upload request/response types** — `CreateUploadPartRequestObject`, `CreateUploadPartResponseObject`, `CreateUploadRequestObject`, `CreateUploadResponseObject`, `UpdateUploadRequestObject`, `UpdateUploadResponseObject`, and all associated `DataUnion`/`Visitor` types have been removed; delete all references and update upload workflow code to use the bulk upload API. * **`HistoricalTransactionCompleteNoData`, `StartHistoricalUploadNoData`, and `UpdateUploadResponseData`** — all three classes and their staged builders have been removed; delete any references in upload workflow code. ## 27.0.0 - 2026-08-27 ### Breaking Changes * **`FileType.VALIDATED_TRANSACTION_DAILY_RECONCILIATION_FILE`** — this public constant and its corresponding `Value` enum entry have been removed; replace any references with an alternative `FileType` value or handle it as an unknown type. * **`FileType.Visitor.visitValidatedTransactionDailyReconciliationFile()`** — this method has been removed from the `Visitor` interface; delete the implementation from any class that implements `FileType.Visitor`. ## 26.0.0 - 2026-08-25 ### Breaking Changes * **`getStatus()` on placement attribute types** — removed from `BatchActivationPlacementAttributes`, `GroupPlacementAttributes`, and `PlacementAttributes`; delete any calls to `.getStatus()` on these types. * **`StatusStage` interface removed from staged builders** — `BatchActivationPlacementAttributes.Builder`, `GroupPlacementAttributes.Builder`, and `PlacementAttributes.Builder` no longer implement `StatusStage`; drop the `.status(...)` call from any builder chain. * **`getStatus()` and `status()` builder methods removed from create/update attribute types** — removed from `CreateBatchActivationAttributes`, `CreateGroupAttributes`, `CreateStandardAttributes`, `UpdateBatchActivationAttributes`, `UpdateGroupAttributes`, and `UpdateStandardAttributes`; remove all `status(PlacementStatus)` and `status(Optional)` calls from request construction code. ### Changed * **`EmailPlacementAttributes.getStatus()` and `PushNotificationPlacementAttributes.getStatus()`** — Javadoc clarified that `INACTIVE` only pauses scheduled deliveries and has no effect on content serving. ## 25.0.0 - 2026-08-24 ### Breaking Changes * **Staged builders for all `*PlacementAttributes` response types** — a new required `StatusStage` is inserted between `NameStage` and `OrganizationIdStage` in `BatchActivationPlacementAttributes`, `EmailPlacementAttributes`, `GroupPlacementAttributes`, `PlacementAttributes`, and `PushNotificationPlacementAttributes`; existing chains of `.name(...).organizationId(...)` will no longer compile — insert `.status(PlacementStatus)` between the two calls. * **`getStatus()` on all `*PlacementAttributes` response types** — `PlacementStatus` is now a required field on `BatchActivationPlacementAttributes`, `EmailPlacementAttributes`, `GroupPlacementAttributes`, `PlacementAttributes`, and `PushNotificationPlacementAttributes`; deserialization of payloads missing this field will fail. ### Added * **`PlacementStatus`** — new enum type in `com.kard.api.resources.organizations.placements.types` representing a placement's lifecycle state (`ACTIVE` / `INACTIVE`) with full visitor-pattern support; an inactive placement retains its configuration but serves empty content and skips scheduled deliveries. * **`getStatus()` on all `Create*Attributes` and `Update*Attributes` types** — new optional `Optional` field added to `CreateBatchActivationAttributes`, `CreateEmailAttributes`, `CreateGroupAttributes`, `CreatePushNotificationAttributes`, `CreateStandardAttributes`, `UpdateBatchActivationAttributes`, `UpdateEmailAttributes`, `UpdateGroupAttributes`, `UpdatePushNotificationAttributes`, and `UpdateStandardAttributes`; defaults to `ACTIVE` on create and preserves the current status when omitted on update. * **`status(PlacementStatus)` and `status(Optional)` builder methods** — optional `_FinalStage` setters added to all `Create*Attributes` and `Update*Attributes` builder types. ## 24.1.0 - 2026-08-18 ### Added * **`LocationAttributes.getCuisine()`**, **`getRating()`**, and **`getPriceLevel()`** — new optional fields exposing cuisine category, customer rating, and price level (1–4) for a location. * **`LocationAttributes.Builder`** — new builder methods `cuisine()`, `rating()`, and `priceLevel()` supporting plain value, `Optional`, and `Nullable` overloads. * **`CuisineOption`** — new enum-like type in `com.kard.api.resources.commons.types` representing cuisine and venue categories (e.g. `PIZZA`, `SUSHI`, `BREWERY`, `MUSEUM`) with visitor-pattern and JSON support. * **`LocationRating`** — new type in `com.kard.api.resources.users.rewards.types` representing a location's customer rating with a required `getValue()` (1–5 scale) and optional `getCount()` for the number of ratings. ## 24.0.1 - 2026-08-07 * chore: update Javadoc for GetLocationsByUserRequest filter fields * Clarify the semantics of geographic filter parameters in the * `GetLocationsByUserRequest` class and trim redundant search-priority * notes from the `getLocations` endpoint Javadoc across all four rewards * client variants. * Key changes: * Add Javadoc to `getFilterCity()`, `getFilterZipCode()`, `getFilterState()`, `getFilterLongitude()`, `getFilterLatitude()`, and `getFilterRadius()` getters describing each field's role and constraints * Add matching Javadoc to the corresponding `Builder` setter methods (`filterCity()`, `filterZipCode()`, `filterState()`, `filterLongitude()`, `filterLatitude()`, `filterRadius()`) * Remove the outdated "Longitude and Latitude fields are prioritized over State, City and Zipcode" note from `getLocations` Javadoc in `RewardsClient`, `AsyncRewardsClient`, `RawRewardsClient`, and `AsyncRawRewardsClient` * 🌿 Generated with Fern ## 24.0.0 - 2026-08-05 ### Breaking Changes * **`ExternalOrganizationAttributes.getCardNetworks()`** — return type changed from `List` to `List`; update all call sites to use `OrganizationCardNetwork` from `com.kard.api.resources.internalorganizations.types`. * **`ExternalOrganizationAttributes` builder methods `cardNetworks()`, `addCardNetworks()`, and `addAllCardNetworks()`** — parameter types changed from `CardNetwork` to `OrganizationCardNetwork`; replace all usages with the new type. ### Added * **`OrganizationCardNetwork`** — new card network type in `com.kard.api.resources.internalorganizations.types` with values `VISA`, `MASTERCARD`, `AMERICAN_EXPRESS`, and `DISCOVER`, replacing the shared `CardNetwork` type for organization-scoped card network fields. ## 23.0.0 - 2026-08-05 ### Breaking Changes * **`ButtonStyle`, `CtaAction`, `CtaComponent`, `LogoFlare`, `LogoFlareBadge`, `LogoFlareBadgePosition`, `LogoFlareBorderColor`, `OfferComponents`, `ProgressBar`, `ProgressBarLabelPair`, `ProgressBarLabels`, `ProgressBarSegment`, `ProgressBarSegmentLabel`, `ProgressBarSegmentPosition`, `ProgressBarSegmentProgress`, `ProgressBarSegmentSelection`, `ProgressBarSegmentSeparator`, and `ProgressBarSegments`** — these classes have moved from `com.kard.api.resources.users.rewards.types` to `com.kard.api.resources.commons.types`; update all import statements to use the new package. ### Added * **`RewardedTransactionAttributes.getComponents()`** — new optional `OfferComponents` field exposing UI component data (e.g. progress bars for progressive and punch-card offers) on rewarded transactions; use the new `components()` builder method to set it. ## 22.0.0 - 2026-08-04 ### Breaking Changes * **`NotificationDataUnion` factory methods** — `validTransaction()`, `failedTransaction()`, and `clawback()` static factory methods have been removed; remove all call sites. * **`NotificationDataUnion` type-check and accessor methods** — `isValidTransaction()`, `isFailedTransaction()`, `isClawback()`, `getValidTransaction()`, `getFailedTransaction()`, and `getClawback()` have been removed; remove all call sites. * **`NotificationDataUnion.Visitor`** — `visitValidTransaction()`, `visitFailedTransaction()`, and `visitClawback()` have been removed from the interface; remove these implementations from all `Visitor` implementations. * **`ClawbackData`, `FailedTransactionData`, `FailedTransactionAttributes`, `FailedTransactionRelationships`** — classes have been deleted entirely; remove all usages. * **`TransactionRelationships`, `ValidTransactionAttributes`, `ValidTransactionCommissionEarned`, `ValidTransactionData`** — classes and their full staged builder APIs have been removed; remove all usages. ## 21.0.0 - 2026-08-04 ### Breaking Changes * **`MatchedTransactionsAttributes`** — class and its entire staged builder API (`UserIdStage`, `AmountStage`, `DescriptionStage`, `AuthorizationDateStage`, `PaymentTypeStage`, `DirectionStage`, `TransactionIdStage`, `_FinalStage`) have been removed; remove all usages. * **`MatchedTransactionsRequest`** — class has been removed; remove all usages. * **`PaymentType`** — enum and its `Visitor` interface have been removed; remove all references to `CARD`, `CASH`, `UNKNOWN`, and any `PaymentType.Visitor` implementations. * **`ReceiptMediumType`** — enum and its `Visitor` interface have been removed; remove all references to `PHYSICAL`, `ELECTRONIC`, and any `ReceiptMediumType.Visitor` implementations. * **`Transactions`** — `matchedTransaction()`, `isMatchedTransaction()`, `getMatchedTransaction()`, and `Visitor.visitMatchedTransaction()` have been removed; update all call sites and visitor implementations accordingly. ## 20.0.0 - 2026-08-03 ### Breaking Changes * **`NotificationType.FAILED_TRANSACTION`**, **`NotificationType.CLAWBACK`**, and **`NotificationType.VALID_TRANSACTION`** — these constants and their corresponding `Value` enum entries have been removed; any code referencing them will fail to compile. Remove all usages of these constants. * **`NotificationType.Visitor`** — the `visitFailedTransaction()`, `visitClawback()`, and `visitValidTransaction()` methods have been removed from the interface; any existing implementation that defines these methods will fail to compile. Remove those method implementations from all classes that implement `NotificationType.Visitor`. ## 19.0.0 - 2026-08-03 ### Breaking Changes * **`NotificationMedium.Visitor`** — new required `visitEmail()` method added to the `Visitor` interface; any existing implementation that does not add `visitEmail()` will fail to compile. Add a `visitEmail()` implementation to every class that implements `NotificationMedium.Visitor`. ### Added * **`NotificationMedium.EMAIL`** — new constant representing the email notification channel, available via `NotificationMedium.EMAIL` and handled by the new `visitEmail()` visitor method. ## 18.0.0 - 2026-07-29 ### Breaking Changes * **`EarnedRewardRejectedAttributes.getReason()`** — now returns `RejectedReason` instead of `String`; update any code that assigns or passes the result to a `String`-typed variable or parameter to use `RejectedReason` instead. * **`EarnedRewardRejectedAttributes.ReasonStage.reason()`** — builder method now accepts `RejectedReason` instead of `String`; replace string literals with the appropriate constant (e.g., `RejectedReason.USER_NOT_ENROLLED`). ### Added * **`RejectedReason`** — new strongly-typed enum in the commons package representing why a transaction did not result in a reward, with constants `USER_NOT_ENROLLED`, `AGGREGATOR_CARD_OVERLAP`, `USER_NOT_IN_AUDIENCE_SEGMENT`, and `SETTLEMENT_REJECTED`, plus a `Visitor` interface for exhaustive handling. ## 17.1.0 - 2026-07-28 ### Added * **`EarnedRewardsRange`** — new type representing the time window for rewarded transaction history, with constants `LAST_12_MONTHS`, `LAST_6_MONTHS`, `LAST_3_MONTHS`, and `YEAR_TO_DATE`, plus a `Visitor` interface for exhaustive handling. * **`GetEarnedRewardsRequest.getFilterRange()`** — new optional `filter[range]` parameter that narrows the transaction history window to the last 3 months (`3M`), last 6 months (`6M`), last 12 months (`12M`), or year to date (`YTD`); defaults to `12M` when omitted. * **`GetEarnedRewardsMeta.getLifetimeRewardsInCents()`** — documentation updated to clarify that the lifetime rewards total is now scoped to the window selected by `filter[range]`, so the meta total always matches the returned rows. ## 17.0.0 - 2026-07-15 ### Breaking Changes * **`ContentStrategyAttributes.OrganizationIdStage.organizationId()`** — now returns `FiltersStage` instead of `_FinalStage`; add a `.filters(ContentStrategyFilters)` call after `.organizationId(...)` in every builder chain. * **`CreateContentStrategyAttributes.NameStage.name()`** — now returns `FiltersStage` instead of `_FinalStage`; add a `.filters(ContentStrategyFilters)` call after `.name(...)` in every builder chain. * **`UpdateContentStrategyAttributes.NameStage.name()`** — now returns `FiltersStage` instead of `_FinalStage`; add a `.filters(ContentStrategyFilters)` call after `.name(...)` in every builder chain. ### Added * **`ContentStrategyFilters`** — new type holding optional `categories`, `categoryExclusions`, `merchantExclusions`, and `offerFeatures` lists used to filter offers selected for a content strategy. * **`OfferFeatures`** — new enum-like type (with `INTERACTIVE` constant and `Visitor` interface) representing offer feature flags that can be passed to `ContentStrategyFilters`. ## 16.0.0 - 2026-07-15 ### Breaking Changes * **`EarnedRewardApprovedData.getAttributes()`** — now returns `EarnedRewardNotificationAttributes` instead of `RewardNotificationAttributes`; update any code that assigns or passes the result to a `RewardNotificationAttributes`-typed variable or parameter. * **`EarnedRewardApprovedData.AttributesStage.attributes()`** — builder method now accepts `EarnedRewardNotificationAttributes` instead of `RewardNotificationAttributes`; update builder call sites accordingly. ### Added * **`EarnedRewardNotificationAttributes`** — new type implementing both `IEarnedRewardNotificationAttributes` and `IRewardNotificationAttributes`, carrying optional `categoryName`, `userReward`, `assets`, and `purchaseChannel` fields alongside all existing reward notification fields. * **`IEarnedRewardNotificationAttributes`** — new interface extending `IRewardNotificationAttributes` that exposes `getCategoryName()`, `getUserReward()`, `getAssets()`, and `getPurchaseChannel()` accessors. * **`EarnedRewardSettledAttributes`** — now implements `IEarnedRewardNotificationAttributes` and gains optional `categoryName`, `userReward`, `assets`, and `purchaseChannel` fields with corresponding builder methods. * **`UserReward`** — new type in the notifications package representing a user reward, exposing `getType()` (`CommissionType`) and `getValue()` (reward amount), with a staged builder for safe construction. ## 15.0.0 - 2026-07-15 ### Breaking Changes * **`NotificationType.Visitor`** — a new required `visitEarnedRewardRejected()` method has been added to the visitor interface. Any class implementing `NotificationType.Visitor` must add a `visitEarnedRewardRejected()` override or it will fail to compile. * **`NotificationDataUnion.Visitor`** — a new required `visitEarnedRewardRejected(EarnedRewardRejectedData)` method has been added to the visitor interface. Any class implementing `NotificationDataUnion.Visitor` must add a `visitEarnedRewardRejected()` override or it will fail to compile. ### Added * **`NotificationType.EARNED_REWARD_REJECTED`** — new enum constant representing the `earnedRewardRejected` notification type. * **`EarnedRewardRejectedAttributes`** — new type carrying the rejection reason code, display message, transaction ID, amount in cents, and optional transaction timestamp for a rejected earned reward. * **`EarnedRewardRejectedData`** and **`RejectedTransactionRelationships`** — new types representing the full notification data payload and its user/transaction relationships for rejected earned reward notifications. ## 14.0.0 - 2026-07-10 ### Breaking Changes * **`ContentStrategySort.Visitor`** — a new required `visitOffersNearYou()` method has been added to the visitor interface. Any class that implements `ContentStrategySort.Visitor` must now add a `visitOffersNearYou()` override or it will fail to compile. ### Added * **`ContentStrategySort.OFFERS_NEAR_YOU`** — new enum constant representing the `OFFERS_NEAR_YOU` content strategy sort option. ## 13.1.0 - 2026-07-02 ### Added * **`ProgressBarSegmentProgress`** — new type representing the fill state of a single progress bar segment, with `getCompleted()` and `getTotal()` accessors. * **`ProgressBarSegments.getProgress()`** — new field returning a `List` with one entry per segment node, index-aligned with the progress bar nodes; supports punch-card qualifying-purchase progress tracking. * **`ProgressBarSegments.Builder`** — new builder methods `progress()`, `addProgress()`, and `addAllProgress()` for populating the segment progress list. ## 13.0.1 - 2026-07-02 * chore: update filterSearch Javadoc to reflect expanded search behavior * The `filterSearch` field in `GetOffersByUserRequest` previously described * a search that filtered by merchant name only. The documentation has been * updated to accurately reflect that the search is a case-insensitive * substring match against both offer name and category name. * Key changes: * Updated `getFilterSearch()` Javadoc from "filter offers by merchant name" to "substring search on offer name or category name" * Updated `Builder.filterSearch()` Javadoc to match the same corrected description * 🌿 Generated with Fern ## 13.0.0 - 2026-06-29 ### Breaking Changes * **`OfferMedium.Visitor`** — a new required `visitPush()` method has been added to the visitor interface. Any class that implements `OfferMedium.Visitor` must now add a `visitPush()` override or it will fail to compile. ### Added * **`OfferMedium.PUSH`** — new enum constant representing the `PUSH` offer medium channel. ## 12.2.2 - 2026-06-23 * SDK regeneration * Unable to analyze changes with AI, incrementing PATCH version. ## 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` 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)` 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` to `List`; 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>` to `Optional>`; 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` field exposing slot-level visual assets (currently a single `IMG_VIEW` SVG showing the slot's initials). * **`BatchSlotData` builder** — new `components(OfferComponents)`, `components(Optional)`, `assets(List)`, and `assets(Optional>)` 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`**, **`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`. * **`GetBatchesByPlacementRequest`** — new request type with an optional `supportedComponents` field (`List`) to filter UI component types in the batch response. * **`BatchesResponseObject`** — new response wrapper type containing a `List` 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` that specifies the separator style to render between segment nodes. * **`ProgressBarSegment.getLabels()`** — new optional accessor returning `Optional>` for per-node label configuration on a progress bar segment. * **`ProgressBarSegment.getSelection()`** — new optional accessor returning `Optional` 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`. Update all call sites to use `getSort()`. * **`_FinalStage.filter(ContentStrategyFilter)`** and **`_FinalStage.filter(Optional)`** — removed from the builder interfaces of all three attributes types; replace with `sort(ContentStrategySort)` or `sort(Optional)`. * 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>` 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`. Update all call sites to use `getFilter()` and handle the `Optional` wrapper. * **`_FinalStage.filters(List)`**, **`addFilters()`**, and **`addAllFilters()`** — removed from all three attributes builder interfaces; replace with `filter(ContentStrategyFilter)` or `filter(Optional)`. * 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` 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>` to `List`; update all call sites to remove `Optional` unwrapping (an absent value is now represented as an empty list). * **`_FinalStage.partnerIds(Optional>)`** — the `Optional`-accepting builder overload is removed; replace calls with `partnerIds(List)`, `addPartnerIds(LocationPartnerId)`, or `addAllPartnerIds(List)`. ### 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` pattern for exhaustive handling of partner ID types. * **`LocationAttributes.getPartnerIds()`** — new optional `Optional>` field exposing partner IDs for LOCAL locations; builder gains `partnerIds(List)` and `partnerIds(Optional>)` 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)` methods. * **`EarnedRewardSettledAttributes.getTransactionTimestamp()`** — new optional `OffsetDateTime` field exposing the ISO-formatted timestamp of the originating transaction; builder gains `transactionTimestamp(OffsetDateTime)` and `transactionTimestamp(Optional)` 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` field exposing attribution-signed asset URLs; builder gains `assets(List)` and `assets(Optional>)` 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` instead of `Optional`; update any code that reads this value to use the enum type. * **`GetEarnedRewardsRequest.Builder.filterStatus()`** — both overloads now accept `RewardedTransactionStatus` (or `Optional`) 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` 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` 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` 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` to `Optional>`. 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` to CtaComponent * Update constructor, builder methods, equals(), and hashCode() to include startIcon * Add getter method with proper documentation * Add builder methods for both `Optional` 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.