For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Update create_bulk_transactions_upload_url docstring to document support for both incomingTransactionsFile and historicalTransactionsFile types, replacing the outdated coreTransaction-only note
Add deprecation notices to all UploadsClient and RawUploadsClient methods (create_upload, create_upload_part, update_upload) directing users to the bulk transactions upload URL endpoint
Apply deprecation notices consistently across sync and async variants in both client.py and raw_client.py
chore: update test fixture asset URLs and alt text in rewards response objects
Refresh the example asset data used in LocationsResponseObject and
OffersResponseObject type docstring/test fixtures. The placeholder
URLs and alt text strings are replaced with more realistic attribution
URLs and empty alt strings that better reflect real API responses.
Key changes:
Replace http://assets.getkard.com/logo/img?attribution-tokens with a realistic attribution URL in both LocationsResponseObject and OffersResponseObject fixtures
Replace http://assets.getkard.com/banner/img?attribution-tokens with a realistic banner attribution URL in both fixtures
Replace placeholder alt text (“Worlds Greatest Chicken Logo Image” / “Worlds Greatest Chicken Banner Image”) with empty strings
The organization_id required parameter is removed from
OrganizationsClient.get / AsyncOrganizationsClient.get and their
raw variants; the endpoint now calls v2/issuer (no path parameter).
Two new types — ChildOrganizationAttributes and
ChildOrganizationResponse — replace ExternalOrganizationResponse as
the return type for all ChildrenClient create/get/update methods.
Key changes:
Remove MerchantNetwork, MerchantNetworkName public types from kard.internal_organizations and top-level kard exports
Remove organization_id required positional parameter from OrganizationsClient.get / AsyncOrganizationsClient.get (and raw variants); URL changed from v2/issuers/{id} to v2/issuer
Add ChildOrganizationAttributes and ChildOrganizationResponse Pydantic models; all ChildrenClient methods now return ChildOrganizationResponse instead of ExternalOrganizationResponse
Remove multiple fields from ExternalOrganizationAttributes (external_id, parent_organization_id, merchant_networks, national_offers, local_offers, use_attribution, created_at, updated_at) and add new required commission-split fields
Minimum Python version — raised from 3.8 to 3.10; projects on Python 3.8 or 3.9 must upgrade before updating this SDK.
Added
KardApi / AsyncKardApi — new optional constructor parameters logging (LogConfig | Logger) and headers (Dict[str, str]) for structured request/response logging and per-client custom HTTP headers.
ParsingError — new exception (available at kard.core.parse_error.ParsingError, re-exported from kard.core) raised when a response cannot be deserialized into the expected schema; exposes headers, status_code, body, and cause attributes.
Logging framework — ILogger, ConsoleLogger, LogConfig, LogLevel, Logger, and create_logger are now available from kard.core for configuring structured logging with automatic redaction of sensitive headers.
BaseHttpResponse.status_code — new property for inspecting the HTTP status code without accessing the underlying httpx object.
DefaultAioHttpClient / DefaultAsyncHttpxClient — pre-configured async HTTP client classes now exported from the top-level kard package; DefaultAioHttpClient requires the optional aiohttp extra.
aiohttp transport extra — install with pip install kard-financial-sdk[aiohttp] to use an aiohttp-backed httpx transport.
Rfc2822DateTime / parse_rfc2822_datetime — new type and helper in kard.core.datetime_utils for deserializing RFC 2822 (email/HTTP header) date strings.
Changed
Retry behavior — the HTTP client now retries on connection-level errors (ConnectError, RemoteProtocolError) in addition to retryable HTTP status codes, using exponential backoff driven by a central base_max_retries setting (default: 2).
Fixed
Base-URL path prefix preservation — URL construction now uses string joining instead of urllib.parse.urljoin, correctly preserving path prefixes (e.g., https://host/org/tenant/api) when appending request paths.
Empty query parameter injection — HttpClient and AsyncHttpClient no longer forward an empty params list or dict to httpx, preventing inadvertent stripping of query parameters already embedded in a URL.
ParsingError on deserialization failure — Pydantic ValidationError raised during response parsing in the uploads and auth clients is now caught and re-raised as a structured ParsingError instead of bubbling up unhandled.
The get_earned_rewards method on TransactionsClient and AsyncTransactionsClient now accepts an optional include parameter. Pass a comma-separated string of related resources (supported values: "merchant" and "offer") to embed those resources directly in the response. Existing code that omits include continues to work without changes.
CardNetwork has been moved from kard.transactions / kard.transactions.types to kard.commons / kard.commons.types. The top-level import from kard import CardNetwork continues to work without changes. If your code imports CardNetwork directly from kard.transactions or kard.transactions.types, update those imports to use kard.commons or kard.commons.types instead.
The SDK now exposes two new types, AttributionFilter and AttributionState (available at kard.AttributionFilter and kard.AttributionState), that represent placement context for attribution events. An optional state field of type AttributionState has been added to both NotificationAttributionAttributes and OfferAttributionAttributes, providing access to the offer’s rank and the active filters at the time the user viewed it. Existing code is unaffected as the new field defaults to None.
The SDK now exposes a new FileUploadType type (available at kard.FileUploadType) that supports both "incomingTransactionsFile" and "historicalTransactionsFile" values. The type field on CreateFileUploadData and FileUploadUrlData has been widened from a hard-coded literal to this new union type, allowing consumers to create file upload URLs for historical transaction files in addition to incoming transaction files. Existing code that omits or hard-codes type="incomingTransactionsFile" continues to work without changes.
Several notification-related types have been removed from the SDK as they are no longer part of the API. The following public symbols are no longer available and must be removed from your code: BrokerAmount, BrokerAmountType, BrokerAsset, BrokerAssetType, BrokerOperationHours, BrokerOperationPeriod, BrokerPurchaseChannel, BrokerReward, BrokerRewardType, LocationAddress, LocationCoordinates, LocationStatus, MerchantSource, OfferStatus, OfferType, TimePeriod, UserOfferStatus, NotificationDataUnion_Offer, NotificationDataUnion_Merchant, NotificationDataUnion_Location, NotificationDataUnion_UserOffer, and all associated WebhookOffer*, WebhookMerchant*, WebhookLocations*, and WebhookUserOffer* types. The "offer", "merchant", "location", and "userOffer" variants have also been removed from the NotificationType union and NotificationDataUnion discriminated union.
Several public webhook notification types have been removed from the kard.notifications.types module: OfferType, TimePeriod, UserOfferStatus, WebhookLocationsAttributes, WebhookLocationsData, WebhookLocationsRelationships, WebhookMerchantAttributes, WebhookMerchantData, WebhookMerchantRelationships, WebhookOfferAttributes, WebhookOfferData, WebhookOfferRelationships, WebhookUserOfferAttributes, WebhookUserOfferData, and WebhookUserOfferRelationships. Any code that imports or references these classes will break and must be updated accordingly.
The deprecated financial_institution_name field in CoreTransactionAttributes is now optional (defaults to None), reflecting its deprecated status in favor of financial_institution_id. Existing code that reads this field continues to work without changes.
The SDK now exposes a unique identifier for the financial institution on transaction data. The new optional financial_institution_id field is available in CoreTransactionAttributes to replace the deprecated financial_institution name field. Existing code using financial_institution continues to work without changes.
The card_last_four field in CoreTransactionAttributes has been replaced with card_last_fours (now a list of strings) to support transactions where multiple cards may have been used. Update your code to handle the new list format when accessing card information from transaction data.
The SDK now supports issuer-specific authentication tokens. The x_kard_target_issuer parameter has moved from the global client configuration to the get_token() method, enabling partners managing multiple issuers to scope auth tokens to specific issuers on a per-request basis. Update your authentication code to pass the issuer ID when calling get_token() instead of during client initialization.
The SDK now includes the last four digits of the card used for transactions. The new card_last_four field is available in CoreTransactionAttributes to provide additional transaction context.
The SDK now provides specialized types for user update operations. New UpdateUserRequestAttributes includes additional fields for email, hashed_email, phone_number, and birth_year. User update and fetch methods now return UserResponseObject for improved type consistency.
The progress bar API has been restructured with breaking changes. The ProgressBarLabel and ProgressBarLabelPosition types have been removed and replaced with ProgressBarLabelPair which uses explicit left and right fields. The segment_icon field has been replaced with a new segments configuration using ProgressBarSegments type. Update imports and field references to use the new structure.
