openapi: 3.0.1 info: title: Kard Rewards API version: "2024-10-01" description: Kard Rewards API paths: /v2/issuers/{organizationId}/files/metadata: get: description: >- Retrieves metadata for files associated with a specific issuer/organization. This endpoint supports pagination and sorting options to efficiently navigate through potentially large sets of file metadata. Required scopes: `files.read` operationId: files_getMetadata tags: - Files parameters: - name: organizationId in: path required: true schema: $ref: '#/components/schemas/OrganizationId' - name: filter[dateFrom] in: query description: >- Start date for filtering files (format ISO8601). If not provided, defaults to current date minus 1 month. required: false schema: type: string nullable: true - name: filter[dateTo] in: query description: >- End date for filtering files (format ISO8601). If not provided, defaults to current date. required: false schema: type: string nullable: true - name: filter[fileType] in: query description: The document file type. required: false schema: $ref: '#/components/schemas/FileType' nullable: true - name: page[size] in: query description: >- Number of items per page. Defaults to 10 if not specified and maximum value allowed 100 items per page. required: false schema: type: integer nullable: true - name: page[after] in: query description: Cursor for forward pagination (next page). required: false schema: type: string nullable: true - name: page[before] in: query description: Cursor for backward pagination (previous page). required: false schema: type: string nullable: true - name: sort in: query description: >- If provided, response will be sorted by the specified fields. Defaults to descending sentDate, equivalent to "-sentDate" required: false schema: type: array items: $ref: '#/components/schemas/FilesMetadataSortOptions' nullable: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/GetFilesMetadataResponse' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get Files security: - BearerAuth: [] /v2/issuers/{organizationId}/notifications: get: description: |- Lists notifications previously dispatched to the issuer, most recent first. Results are filterable by event name, delivery status, and a `created_at` time range.
Required scopes: `notifications:read` operationId: notifications_notifications_list tags: - NotificationsNotifications parameters: - name: organizationId in: path required: true schema: $ref: '#/components/schemas/OrganizationId' - name: page[after] in: query description: >- Represents a cursor value, and if provided, returns the next page of results required: false schema: type: string nullable: true - name: page[before] in: query description: >- Represents a cursor value, and if provided, returns the previous page of results required: false schema: type: string nullable: true - name: page[size] in: query description: Maximum number of records to be returned [1 - 200], (default = 200) required: false schema: type: integer nullable: true - name: filter[eventName] in: query description: Return only notifications for this event name. required: false schema: $ref: '#/components/schemas/NotificationType' nullable: true - name: filter[status] in: query description: Return only notifications with this delivery status. required: false schema: $ref: '#/components/schemas/notificationsDeliveryStatus' nullable: true - name: filter[transactionId] in: query description: >- Return only notifications carrying this network transaction id. Matches the `transactionId` attribute exactly. Several notifications can describe the same purchase, so more than one may be returned. required: false schema: type: string nullable: true - name: filter[after] in: query description: >- Return only notifications created strictly after this timestamp (ISO 8601). required: false schema: type: string format: date-time nullable: true - name: filter[before] in: query description: >- Return only notifications created strictly before this timestamp (ISO 8601). required: false schema: type: string format: date-time nullable: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/notificationsNotificationsListResponse' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: List Notifications security: - BearerAuth: [] post: description: >- Sends a simulated earned-reward notification to the issuer's configured webhook for the given event, without requiring a real transaction. Provide the `userId` and `transactionId` to include in the simulated transaction; offer information is sourced from an existing offer in sandbox, so the payload matches a production notification and is HMAC-signed like any other. A fresh `eventId` is generated on each call, so the triggered notification is listable and replayable just like a real one. Returns `409` when the issuer has no enabled subscription for the requested event. Sandbox environment only. This endpoint is available only in Kard's test (sandbox) environment. It does not exist in production.
Required scopes: `notifications:write` operationId: notifications_notifications_trigger tags: - NotificationsNotifications parameters: - name: organizationId in: path required: true schema: $ref: '#/components/schemas/OrganizationId' responses: '202': description: '' content: application/json: schema: $ref: '#/components/schemas/notificationsTriggerNotificationResponse' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Simulate Test Notification security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/notificationsTriggerNotificationRequestBody' /v2/issuers/{organizationId}/notifications/{eventId}/replay: post: description: |- Re-enqueues a previously dispatched notification so it is redelivered to the issuer's currently configured webhook for that event. Returns 409 when the issuer has no enabled subscription for the event.
Required scopes: `notifications:write` operationId: notifications_notifications_replay tags: - NotificationsNotifications parameters: - name: organizationId in: path required: true schema: $ref: '#/components/schemas/OrganizationId' - name: eventId in: path description: The event ID of the notification to replay. required: true schema: type: string format: uuid responses: '202': description: '' content: application/json: schema: $ref: '#/components/schemas/notificationsReplayNotificationResponse' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Replay Notification security: - BearerAuth: [] /v2/issuers/{organizationId}/subscriptions: get: description: >- Call this endpoint to fetch the subscriptions of the provided issuer.
Required scopes: `notifications:read` operationId: notifications_subscriptions_get tags: - NotificationsSubscriptions parameters: - name: organizationId in: path required: true schema: $ref: '#/components/schemas/OrganizationId' - name: filter[eventName] in: query required: false schema: $ref: '#/components/schemas/NotificationType' nullable: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/notificationsSubscriptionsResponseObject' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get Subscriptions security: - BearerAuth: [] post: description: |- Call this endpoint to subscribe to notification events.
Required scopes: `notifications:write` operationId: notifications_subscriptions_create tags: - NotificationsSubscriptions parameters: - name: organizationId in: path required: true schema: $ref: '#/components/schemas/OrganizationId' responses: '201': description: '' content: application/json: schema: $ref: >- #/components/schemas/notificationsCreateSubscriptionsResponseObject '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Create Subscription security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/notificationsSubscriptionRequestBody' /v2/issuers/{organizationId}/subscriptions/{subscriptionId}: patch: description: |- Call this endpoint to update existing notification subscriptions.
Required scopes: `notifications:write` operationId: notifications_subscriptions_update tags: - NotificationsSubscriptions parameters: - name: organizationId in: path required: true schema: $ref: '#/components/schemas/OrganizationId' - name: subscriptionId in: path required: true schema: $ref: '#/components/schemas/SubscriptionId' responses: '200': description: '' content: application/json: schema: $ref: >- #/components/schemas/notificationsUpdateSubscriptionsResponseObject '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Update Subscription security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/notificationsUpdateSubscriptionRequestBody' /v2/issuer: get: description: Retrieve organization details for the authenticated issuer operationId: organizations_get tags: - Organizations parameters: [] responses: '200': description: Organization resource with limited attributes content: application/json: schema: $ref: '#/components/schemas/ExternalOrganizationResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] /v2/issuers/{organizationId}/children: get: description: List child organizations belonging to the authenticated issuer operationId: organizations_children_list tags: - OrganizationsChildren parameters: - name: organizationId in: path description: Unique identifier of the parent organization required: true schema: type: string - name: page[after] in: query description: Cursor value for the next page of results required: false schema: type: string nullable: true - name: page[size] in: query description: Maximum number of records to return [1 - 200] (default = 200) required: false schema: type: integer nullable: true responses: '200': description: Paginated list of child organizations content: application/json: schema: $ref: >- #/components/schemas/organizationsChildOrganizationListResponse '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] post: description: >- Create a child organization by cloning the parent and overriding specified fields. An 8-digit numeric ID is generated automatically. The name is required, must contain at least one letter, and may contain only letters and spaces. operationId: organizations_children_create tags: - OrganizationsChildren parameters: - name: organizationId in: path description: Unique identifier of the parent organization required: true schema: type: string responses: '201': description: Created child organization resource content: application/json: schema: $ref: '#/components/schemas/organizationsChildOrganizationResponse' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] requestBody: description: Child organization data for creation required: true content: application/json: schema: $ref: '#/components/schemas/organizationsCreateChildRequestBody' /v2/issuers/{organizationId}/children/{childId}: get: description: Retrieve a specific child organization operationId: organizations_children_get tags: - OrganizationsChildren parameters: - name: organizationId in: path description: Unique identifier of the parent organization required: true schema: type: string - name: childId in: path description: Unique identifier of the child organization required: true schema: type: string responses: '200': description: Child organization resource content: application/json: schema: $ref: '#/components/schemas/organizationsChildOrganizationResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] patch: description: Update a child organization. Only the name can be changed. operationId: organizations_children_update tags: - OrganizationsChildren parameters: - name: organizationId in: path description: Unique identifier of the parent organization required: true schema: type: string - name: childId in: path description: Unique identifier of the child organization required: true schema: type: string responses: '200': description: Updated child organization resource content: application/json: schema: $ref: '#/components/schemas/organizationsChildOrganizationResponse' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] requestBody: description: Child organization data for update required: true content: application/json: schema: $ref: '#/components/schemas/organizationsUpdateChildRequestBody' delete: description: Delete a child organization operationId: organizations_children_delete tags: - OrganizationsChildren parameters: - name: organizationId in: path description: Unique identifier of the parent organization required: true schema: type: string - name: childId in: path description: Unique identifier of the child organization required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/DeleteResourceResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] /v2/issuers/{organizationId}/contentStrategies: post: description: >- Create a content strategy for the organization. The strategy name must be unique within the organization. operationId: organizations_contentStrategies_create tags: - OrganizationsContentStrategies parameters: - name: organizationId in: path description: Unique identifier of the organization required: true schema: type: string responses: '201': description: Created content strategy resource content: application/json: schema: $ref: '#/components/schemas/organizationsContentStrategyResponse' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] requestBody: description: Content strategy data for creation required: true content: application/json: schema: $ref: >- #/components/schemas/organizationsCreateContentStrategyRequestBody get: description: List content strategies belonging to the authenticated organization operationId: organizations_contentStrategies_list tags: - OrganizationsContentStrategies parameters: - name: organizationId in: path description: Unique identifier of the organization required: true schema: type: string - name: filter[name] in: query description: >- Filter by exact content strategy name (unique within an organization) required: false schema: type: string nullable: true - name: page[after] in: query description: Cursor value for the next page of results required: false schema: type: string nullable: true - name: page[size] in: query description: Maximum number of records to return [1 - 200] (default = 200) required: false schema: type: integer nullable: true responses: '200': description: Paginated list of content strategies content: application/json: schema: $ref: '#/components/schemas/organizationsContentStrategyListResponse' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] /v2/issuers/{organizationId}/contentStrategies/{contentStrategyId}: get: description: Retrieve a specific content strategy operationId: organizations_contentStrategies_get tags: - OrganizationsContentStrategies parameters: - name: organizationId in: path description: Unique identifier of the organization required: true schema: type: string - name: contentStrategyId in: path description: Unique identifier of the content strategy (UUID v7) required: true schema: type: string responses: '200': description: Content strategy resource content: application/json: schema: $ref: '#/components/schemas/organizationsContentStrategyResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] put: description: >- Replace a content strategy. All fields must be provided; any omitted attribute is treated as cleared. operationId: organizations_contentStrategies_update tags: - OrganizationsContentStrategies parameters: - name: organizationId in: path description: Unique identifier of the organization required: true schema: type: string - name: contentStrategyId in: path description: Unique identifier of the content strategy (UUID v7) required: true schema: type: string responses: '200': description: Updated content strategy resource content: application/json: schema: $ref: '#/components/schemas/organizationsContentStrategyResponse' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] requestBody: description: Content strategy data for update required: true content: application/json: schema: $ref: >- #/components/schemas/organizationsUpdateContentStrategyRequestBody delete: description: >- Delete a content strategy. Returns 409 if the strategy is still referenced by another resource. operationId: organizations_contentStrategies_delete tags: - OrganizationsContentStrategies parameters: - name: organizationId in: path description: Unique identifier of the organization required: true schema: type: string - name: contentStrategyId in: path description: Unique identifier of the content strategy (UUID v7) required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/DeleteResourceResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] /v2/issuers/{organizationId}/placements: post: description: >- Create a placement for the organization. Use type "placement" for standard placements (requires name and availableSlots), "placementPushNotification" for push-notification placements (requires name and cadence; availableSlots is automatically set to 1), "placementEmail" for email placements (requires name, cadence, and availableSlots), "placementBatchActivation" for batch-activation placements (requires name, refreshInterval, and slots), or "placementGroup" for group placements (requires name and slots). operationId: organizations_placements_create tags: - OrganizationsPlacements parameters: - name: organizationId in: path description: Unique identifier of the organization required: true schema: type: string responses: '201': description: Created placement resource content: application/json: schema: $ref: '#/components/schemas/organizationsPlacementFormatUnion' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] requestBody: description: Placement data for creation required: true content: application/json: schema: $ref: '#/components/schemas/organizationsCreatePlacementRequestBody' get: description: List placements belonging to the authenticated organization operationId: organizations_placements_list tags: - OrganizationsPlacements parameters: - name: organizationId in: path description: Unique identifier of the organization required: true schema: type: string - name: filter[type] in: query description: >- Filter by placement type (placement, placementPushNotification, placementEmail, placementBatchActivation, or placementGroup) required: false schema: $ref: '#/components/schemas/organizationsPlacementTypeFilter' nullable: true - name: filter[name] in: query description: >- Filter by exact placement name (unique within an organization per type) required: false schema: type: string nullable: true - name: filter[contentStrategyId] in: query description: Filter by the ID of the content strategy linked to the placement required: false schema: type: string nullable: true - name: include in: query description: >- CSV list of related resources to embed in the `included` array. Supported paths: `contentStrategy` (the direct content strategy of a non-batch placement), `slots` (the slot resources of a batch-activation or group placement), `slots.placement` (and the placement each slot references), and `slots.placement.contentStrategy` (and the content strategy of each referenced placement). Dotted paths implicitly include all intermediate resources. required: false schema: type: string nullable: true - name: page[after] in: query description: Cursor value for the next page of results required: false schema: type: string nullable: true - name: page[size] in: query description: Maximum number of records to return [1 - 200] (default = 200) required: false schema: type: integer nullable: true responses: '200': description: Paginated list of placements content: application/json: schema: $ref: '#/components/schemas/organizationsPlacementListResponse' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] /v2/issuers/{organizationId}/placements/{placementId}: get: description: Retrieve a specific placement operationId: organizations_placements_get tags: - OrganizationsPlacements parameters: - name: organizationId in: path description: Unique identifier of the organization required: true schema: type: string - name: placementId in: path description: Unique identifier of the placement (UUID v7) required: true schema: type: string - name: include in: query description: >- CSV list of related resources to embed in the `included` array. Supported paths: `contentStrategy` (the direct content strategy of a non-batch placement), `slots` (the slot resources of a batch-activation or group placement), `slots.placement` (and the placement each slot references), and `slots.placement.contentStrategy` (and the content strategy of each referenced placement). Dotted paths implicitly include all intermediate resources. required: false schema: type: string nullable: true responses: '200': description: Placement resource (optionally with embedded related resources) content: application/json: schema: $ref: '#/components/schemas/organizationsPlacementResource' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] put: description: >- Replace a placement. All fields must be provided. Use type "placement", "placementPushNotification", "placementEmail", "placementBatchActivation", or "placementGroup" to set the placement kind. If the type is "placementPushNotification", availableSlots is automatically set to 1. operationId: organizations_placements_update tags: - OrganizationsPlacements parameters: - name: organizationId in: path description: Unique identifier of the organization required: true schema: type: string - name: placementId in: path description: Unique identifier of the placement (UUID v7) required: true schema: type: string responses: '200': description: Updated placement resource content: application/json: schema: $ref: '#/components/schemas/organizationsPlacementFormatUnion' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] requestBody: description: Placement data for update required: true content: application/json: schema: $ref: '#/components/schemas/organizationsUpdatePlacementRequestBody' delete: description: Delete a placement operationId: organizations_placements_delete tags: - OrganizationsPlacements parameters: - name: organizationId in: path description: Unique identifier of the organization required: true schema: type: string - name: placementId in: path description: Unique identifier of the placement (UUID v7) required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/DeleteResourceResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] /v2/ping: get: description: >- Call this endpoint to verify network connectivity and service availability. operationId: ping_ping tags: - Ping parameters: [] responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/PingResponseObject' '403': description: '' content: application/json: schema: $ref: '#/components/schemas/NetworkBlockedErrorBody' /v2/issuers/{organizationId}/transactions: post: description: >- Call this endpoint to send all transactions made by all your enrolled users in your rewards program. The request body will depend on the transaction type.
Please use the correct type when calling the endpoint: - `transaction`: These incoming transactions will be processed and matched by the Kard system. Learn more about the [Transaction CLO Matching](https://github.com/kard-financial/kard-postman#c-transaction-clo-matching) flow here. - `coreTransaction`: For transactions from core banking systems with limited card-level data.
Required scopes: `transaction:write`
Note: `Maximum of 500 transactions can be created per request`. operationId: transactions_create tags: - Transactions parameters: - name: organizationId in: path required: true schema: $ref: '#/components/schemas/OrganizationId' responses: '202': description: '' content: application/json: schema: $ref: '#/components/schemas/TransactionsResponse' '207': description: '' content: application/json: schema: $ref: '#/components/schemas/TransactionsMultiResponse' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Create Incoming Transactions security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TransactionsRequestBody' /v2/issuers/{organizationId}/users/{userId}/audits: post: description: >- Call this endpoint to request that a particular transaction be audited further by the Kard system, in the event of a missing cashback claim, incorrect cashback amount claim or other mis-match claims.
Required scopes: `audit:write` operationId: transactions_createAudits tags: - Transactions parameters: - name: organizationId in: path required: true schema: $ref: '#/components/schemas/OrganizationId' - name: userId in: path description: The ID of the user as defined on the issuers system required: true schema: type: string responses: '201': description: '' content: application/json: schema: $ref: '#/components/schemas/CreateAuditResponseBody' '207': description: '' content: application/json: schema: $ref: '#/components/schemas/CreateAuditMultiStatusResponse' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAuditRequestBody' /v2/issuers/{organizationId}/transactions/uploads: post: description: >- Generates up to 10 presigned PUT URLs for uploading JSONL transaction files (up to 5GB each) directly to storage. Each URL is valid for 15 minutes. Use the returned URL to upload the file via an HTTP PUT request with the binary file content as the body. If a URL expires before the upload completes, you must request a new one. Files can be uploaded as plain JSONL or as a gzip-compressed file. Supports both `incomingTransactionsFile` for daily transaction ingestion and `historicalTransactionsFile` for historical transaction ingestion. See the [Historical Transaction Uploads](/2024-10-01/api/integration-guides/historical-transaction-uploads) integration guide for details on the historical flow. Required scopes: `files:write` operationId: transactions_createBulkTransactionsUploadUrl tags: - Transactions parameters: - name: organizationId in: path required: true schema: $ref: '#/components/schemas/OrganizationId' responses: '201': description: '' content: application/json: schema: $ref: '#/components/schemas/CreateFileUploadUrlResponse' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Create Bulk Transactions Upload URL security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateFileUploadRequestBody' /v2/issuers/{organizationId}/users/{userId}/earned-rewards: get: description: >- Retrieve rewarded transaction history for a specific user. By default this returns only SETTLED transactions within the last 12 months regardless of payment status. Pass `filter[range]` to narrow the window to the last 6 months (`6M`), last 3 months (`3M`), or year to date (`YTD`). Pass `filter[paidInFullOnly]=true` to restrict the response to matched transactions that have been paid in full to the issuer (`paidToIssuer` is `PAID_IN_FULL`).
Required scopes: `transaction:read`
Query Limit: Maximum of 12 months of transaction data can be queried. operationId: transactions_GetEarnedRewards tags: - Transactions parameters: - name: organizationId in: path required: true schema: $ref: '#/components/schemas/OrganizationId' - name: userId in: path description: The ID of the user as defined on the issuers system required: true schema: type: string - name: page[after] in: query description: Cursor for next page (base64-encoded timestamp + transaction ID) required: false schema: type: string nullable: true - name: page[before] in: query description: Cursor for previous page (base64-encoded timestamp + transaction ID) required: false schema: type: string nullable: true - name: page[size] in: query description: Number of results per page required: false schema: type: integer nullable: true - name: filter[status] in: query description: >- Filter by transaction status. Supported values are `APPROVED` and `SETTLED`. Defaults to `SETTLED` when omitted. When `APPROVED` is specified, only approved transactions that do not yet have a corresponding settled transaction are returned. required: false schema: $ref: '#/components/schemas/RewardedTransactionStatus' nullable: true - name: filter[paidInFullOnly] in: query description: >- When `true`, only return transactions that have been paid in full to the issuer (`paidToIssuer` is `PAID_IN_FULL`). By default (`false`), any matched transaction is returned regardless of payment status. This also controls whether unpaid transactions contribute to `lifetimeRewardsInCents`. Has no effect on `APPROVED` transactions, which are always returned when requested. required: false schema: type: boolean nullable: true - name: filter[range] in: query description: >- Time window for the returned transactions, ending now. Supported values are `12M`, `6M`, `3M`, and `YTD` (since January 1 of the current year). Defaults to `12M` when omitted. Also scopes `lifetimeRewardsInCents`, so the meta total always matches the returned rows. required: false schema: $ref: '#/components/schemas/EarnedRewardsRange' nullable: true - name: include in: query description: >- Comma-separated list of related resources to include in the response. Supported values are `merchant` and `offer`. required: false schema: type: string nullable: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/GetEarnedRewardsResponse' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] /v2/issuers/{organizationId}/users: post: description: >- Call this endpoint to enroll a specified user into your rewards program.
Required scopes:  `user:write`
Note: `Maximum of 100 users can be created per request`. operationId: users_create tags: - Users parameters: - name: organizationId in: path required: true schema: $ref: '#/components/schemas/OrganizationId' responses: '201': description: '' content: application/json: schema: $ref: '#/components/schemas/CreateUsersObject' '207': description: '' content: application/json: schema: $ref: '#/components/schemas/CreateUsersMultiStatusResponse' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Create Users security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateUsersObject' /v2/issuers/{organizationId}/users/{userId}: put: description: |- Call this endpoint to update the details on a specified user.
Required scopes: `user:update` operationId: users_update tags: - Users parameters: - name: organizationId in: path required: true schema: $ref: '#/components/schemas/OrganizationId' - name: userId in: path required: true schema: $ref: '#/components/schemas/UserId' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/UserResponseObject' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Update User security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateUserObject' delete: description: >- Call this endpoint to delete a specified enrolled user from the rewards program and Kard's system. Users can be re-enrolled into rewards by calling the [Create User](/2024-10-01/api/users/create) endpoint using the same `id` from before.
Required scopes: `user:delete` operationId: users_delete tags: - Users parameters: - name: organizationId in: path required: true schema: $ref: '#/components/schemas/OrganizationId' - name: userId in: path required: true schema: $ref: '#/components/schemas/UserId' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/DeleteUserResponseObject' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Delete User security: - BearerAuth: [] get: description: |- Call this endpoint to fetch the details on a specified user.

Required scopes:  `user:read` operationId: users_get tags: - Users parameters: - name: organizationId in: path required: true schema: $ref: '#/components/schemas/OrganizationId' - name: userId in: path required: true schema: $ref: '#/components/schemas/UserId' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/UserResponseObject' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get User By ID security: - BearerAuth: [] /v2/issuers/{organizationId}/users/{userId}/attributions: post: description: >- Call this endpoint to send attribution events made by a single enrolled user for processing. A maximum of 100 events can be included in a single request. Required scopes: `attributions:write` operationId: users_attributions_create tags: - UsersAttributions parameters: - name: organizationId in: path required: true schema: $ref: '#/components/schemas/OrganizationId' - name: userId in: path required: true schema: $ref: '#/components/schemas/UserId' responses: '202': description: '' content: application/json: schema: $ref: '#/components/schemas/usersCreateAttributionResponse' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Create Attribution Events security: - BearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/usersCreateAttributionRequestObject' /v2/issuers/{organizationId}/users/{userId}/offers/{offerId}/activate: post: description: >- Record when a user activates an offer. Creates an attribution event with eventCode=ACTIVATE and medium=CTA. Optionally include the offer data by passing `include=offer`. operationId: users_attributions_activate tags: - UsersAttributions parameters: - name: organizationId in: path required: true schema: $ref: '#/components/schemas/OrganizationId' - name: userId in: path required: true schema: $ref: '#/components/schemas/UserId' - name: offerId in: path description: The unique identifier of the offer being activated required: true schema: type: string - name: supportedComponents in: query description: >- UI component types to include in the offer response (when include=offer). required: false schema: type: array items: $ref: '#/components/schemas/usersComponentType' nullable: true - name: include in: query description: >- Related resources to include in the response. Allowed value is `offer`. required: false schema: type: array items: $ref: '#/components/schemas/usersActivateOfferIncludeOption' nullable: true responses: '201': description: '' content: application/json: schema: $ref: '#/components/schemas/usersActivateOfferResponse' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Activate Offer security: - BearerAuth: [] /v2/issuers/{organizationId}/users/{userId}/offers/{offerId}/boost: post: description: >- Record when a user boosts an offer. Creates an attribution event with eventCode=BOOST and medium=CTA. Optionally include the offer data by passing `include=offer`. operationId: users_attributions_boost tags: - UsersAttributions parameters: - name: organizationId in: path required: true schema: $ref: '#/components/schemas/OrganizationId' - name: userId in: path required: true schema: $ref: '#/components/schemas/UserId' - name: offerId in: path description: The unique identifier of the offer being boosted required: true schema: type: string - name: supportedComponents in: query description: >- UI component types to include in the offer response (when include=offer). required: false schema: type: array items: $ref: '#/components/schemas/usersComponentType' nullable: true - name: include in: query description: >- Related resources to include in the response. Allowed value is `offer`. required: false schema: type: array items: $ref: '#/components/schemas/usersBoostOfferIncludeOption' nullable: true responses: '201': description: '' content: application/json: schema: $ref: '#/components/schemas/usersBoostOfferResponse' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Boost Offer security: - BearerAuth: [] /v2/issuers/{organizationId}/users/{userId}/placements/{placementId}/slot/{slotId}/activate: post: description: >- Record when a user activates a batch-activation placement slot. Writes a slot-level `placementSlotAttribution` ACTIVATE event and fans out a per-offer `offerAttribution` ACTIVATE event for every offer resolved by the slot's content strategy. The slot-level event id and the resolved `offerIds` are returned so the partner can render the batch immediately without an extra round-trip to re-fetch the placement content. Required scopes: `attributions:write` operationId: users_attributions_activatePlacementSlot tags: - UsersAttributions parameters: - name: organizationId in: path required: true schema: $ref: '#/components/schemas/OrganizationId' - name: userId in: path required: true schema: $ref: '#/components/schemas/UserId' - name: placementId in: path description: Unique identifier of the placement (UUID v7) required: true schema: type: string - name: slotId in: path description: Stable identifier for the slot within the placement required: true schema: type: string responses: '201': description: '' content: application/json: schema: $ref: '#/components/schemas/usersActivatePlacementSlotResponse' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Activate Placement Slot security: - BearerAuth: [] /v2/auth/issuers/{organizationId}/users/{userId}/token: post: description: Retrieves an OAuth token for webview authentication. operationId: users_auth_getWebViewToken tags: - UsersAuth parameters: - name: organizationId in: path required: true schema: $ref: '#/components/schemas/OrganizationId' - name: userId in: path required: true schema: $ref: '#/components/schemas/UserId' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/usersWebViewTokenResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get WebView Token security: - BearerAuth: [] /v2/issuers/{organizationId}/users/{userId}/offers: get: description: >- Retrieve national brand offers that a specified user is eligible for. Call this endpoint to build out your [targeted offers UX experience](/2024-10-01/api/getting-started#b-discover-a-lapsed-customer-clo). Local offers details can be found by calling the [Get Eligible Locations](/2024-10-01/api/rewards/locations).
Required scopes: `rewards:read` operationId: users_rewards_offers tags: - UsersRewards parameters: - name: organizationId in: path required: true schema: $ref: '#/components/schemas/OrganizationId' - name: userId in: path required: true schema: $ref: '#/components/schemas/UserId' - name: page[size] in: query required: false schema: type: integer nullable: true - name: page[after] in: query required: false schema: type: string nullable: true - name: page[before] in: query required: false schema: type: string nullable: true - name: filter[search] in: query description: >- Case-insensitive substring search. Returns offers whose offer name or category name contains the search string. required: false schema: type: string nullable: true - name: filter[purchaseChannel] in: query required: false schema: type: array items: $ref: '#/components/schemas/PurchaseChannel' nullable: true - name: filter[category] in: query required: false schema: $ref: '#/components/schemas/CategoryOption' nullable: true - name: filter[isTargeted] in: query required: false schema: type: boolean nullable: true - name: sort in: query description: If provided, response will be sorted by the specified fields required: false schema: type: array items: $ref: '#/components/schemas/usersOfferSortOptions' nullable: true - name: include in: query description: >- CSV list of included resources in the response (e.g "categories"). Allowed value is `categories`. required: false schema: type: array items: type: string nullable: true - name: supportedComponents in: query description: UI component types to include in the response. required: false schema: type: array items: $ref: '#/components/schemas/usersComponentType' nullable: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/usersOffersResponseObject' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get Offers By User security: - BearerAuth: [] /v2/issuers/{organizationId}/users/{userId}/placements/{placementId}/content: get: description: |- Retrieve the content for a placement. The placement type is resolved server-side so callers no longer pick an endpoint by placement type. Returns a JSON:API document whose `data` resources are self-describing by `type`: a standard placement returns `standardOffer` resources (with `links`, optional `included` categories, and `meta`); a batch-activation or group placement returns `placementBatch` slot resources. Distinguish the two by each resource's `type`. Email and push-notification placements are not servable through this endpoint and respond with a `400`.
Required scopes: `rewards:read` operationId: users_rewards_placementContent tags: - UsersRewards parameters: - name: organizationId in: path required: true schema: $ref: '#/components/schemas/OrganizationId' - name: userId in: path required: true schema: $ref: '#/components/schemas/UserId' - name: placementId in: path required: true schema: type: string - name: include in: query description: >- CSV list of included resources in the response (e.g "categories"). Allowed value is `categories`. Only applies to standard placements (those returning `standardOffer` resources). required: false schema: type: array items: type: string nullable: true - name: supportedComponents in: query description: UI component types to include in the response. required: false schema: type: array items: $ref: '#/components/schemas/usersComponentType' nullable: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/usersPlacementContentResponse' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get Placement Content security: - BearerAuth: [] /v2/issuers/{organizationId}/users/{userId}/locations: get: description: >- Retrieve national and local geographic locations that a specified user has eligible in-store offers at. Use this endpoint to build out your [map-specific UX experiences](/2024-10-01/api/getting-started#c-discover-clos-near-you-map-view).

Required scopes: `rewards:read` operationId: users_rewards_locations tags: - UsersRewards parameters: - name: organizationId in: path required: true schema: $ref: '#/components/schemas/OrganizationId' - name: userId in: path required: true schema: $ref: '#/components/schemas/UserId' - name: page[size] in: query required: false schema: type: integer nullable: true - name: page[after] in: query required: false schema: type: string nullable: true - name: page[before] in: query required: false schema: type: string nullable: true - name: filter[name] in: query required: false schema: type: string nullable: true - name: filter[city] in: query description: >- Case-insensitive substring match on the location's city. Never defines the search area; applied as an additional constraint alongside a radius search when `filter[latitude]`/`filter[longitude]`/`filter[radius]` are also provided. required: false schema: type: string nullable: true - name: filter[zipCode] in: query description: >- Exact-match filter on the location's zip code. Never defines the search area; applied as an additional constraint alongside a radius search when `filter[latitude]`/`filter[longitude]`/`filter[radius]` are also provided. required: false schema: type: string nullable: true - name: filter[state] in: query description: >- Exact-match filter on the location's state. Never defines the search area; applied as an additional constraint alongside a radius search when `filter[latitude]`/`filter[longitude]`/`filter[radius]` are also provided. required: false schema: $ref: '#/components/schemas/State' nullable: true - name: filter[category] in: query required: false schema: $ref: '#/components/schemas/CategoryOption' nullable: true - name: filter[longitude] in: query description: >- Longitude of the point to search around. Must be provided together with `filter[latitude]`; combine with `filter[radius]` to run a radius search. required: false schema: type: number format: double nullable: true - name: filter[latitude] in: query description: >- Latitude of the point to search around. Must be provided together with `filter[longitude]`; combine with `filter[radius]` to run a radius search. required: false schema: type: number format: double nullable: true - name: filter[radius] in: query description: >- Radius in miles to search around the point given by `filter[latitude]`/`filter[longitude]` (default 10, minimum 1). Has no effect unless both latitude and longitude are also provided — it is ignored when only `filter[zipCode]`, `filter[city]`, or `filter[state]` is used, without lat/long. required: false schema: type: integer nullable: true - name: sort in: query description: >- If provided, response will be sorted by the specified fields. Defaults to newest first, equivalent to descending `createdDate`; when `filter[latitude]`/`filter[longitude]` are provided, locations are ordered by ascending distance from that point first, then newest first. required: false schema: type: array items: $ref: '#/components/schemas/usersLocationSortOptions' nullable: true - name: include in: query description: >- CSV list of included resources in the response (e.g "offers,categories"). Allowed values are `offers` and `categories`. required: false schema: type: array items: type: string nullable: true - name: supportedComponents in: query description: UI component types to include in included offers. required: false schema: type: array items: $ref: '#/components/schemas/usersComponentType' nullable: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/usersLocationsResponseObject' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: '' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' summary: Get Locations By User security: - BearerAuth: [] components: schemas: CardNetwork: title: CardNetwork type: string enum: - VISA - MASTERCARD - AMERICANEXPRESS - DISCOVER description: Supported card networks NotificationType: title: NotificationType type: string enum: - earnedRewardApproved - earnedRewardSettled - earnedRewardRejected - auditUpdate - fileProcessingResult - pushNotificationPlacementFile - emailNotificationPlacementFile CategoryOption: title: CategoryOption type: string enum: - Arts & Entertainment - Baby, Kids & Toys - Books & Digital Media - Clothing, Shoes & Accessories - Computers, Electronics & Software - Convenience - Gas - Department Stores - Food & Beverage - Health & Beauty - Home & Garden - Miscellaneous - Occasions & Gifts - Pets - Sports & Outdoors - Supplies & Services - Travel description: >- Category of merchant. Please use URL Encode for non single word categories. (Food & Beverage should be Food%20%26%20Beverage) CuisineOption: title: CuisineOption type: string enum: - American Restaurant - Southern Restaurant - Cajun & Creole Restaurant - Southwestern Restaurant - BBQ Restaurant - Steakhouse - Burger Restaurant - Hot Dog Joint - Wings Joint - Fried Chicken Restaurant - Sandwich Shop - Deli - Diner - Hawaiian Restaurant - Canadian Restaurant - Mexican Restaurant - Taco Shop - Burrito Restaurant - Latin American Restaurant - Caribbean Restaurant - Jamaican Restaurant - Cuban Restaurant - Puerto Rican Restaurant - Brazilian Restaurant - Argentine Restaurant - Peruvian Restaurant - Colombian Restaurant - Venezuelan Restaurant - Salvadoran Restaurant - Honduran Restaurant - Italian Restaurant - Pizza Restaurant - Pasta Restaurant - French Restaurant - Creperie - Spanish Restaurant - Tapas Restaurant - Portuguese Restaurant - German Restaurant - Austrian Restaurant - Swiss Restaurant - Fondue Restaurant - British Restaurant - Fish & Chips Shop - Irish Restaurant - Belgian Restaurant - Dutch Restaurant - Scandinavian Restaurant - Eastern European Restaurant - Polish Restaurant - Russian Restaurant - European Restaurant - Mediterranean Restaurant - Greek Restaurant - Middle Eastern Restaurant - Lebanese Restaurant - Israeli Restaurant - Jewish Restaurant - Turkish Restaurant - Persian Restaurant - Egyptian Restaurant - Moroccan Restaurant - Armenian Restaurant - Georgian Restaurant - Falafel Restaurant - Kebab Shop - African Restaurant - Ethiopian Restaurant - Indian Restaurant - Pakistani Restaurant - Bangladeshi Restaurant - Sri Lankan Restaurant - Nepalese Restaurant - Afghan Restaurant - Asian Restaurant - Chinese Restaurant - Taiwanese Restaurant - Hong Kong Restaurant - Dim Sum Restaurant - Hot Pot Restaurant - Dumpling Restaurant - Noodle Shop - Japanese Restaurant - Sushi Restaurant - Ramen Restaurant - Yakitori Restaurant - Korean Restaurant - Mongolian Restaurant - Thai Restaurant - Vietnamese Restaurant - Filipino Restaurant - Malaysian Restaurant - Indonesian Restaurant - Singaporean Restaurant - Burmese Restaurant - Cambodian Restaurant - Australian Restaurant - Seafood Restaurant - Poke Restaurant - Salad Restaurant - Soup Restaurant - Breakfast Restaurant - Brunch Restaurant - Bagel Shop - Buffet - Fast Food Restaurant - Food Truck - Gastropub - Bakery - Cafe - Bubble Tea Shop - Juice Bar - Dessert Shop - Ice Cream Shop - Doughnut Shop - Bar - Sports Bar - Wine Bar - Winery - Brewery - Cocktail Bar - Distillery - Nightclub - Karaoke Bar - Comedy Club - Music Venue - Dance Club - Pool Hall - Casino - Bowling Alley - Movie Theater - Museum - Stadium - Theme Park - Sports & Recreation - Vegan Restaurant - Vegetarian Restaurant - Kosher Restaurant - Halal Restaurant - Gluten Free Restaurant - Healthy Restaurant description: >- The kind of food or venue a location offers, for example "Pizza Restaurant". CommissionType: title: CommissionType type: string enum: - FLAT - PERCENT description: Type of commission on offer (% or a flat $) CommissionValueType: title: CommissionValueType type: string enum: - cents description: The type of commission value CommissionValue: title: CommissionValue type: object properties: type: $ref: '#/components/schemas/CommissionValueType' description: The type of commission value: type: integer description: The commission value. required: - type - value State: title: State type: string enum: - AL - AK - AS - AZ - AR - CA - CO - CT - DE - DC - FM - FL - GA - GU - HI - ID - IL - IN - IA - KS - KY - LA - ME - MH - MD - MA - MI - MN - MS - MO - MT - NE - NV - NH - NJ - NM - NY - NC - ND - MP - OH - OK - OR - PW - PA - PR - RI - SC - SD - TN - TX - UT - VT - VI - VA - WA - WV - WI - WY EnrolledRewardsType: title: EnrolledRewardsType type: string enum: - CARDLINKED description: Enrolled Rewards PurchaseChannel: title: PurchaseChannel type: string enum: - INSTORE - ONLINE description: Purchase channel of offer RelationshipSingle: title: RelationshipSingle type: object properties: data: $ref: '#/components/schemas/RelationshipData' required: - data RelationshipMultiple: title: RelationshipMultiple type: object properties: data: type: array items: $ref: '#/components/schemas/RelationshipData' required: - data RelationshipData: title: RelationshipData type: object properties: type: $ref: '#/components/schemas/ResourceType' id: type: string description: The ID of the related resource required: - type - id Links: title: Links type: object description: Related links to the API call properties: self: type: string prev: type: string nullable: true next: type: string nullable: true required: - self JobResponse: title: JobResponse type: object properties: type: $ref: '#/components/schemas/ResourceType' id: type: string description: The request id of the pending job attributes: $ref: '#/components/schemas/Job' required: - type - id - attributes Job: title: Job type: object properties: status: $ref: '#/components/schemas/JobStatus' message: type: string description: Message regarding the status of the job request required: - status - message JobStatus: title: JobStatus type: string enum: - queued description: Status of the job EmptyObject: title: EmptyObject type: object properties: {} MongoId: title: MongoId type: string description: The unique identifier for a document in the database OrganizationId: title: OrganizationId type: string description: Your issuer organization ID, provided by Kard SubscriptionId: title: SubscriptionId type: string description: The ID of the subscription UserId: title: UserId type: string description: The ID of the user as defined on the issuers system ResourceType: title: ResourceType type: string description: Type of document returned ErrorResponse: title: ErrorResponse type: object properties: errors: type: array items: $ref: '#/components/schemas/ErrorObject' required: - errors ErrorObject: title: ErrorObject type: object properties: status: type: string description: Status code returned from the request title: type: string description: Name of error detail: type: string description: Description of the specific occurance of the error source: $ref: '#/components/schemas/ErrorSource' nullable: true description: An object containing a reference to the primary source of the error id: type: string nullable: true description: >- The id of the resource which caused the error. Always returned for multi-status errors. required: - status - title - detail ErrorSource: title: ErrorSource type: object properties: pointer: type: string nullable: true description: >- A JSON pointer to the value in the request document that caused the error parameter: type: string nullable: true description: A string indicating which URI query parameter caused the error header: type: string nullable: true description: >- A string indicating the name of a single request header which caused the error OfferComponents: title: OfferComponents type: object description: UI component data for rendering offer details properties: shortDescription: type: string nullable: true description: Short description for the offer longDescription: type: string nullable: true description: Long description for the offer baseReward: type: string nullable: true description: Formatted reward string boostedReward: type: string nullable: true description: Formatted boosted reward string cta: $ref: '#/components/schemas/CtaComponent' nullable: true description: Call-to-action button component tags: type: array items: type: string nullable: true description: Tags for the offer detailTags: type: array items: type: string nullable: true description: Detail tags for the offer logoFlare: $ref: '#/components/schemas/LogoFlare' nullable: true description: Logo flare configuration for the offer progressBar: $ref: '#/components/schemas/ProgressBar' nullable: true description: Progress bar component for tracking offer redemptions ProgressBar: title: ProgressBar type: object description: Progress bar component for tracking offer redemption progress properties: total: type: integer description: Total number of redemptions allowed currentProgress: type: integer description: Number of redemptions the user has completed label: type: string description: Formatted label for the progress bar segmented: type: boolean description: Whether the progress bar should be displayed as segmented segments: $ref: '#/components/schemas/ProgressBarSegments' nullable: true description: Segment configuration for the progress bar in different layouts labels: $ref: '#/components/schemas/ProgressBarLabels' description: Labels to render around the progress bar in different layouts required: - total - currentProgress - label - segmented - labels ProgressBarSegments: title: ProgressBarSegments type: object description: Segment configuration for the progress bar in different layouts properties: details: $ref: '#/components/schemas/ProgressBarSegment' nullable: true description: Segment configuration for the details view default: $ref: '#/components/schemas/ProgressBarSegment' description: Segment configuration for the default view progress: type: array items: $ref: '#/components/schemas/ProgressBarSegmentProgress' description: >- Per-segment fill state: one entry per segment node, index-aligned with the nodes (length equals the progress bar total). Reached nodes report 1 of 1 and not-yet-reached nodes 0 of 1; for a punch-card offer the in-progress node reports qualifying-purchase progress toward the next reward (Q mod N of N). required: - default - progress ProgressBarSegmentProgress: title: ProgressBarSegmentProgress type: object description: Fill state of a single segment node, expressed as completed of total. properties: completed: type: integer description: Units completed within the current segment. total: type: integer description: Total units required to complete the current segment. required: - completed - total ProgressBarSegment: title: ProgressBarSegment type: object description: Segment configuration for a specific layout properties: icon: type: string nullable: true description: SVG icon to use for each segment position: $ref: '#/components/schemas/ProgressBarSegmentPosition' description: Position of the segment within the layout separator: $ref: '#/components/schemas/ProgressBarSegmentSeparator' nullable: true description: Separator style to render between segment nodes labels: type: array items: $ref: '#/components/schemas/ProgressBarSegmentLabel' nullable: true description: Label configuration for each node in the segment selection: $ref: '#/components/schemas/ProgressBarSegmentSelection' nullable: true description: >- Which segment nodes the UI should render as selected based on currentProgress required: - position ProgressBarSegmentLabel: title: ProgressBarSegmentLabel type: object description: Label configuration for a single node within a segment properties: title: type: string description: Title text for the segment node description: type: string description: Description text for the segment node required: - title - description ProgressBarSegmentSeparator: title: ProgressBarSegmentSeparator type: string enum: - LINE description: Supported separator styles between segment nodes ProgressBarSegmentSelection: title: ProgressBarSegmentSelection type: string enum: - CURRENT - CURRENT_AND_BELOW description: >- Supported selection strategies for highlighting segment nodes. - CURRENT: select only the segment at currentProgress - CURRENT_AND_BELOW: select the segment at currentProgress and all segments below it ProgressBarSegmentPosition: title: ProgressBarSegmentPosition type: string enum: - LEFT - RIGHT - FULL_WIDTH description: Supported segment positions ProgressBarLabels: title: ProgressBarLabels type: object description: Labels to render around the progress bar in different layouts properties: details: $ref: '#/components/schemas/ProgressBarLabelPair' nullable: true description: Label configuration for the details view default: $ref: '#/components/schemas/ProgressBarLabelPair' description: Label configuration for the default view required: - default ProgressBarLabelPair: title: ProgressBarLabelPair type: object description: Left and right label configuration for a specific layout properties: left: type: string nullable: true description: Text content for the left label right: type: string nullable: true description: Text content for the right label CtaComponent: title: CtaComponent type: object description: Call-to-action button component for offers properties: buttonText: type: string description: Text to display on the button buttonStyle: $ref: '#/components/schemas/ButtonStyle' description: Style of the button action: $ref: '#/components/schemas/CtaAction' nullable: true description: Action to perform when the button is clicked startIcon: type: string nullable: true description: Icon identifier to display on the button required: - buttonText - buttonStyle CtaAction: title: CtaAction type: object description: Action configuration for CTA button properties: url: type: string description: URL endpoint to call when button is clicked method: type: string description: HTTP method to use (e.g., POST) required: - url - method LogoFlare: title: LogoFlare type: object description: Logo flare configuration for offer display properties: borderColor: $ref: '#/components/schemas/LogoFlareBorderColor' description: Border color style for the logo flare badge: $ref: '#/components/schemas/LogoFlareBadge' nullable: true description: Optional badge to display on the logo required: - borderColor LogoFlareBorderColor: title: LogoFlareBorderColor type: string enum: - PRIMARY - SECONDARY description: Available border color options for logo flare LogoFlareBadge: title: LogoFlareBadge type: object description: Badge configuration for logo flare properties: icon: type: string description: Icon identifier for the badge position: $ref: '#/components/schemas/LogoFlareBadgePosition' description: Position of the badge on the logo required: - icon - position LogoFlareBadgePosition: title: LogoFlareBadgePosition type: string enum: - TOP_RIGHT - TOP_LEFT - BOTTOM_RIGHT - BOTTOM_LEFT description: Available positions for the logo flare badge ButtonStyle: title: ButtonStyle type: string enum: - PRIMARY - SECONDARY - DISABLED description: Available button styles for CTA components FileType: title: FileType type: string enum: - earnedRewardApprovedDailyReconciliationFile - earnedRewardSettledDailyReconciliationFile - monthlyReconciliationFile FilesMetadataSortOptions: title: FilesMetadataSortOptions type: string enum: - sentDate - '-sentDate' GetFilesMetadataResponse: title: GetFilesMetadataResponse type: object properties: data: type: array items: $ref: '#/components/schemas/FileMetadataWithURL' description: List of file metadata objects with their pre-signed URLs. links: $ref: '#/components/schemas/Links' description: Navigation links for paginated results. meta: $ref: '#/components/schemas/PaginationMeta' description: Metadata about the pagination status. required: - data - links - meta FileMetadataWithURL: title: FileMetadataWithURL type: object properties: type: $ref: '#/components/schemas/FileType' description: The type of the generated file. attributes: $ref: '#/components/schemas/FileMetadataAttribute' description: Attributes of the filetype id: type: string description: The File ID in Kard’s system required: - type - attributes - id FileMetadataAttribute: title: FileMetadataAttribute type: object properties: fileName: type: string description: The name of the file. sentAt: type: string description: >- ISO 8601 timestamp (ISO8601) when the file was originally sent/created. lastModified: type: string description: ISO 8601 timestamp (ISO8601) when the file was last modified. downloadUrl: type: string description: >- Temporary URL that provides direct access to download the file for 30 minutes. required: - fileName - sentAt - lastModified - downloadUrl PaginationMeta: title: PaginationMeta type: object properties: pageSize: type: integer description: Number of items per page. hasNextPage: type: boolean description: Indicates if there are more pages available after the current one. required: - pageSize - hasNextPage EnrolledReward: title: EnrolledReward type: string enum: - CARDLINKED - AFFILIATE description: Rewards programs an organization is enrolled in OrganizationCardNetwork: title: OrganizationCardNetwork type: string enum: - VISA - MASTERCARD - AMERICAN_EXPRESS - DISCOVER description: >- Card networks supported by an organization. Deliberately not commons.CardNetwork: that type spells Amex `AMERICANEXPRESS`, which the organizations database rejects. The organizations.card_networks CHECK constraint permits `AMERICAN_EXPRESS` (canonical, and what this service writes) and `AMERICAN EXPRESS` (legacy, present in existing rows only). The name differs from commons.CardNetwork because a type may not shadow one from an imported file. OrganizationPaginationMetadata: title: OrganizationPaginationMetadata type: object description: Pagination metadata for organization list responses properties: pageSize: type: integer description: Number of items per page hasNextPage: type: boolean description: Whether more pages are available required: - pageSize - hasNextPage DeleteResourceResponse: title: DeleteResourceResponse type: object description: Response returned after deleting a resource properties: data: $ref: '#/components/schemas/DeleteResourceData' required: - data DeleteResourceData: title: DeleteResourceData type: object description: Deleted resource stub properties: type: type: string description: Resource type identifier id: type: string description: ID of the deleted resource attributes: $ref: '#/components/schemas/EmptyObject' required: - type - id - attributes notificationsDeliveryStatus: title: notificationsDeliveryStatus type: string enum: - pending - delivered - delivery_failed description: The delivery status of a notification. notificationsNotificationsListResponse: title: notificationsNotificationsListResponse type: object properties: data: type: array items: $ref: '#/components/schemas/notificationsNotificationUnion' meta: $ref: '#/components/schemas/notificationsPaginationMetadata' description: Metadata about the pagination status. links: $ref: '#/components/schemas/Links' nullable: true description: Links to the current, next, and previous pages. required: - data - meta notificationsNotificationUnion: title: notificationsNotificationUnion oneOf: - $ref: '#/components/schemas/notificationsNotification' discriminator: propertyName: type mapping: notification: '#/components/schemas/notificationsNotification' notificationsNotification: title: notificationsNotification type: object properties: type: type: string enum: - notification id: type: string description: >- The event ID of the notification; the value the replay endpoint consumes. attributes: $ref: '#/components/schemas/notificationsNotificationAttributes' required: - type - id - attributes notificationsNotificationAttributes: title: notificationsNotificationAttributes type: object properties: eventId: type: string description: The event ID of the notification. eventName: $ref: '#/components/schemas/NotificationType' description: The name of the event. transactionId: type: string nullable: true description: >- The network transaction id carried by the notification payload, matching `data.attributes.transactionId` on the delivered webhook. Present whenever the event is about a transaction; absent on events that are not. timestamp: type: string format: date-time description: When the notification was created. lastAttemptAt: type: string format: date-time description: When the most recent delivery attempt was recorded. status: $ref: '#/components/schemas/notificationsDeliveryStatus' description: The delivery status of the notification. attempts: type: integer description: The number of delivery attempts recorded for this notification. statusCode: type: integer nullable: true description: >- The HTTP status code returned by the issuer's webhook on the last delivery attempt, when available. errorMessage: type: string nullable: true description: >- The error recorded on the last delivery attempt, when delivery failed. required: - eventId - eventName - timestamp - lastAttemptAt - status - attempts notificationsPaginationMetadata: title: notificationsPaginationMetadata type: object description: Response metadata. properties: pageSize: type: integer description: Number of items per page. hasNextPage: type: boolean description: Indicates if there are more pages available after the current one. total: type: integer nullable: true description: >- Total number of records matching the query (for offset-based pagination). page: type: integer nullable: true description: Current page number (for offset-based pagination). required: - pageSize - hasNextPage notificationsReplayNotificationResponse: title: notificationsReplayNotificationResponse type: object properties: data: $ref: '#/components/schemas/notificationsReplayAcceptedNotification' required: - data notificationsReplayAcceptedNotification: title: notificationsReplayAcceptedNotification type: object properties: eventId: type: string format: uuid description: The event ID accepted for replay and queued for delivery. required: - eventId notificationsTriggerEventName: title: notificationsTriggerEventName type: string enum: - earnedRewardApproved - earnedRewardSettled description: >- The earned-reward event to simulate. Only these two events are supported. notificationsTriggerNotificationRequestBody: title: notificationsTriggerNotificationRequestBody type: object properties: data: type: array items: $ref: '#/components/schemas/notificationsSimulateTestTransactionUnion' required: - data notificationsSimulateTestTransactionUnion: title: notificationsSimulateTestTransactionUnion oneOf: - $ref: '#/components/schemas/notificationsSimulateTestTransaction' discriminator: propertyName: type mapping: simulateTestTransaction: '#/components/schemas/notificationsSimulateTestTransaction' notificationsSimulateTestTransaction: title: notificationsSimulateTestTransaction type: object properties: type: type: string enum: - simulateTestTransaction attributes: $ref: '#/components/schemas/notificationsSimulateTestTransactionAttributes' required: - type - attributes notificationsSimulateTestTransactionAttributes: title: notificationsSimulateTestTransactionAttributes type: object properties: userId: type: string description: >- The issuer's user id (referringPartnerUserId) to attribute the simulated reward to. transactionId: type: string description: The network transaction id to include in the simulated transaction. eventName: $ref: '#/components/schemas/notificationsTriggerEventName' description: The earned-reward event to simulate. required: - userId - transactionId - eventName notificationsTriggerNotificationResponse: title: notificationsTriggerNotificationResponse type: object properties: data: $ref: '#/components/schemas/notificationsTriggerAcceptedNotification' required: - data notificationsTriggerAcceptedNotification: title: notificationsTriggerAcceptedNotification type: object properties: eventId: type: string format: uuid description: >- The generated event ID of the triggered notification, queued for delivery. It is listable and replayable like any other notification. required: - eventId notificationsCreatedSubscription: title: notificationsCreatedSubscription type: object properties: type: type: string enum: - subscription id: type: string description: The ID of the subscription required: - type - id allOf: - $ref: '#/components/schemas/notificationsSubscriptionRequest' notificationsSubscriptionsResponseObject: title: notificationsSubscriptionsResponseObject type: object properties: data: type: array items: $ref: '#/components/schemas/notificationsSubscriptionUnion' required: - data notificationsSubscriptionUnion: title: notificationsSubscriptionUnion oneOf: - $ref: '#/components/schemas/notificationsSubscription' discriminator: propertyName: type mapping: subscription: '#/components/schemas/notificationsSubscription' notificationsSubscription: title: notificationsSubscription type: object properties: type: type: string enum: - subscription id: type: string description: The ID of the subscription attributes: $ref: '#/components/schemas/notificationsSubscriptionAttributes' required: - type - id - attributes notificationsSubscriptionAttributes: title: notificationsSubscriptionAttributes type: object properties: eventName: $ref: '#/components/schemas/NotificationType' description: The name of the event webhookUrl: type: string description: The URL to which notifications will be sent enabled: type: boolean description: Indicates whether the subscription is active required: - eventName - webhookUrl - enabled notificationsSubscriptionRequestBody: title: notificationsSubscriptionRequestBody type: object properties: data: type: array items: $ref: '#/components/schemas/notificationsSubscriptionRequestUnion' required: - data notificationsSubscriptionRequestUnion: title: notificationsSubscriptionRequestUnion oneOf: - type: object allOf: - type: object properties: type: type: string enum: - subscription - $ref: '#/components/schemas/notificationsSubscriptionRequest' required: - type notificationsSubscriptionRequest: title: notificationsSubscriptionRequest type: object properties: attributes: $ref: '#/components/schemas/notificationsSubscriptionRequestAttributes' required: - attributes notificationsSubscriptionRequestAttributes: title: notificationsSubscriptionRequestAttributes type: object properties: eventName: $ref: '#/components/schemas/NotificationType' description: The name of the event for the subscription webhookUrl: type: string description: The URL where notifications will be delivered enabled: type: boolean description: Indicates whether the subscription is active required: - eventName - webhookUrl - enabled notificationsUpdateSubscriptionRequestBody: title: notificationsUpdateSubscriptionRequestBody type: object properties: data: $ref: '#/components/schemas/notificationsUpdateSubscriptionRequestUnion' required: - data notificationsUpdateSubscriptionRequestUnion: title: notificationsUpdateSubscriptionRequestUnion oneOf: - $ref: '#/components/schemas/notificationsUpdateSubscriptionRequest' discriminator: propertyName: type mapping: subscription: '#/components/schemas/notificationsUpdateSubscriptionRequest' notificationsUpdateSubscriptionRequest: title: notificationsUpdateSubscriptionRequest type: object properties: type: type: string enum: - subscription attributes: $ref: >- #/components/schemas/notificationsUpdateSubscriptionRequestAttributes required: - type - attributes notificationsUpdateSubscriptionRequestAttributes: title: notificationsUpdateSubscriptionRequestAttributes type: object properties: eventName: $ref: '#/components/schemas/NotificationType' nullable: true description: The name of the event for the subscription webhookUrl: type: string nullable: true description: The URL where notifications will be delivered enabled: type: boolean nullable: true description: Indicates whether the subscription is active notificationsCreateSubscriptionsResponseObject: title: notificationsCreateSubscriptionsResponseObject type: object properties: data: type: array items: $ref: '#/components/schemas/notificationsCreateSubscriptionUnion' required: - data notificationsUpdateSubscriptionsResponseObject: title: notificationsUpdateSubscriptionsResponseObject type: object properties: data: $ref: '#/components/schemas/notificationsCreateSubscriptionUnion' required: - data notificationsCreateSubscriptionUnion: title: notificationsCreateSubscriptionUnion oneOf: - $ref: '#/components/schemas/notificationsCreatedSubscription' discriminator: propertyName: type mapping: subscription: '#/components/schemas/notificationsCreatedSubscription' ExternalOrganizationAttributes: title: ExternalOrganizationAttributes type: object description: Limited set of organization attributes exposed to external consumers properties: name: type: string description: Name of the organization (uppercase, no spaces) enrolledRewards: type: array items: $ref: '#/components/schemas/EnrolledReward' description: Rewards programs the organization is enrolled in cardNetworks: type: array items: $ref: '#/components/schemas/OrganizationCardNetwork' description: Card networks supported by the organization bins: type: array items: type: string description: Bank Identification Numbers for the organization affiliateCommissionSplit: type: number format: double description: Affiliate commission split percentage cardlinkedCommissionSplit: type: number format: double description: Cardlinked commission split percentage cardlinkedUserCommissionSplit: type: number format: double description: Cardlinked user commission split percentage required: - name - enrolledRewards - cardNetworks - bins - affiliateCommissionSplit - cardlinkedCommissionSplit - cardlinkedUserCommissionSplit ExternalOrganizationResponse: title: ExternalOrganizationResponse type: object description: External organization resource response properties: type: type: string enum: - organization id: type: string description: Unique identifier of the organization attributes: $ref: '#/components/schemas/ExternalOrganizationAttributes' required: - type - id - attributes organizationsChildOrganizationAttributes: title: organizationsChildOrganizationAttributes type: object description: >- Limited set of child organization attributes exposed to external consumers properties: name: type: string description: >- Name of the child organization (at least one letter; letters and spaces only) externalId: type: string nullable: true description: External identifier for the child organization bins: type: array items: type: string description: Bank Identification Numbers for the child organization required: - name - bins organizationsChildOrganizationResponse: title: organizationsChildOrganizationResponse type: object description: Child organization resource response properties: type: type: string enum: - organization id: type: string description: Unique identifier of the child organization attributes: $ref: '#/components/schemas/organizationsChildOrganizationAttributes' required: - type - id - attributes organizationsChildOrganizationListResponse: title: organizationsChildOrganizationListResponse type: object description: Paginated list of child organizations properties: data: type: array items: $ref: '#/components/schemas/organizationsChildOrganizationResponse' description: Array of child organization resources links: $ref: '#/components/schemas/Links' nullable: true meta: $ref: '#/components/schemas/OrganizationPaginationMetadata' nullable: true description: Pagination metadata required: - data organizationsCreateChildRequestBody: title: organizationsCreateChildRequestBody type: object description: Request body for creating a child organization properties: data: $ref: '#/components/schemas/organizationsCreateChildRequestData' description: Child organization data for creation required: - data organizationsCreateChildRequestData: title: organizationsCreateChildRequestData type: object description: Child organization data structure for creation properties: type: type: string enum: - organization description: Resource type identifier attributes: $ref: '#/components/schemas/organizationsCreateChildAttributes' description: Child organization attributes for creation required: - type - attributes organizationsCreateChildAttributes: title: organizationsCreateChildAttributes type: object description: >- Attributes for creating a child organization. Only name is required. All other fields are optional and default to the parent organization's values. properties: name: type: string description: >- Name of the child organization (at least one letter; letters and spaces only) externalId: type: string nullable: true description: External identifier for the child organization bins: type: array items: type: string nullable: true description: Bank Identification Numbers for the child organization required: - name organizationsUpdateChildRequestBody: title: organizationsUpdateChildRequestBody type: object description: Request body for updating a child organization properties: data: $ref: '#/components/schemas/organizationsUpdateChildRequestData' description: Child organization data for update required: - data organizationsUpdateChildRequestData: title: organizationsUpdateChildRequestData type: object description: Child organization data structure for update properties: type: type: string enum: - organization description: Resource type identifier attributes: $ref: '#/components/schemas/organizationsUpdateChildAttributes' description: Child organization attributes for update required: - type - attributes organizationsUpdateChildAttributes: title: organizationsUpdateChildAttributes type: object description: >- Attributes for updating a child organization. All fields are optional; only provided fields are changed. properties: name: type: string nullable: true description: >- New name for the child organization (at least one letter; letters and spaces only) externalId: type: string nullable: true description: External identifier for the child organization bins: type: array items: type: string nullable: true description: Bank Identification Numbers for the child organization organizationsContentStrategySort: title: organizationsContentStrategySort type: string enum: - NEWLY_LIVE - EXPIRING_SOON - HIGHEST_CASHBACK - PERSONALIZED - OFFERS_NEAR_YOU description: >- Sort applied to the offers selected by a content strategy. A strategy may have at most one sort. The v1 starter set covers newly-live, expiring-soon, highest-cashback, personalized, and offers-near-you selections. organizationsOfferFeatures: title: organizationsOfferFeatures type: string enum: - INTERACTIVE description: >- Offer feature applied to the offers selected by a content strategy. A strategy may have any number of offer features. organizationsContentStrategyFilters: title: organizationsContentStrategyFilters type: object description: Filters applied when selecting offers for a content strategy properties: categories: type: array items: type: string nullable: true description: Merchant categories to include categoryExclusions: type: array items: type: string nullable: true description: Merchant categories to exclude merchantExclusions: type: array items: type: string nullable: true description: Merchant IDs to exclude offerFeatures: type: array items: $ref: '#/components/schemas/organizationsOfferFeatures' nullable: true description: Offer features to filter by organizationsContentStrategyResponse: title: organizationsContentStrategyResponse type: object description: Content strategy resource response properties: type: type: string enum: - contentStrategy id: type: string description: Unique identifier of the content strategy (UUID v7) attributes: $ref: '#/components/schemas/organizationsContentStrategyAttributes' required: - type - id - attributes organizationsContentStrategyAttributes: title: organizationsContentStrategyAttributes type: object description: Attributes for a content strategy properties: name: type: string description: Name of the content strategy (unique within an organization) organizationId: type: string description: ID of the organization this content strategy belongs to sort: $ref: '#/components/schemas/organizationsContentStrategySort' nullable: true description: Sort applied when selecting offers for the strategy filters: $ref: '#/components/schemas/organizationsContentStrategyFilters' description: Filters applied when selecting offers for the strategy categories: type: array items: $ref: '#/components/schemas/CategoryOption' description: Merchant categories to include categoryExclusions: type: array items: $ref: '#/components/schemas/CategoryOption' description: Merchant categories to exclude merchantExclusions: type: array items: type: string description: Merchant IDs to exclude required: - name - organizationId - filters - categories - categoryExclusions - merchantExclusions organizationsContentStrategyListResponse: title: organizationsContentStrategyListResponse type: object description: Paginated list of content strategies properties: data: type: array items: $ref: '#/components/schemas/organizationsContentStrategyResponse' description: Array of content strategy resources links: $ref: '#/components/schemas/Links' nullable: true meta: $ref: '#/components/schemas/OrganizationPaginationMetadata' nullable: true description: Pagination metadata required: - data organizationsCreateContentStrategyRequestBody: title: organizationsCreateContentStrategyRequestBody type: object description: Request body for creating a content strategy properties: data: $ref: '#/components/schemas/organizationsCreateContentStrategyRequestData' description: Content strategy data for creation required: - data organizationsCreateContentStrategyRequestData: title: organizationsCreateContentStrategyRequestData type: object description: Content strategy data structure for creation properties: type: type: string enum: - contentStrategy description: Resource type identifier attributes: $ref: '#/components/schemas/organizationsCreateContentStrategyAttributes' description: Content strategy attributes for creation required: - type - attributes organizationsCreateContentStrategyAttributes: title: organizationsCreateContentStrategyAttributes type: object description: Attributes for creating a content strategy properties: name: type: string description: Name of the content strategy (unique within an organization) sort: $ref: '#/components/schemas/organizationsContentStrategySort' nullable: true description: Sort applied when selecting offers for the strategy filters: $ref: '#/components/schemas/organizationsContentStrategyFilters' description: Filters applied when selecting offers for the strategy categories: type: array items: $ref: '#/components/schemas/CategoryOption' description: Merchant categories to include categoryExclusions: type: array items: $ref: '#/components/schemas/CategoryOption' description: Merchant categories to exclude merchantExclusions: type: array items: type: string description: Merchant IDs to exclude required: - name - filters - categories - categoryExclusions - merchantExclusions organizationsUpdateContentStrategyRequestBody: title: organizationsUpdateContentStrategyRequestBody type: object description: Request body for updating a content strategy properties: data: $ref: '#/components/schemas/organizationsUpdateContentStrategyRequestData' description: Content strategy data for update required: - data organizationsUpdateContentStrategyRequestData: title: organizationsUpdateContentStrategyRequestData type: object description: Content strategy data structure for update properties: type: type: string enum: - contentStrategy description: Resource type identifier attributes: $ref: '#/components/schemas/organizationsUpdateContentStrategyAttributes' description: Content strategy attributes for update required: - type - attributes organizationsUpdateContentStrategyAttributes: title: organizationsUpdateContentStrategyAttributes type: object description: Attributes for updating a content strategy. All fields are required. properties: name: type: string description: Name of the content strategy (unique within an organization) sort: $ref: '#/components/schemas/organizationsContentStrategySort' nullable: true description: Sort applied when selecting offers for the strategy filters: $ref: '#/components/schemas/organizationsContentStrategyFilters' description: Filters applied when selecting offers for the strategy categories: type: array items: $ref: '#/components/schemas/CategoryOption' description: Merchant categories to include categoryExclusions: type: array items: $ref: '#/components/schemas/CategoryOption' description: Merchant categories to exclude merchantExclusions: type: array items: type: string description: Merchant IDs to exclude required: - name - filters - categories - categoryExclusions - merchantExclusions organizationsPlacementTypeFilter: title: organizationsPlacementTypeFilter type: string enum: - placement - placementPushNotification - placementEmail - placementBatchActivation - placementGroup description: Placement type discriminator used as a list filter organizationsCadenceFrequency: title: organizationsCadenceFrequency type: string enum: - DAILY - WEEKLY - MONTHLY description: How often a push notification or email placement delivers organizationsDayOfWeek: title: organizationsDayOfWeek type: string enum: - MON - TUE - WED - THU - FRI - SAT - SUN description: Day of the week (used when frequency is WEEKLY) organizationsCadence: title: organizationsCadence type: object description: Cadence schedule for push notification and email placements properties: frequency: $ref: '#/components/schemas/organizationsCadenceFrequency' description: Delivery frequency timeOfDay: type: string nullable: true description: Optional time of day in HH:mm format (24-hour, UTC) dayOfWeek: $ref: '#/components/schemas/organizationsDayOfWeek' nullable: true description: >- Day of the week to deliver (used when frequency is WEEKLY, defaults to MON) dayOfMonth: type: integer nullable: true description: >- Day of the month to deliver, 1-31 (used when frequency is MONTHLY, defaults to 1) required: - frequency organizationsPlacementFormatUnion: title: organizationsPlacementFormatUnion oneOf: - $ref: '#/components/schemas/organizationsPlacementData' - $ref: '#/components/schemas/organizationsPushNotificationPlacementData' - $ref: '#/components/schemas/organizationsEmailPlacementData' - $ref: '#/components/schemas/organizationsBatchActivationPlacementData' - $ref: '#/components/schemas/organizationsGroupPlacementData' description: Discriminated union for placement resources keyed on type discriminator: propertyName: type mapping: placement: '#/components/schemas/organizationsPlacementData' placementPushNotification: '#/components/schemas/organizationsPushNotificationPlacementData' placementEmail: '#/components/schemas/organizationsEmailPlacementData' placementBatchActivation: '#/components/schemas/organizationsBatchActivationPlacementData' placementGroup: '#/components/schemas/organizationsGroupPlacementData' organizationsResourceIdentifier: title: organizationsResourceIdentifier type: object description: A reference to another resource by type and id. properties: type: type: string description: Discriminant of the referenced resource (e.g. `contentStrategy`). id: type: string description: Identifier of the referenced resource. required: - type - id organizationsToOneRelationship: title: organizationsToOneRelationship type: object description: A JSON:API to-one relationship payload. properties: data: $ref: '#/components/schemas/organizationsResourceIdentifier' nullable: true description: >- The linked resource identifier, or null when the relationship is present but unlinked. organizationsToManyRelationship: title: organizationsToManyRelationship type: object description: A JSON:API to-many relationship payload. properties: data: type: array items: $ref: '#/components/schemas/organizationsResourceIdentifier' description: The linked resource identifiers. required: - data organizationsPlacementRelationships: title: organizationsPlacementRelationships type: object description: >- Relationship block for non-batch placements. Mirrors the `contentStrategyId` attribute so JSON:API clients can walk the graph. properties: contentStrategy: $ref: '#/components/schemas/organizationsToOneRelationship' nullable: true description: >- Relationship to the content strategy that powers this placement. Present whenever the placement has been linked to a content strategy (`data.id` will be set). Omitted entirely when no content strategy is linked. organizationsSlottedPlacementRelationships: title: organizationsSlottedPlacementRelationships type: object description: Relationship block for a batch-activation or group placement. properties: slots: $ref: '#/components/schemas/organizationsToManyRelationship' description: >- Resource identifiers for the slots that make up the placement. Each entry corresponds to a `batchActivationSlot` resource that appears in `included` when the request asks for `slots` (or any deeper path that implies it). required: - slots organizationsPlacementData: title: organizationsPlacementData type: object description: Standard placement resource data properties: type: type: string enum: - placement id: type: string description: Unique identifier of the placement (UUID v7) attributes: $ref: '#/components/schemas/organizationsPlacementAttributes' relationships: $ref: '#/components/schemas/organizationsPlacementRelationships' nullable: true description: >- JSON:API relationships for the placement. Omitted entirely when the placement has no linked resources. required: - type - id - attributes organizationsPushNotificationPlacementData: title: organizationsPushNotificationPlacementData type: object description: Push-notification placement resource data properties: type: type: string enum: - placementPushNotification id: type: string description: Unique identifier of the placement (UUID v7) attributes: $ref: >- #/components/schemas/organizationsPushNotificationPlacementAttributes relationships: $ref: '#/components/schemas/organizationsPlacementRelationships' nullable: true description: >- JSON:API relationships for the placement. Omitted entirely when the placement has no linked resources. required: - type - id - attributes organizationsEmailPlacementData: title: organizationsEmailPlacementData type: object description: Email placement resource data properties: type: type: string enum: - placementEmail id: type: string description: Unique identifier of the placement (UUID v7) attributes: $ref: '#/components/schemas/organizationsEmailPlacementAttributes' relationships: $ref: '#/components/schemas/organizationsPlacementRelationships' nullable: true description: >- JSON:API relationships for the placement. Omitted entirely when the placement has no linked resources. required: - type - id - attributes organizationsPlacementStatus: title: organizationsPlacementStatus type: string enum: - ACTIVE - INACTIVE description: >- Whether a scheduled placement's deliveries are paused. INACTIVE removes the placement's delivery schedule (push/email); ACTIVE re-creates it. Status has no effect on content serving. organizationsPlacementAttributes: title: organizationsPlacementAttributes type: object description: Attributes for a standard placement properties: name: type: string description: Name of the placement displayName: type: string nullable: true description: >- Cardholder-facing title for the section, if one was set. When absent, clients fall back to their own default label. organizationId: type: string description: ID of the organization this placement belongs to availableSlots: type: integer description: Number of available slots contentStrategyId: type: string nullable: true description: >- ID of the content strategy linked to this placement, if any. Retained alongside `relationships.contentStrategy` for backward compatibility. required: - name - organizationId - availableSlots organizationsPushNotificationPlacementAttributes: title: organizationsPushNotificationPlacementAttributes type: object description: Attributes for a push-notification placement properties: name: type: string description: Name of the placement status: $ref: '#/components/schemas/organizationsPlacementStatus' description: >- Whether the placement's scheduled deliveries are paused. Has no effect on content serving. organizationId: type: string description: ID of the organization this placement belongs to cadence: $ref: '#/components/schemas/organizationsCadence' description: Delivery cadence for the notification contentStrategyId: type: string nullable: true description: >- ID of the content strategy linked to this placement, if any. Retained alongside `relationships.contentStrategy` for backward compatibility. required: - name - status - organizationId - cadence organizationsEmailPlacementAttributes: title: organizationsEmailPlacementAttributes type: object description: Attributes for an email placement properties: name: type: string description: Name of the placement status: $ref: '#/components/schemas/organizationsPlacementStatus' description: >- Whether the placement's scheduled deliveries are paused. Has no effect on content serving. organizationId: type: string description: ID of the organization this placement belongs to availableSlots: type: integer description: Number of available slots cadence: $ref: '#/components/schemas/organizationsCadence' description: Delivery cadence for the email contentStrategyId: type: string nullable: true description: >- ID of the content strategy linked to this placement, if any. Retained alongside `relationships.contentStrategy` for backward compatibility. required: - name - status - organizationId - availableSlots - cadence organizationsBatchActivationPlacementData: title: organizationsBatchActivationPlacementData type: object description: Batch-activation placement resource data properties: type: type: string enum: - placementBatchActivation id: type: string description: Unique identifier of the placement (UUID v7) attributes: $ref: '#/components/schemas/organizationsBatchActivationPlacementAttributes' relationships: $ref: '#/components/schemas/organizationsSlottedPlacementRelationships' description: >- JSON:API relationships for the placement. Always present on a batch-activation placement; the `slots` to-many relationship lists the slot resource identifiers. required: - type - id - attributes - relationships organizationsBatchActivationPlacementAttributes: title: organizationsBatchActivationPlacementAttributes type: object description: >- Attributes for a batch-activation placement. Slot detail is exposed via `relationships.slots` (resource identifiers) and the `batchActivationSlot` entries in `included`; request `?include=slots` (or a deeper path) to get the slot details. properties: name: type: string description: Name of the placement organizationId: type: string description: ID of the organization this placement belongs to refreshInterval: type: string description: >- ISO-8601 duration that controls how often the activation cohort refreshes (e.g. "P7D" for weekly). required: - name - organizationId - refreshInterval organizationsGroupPlacementData: title: organizationsGroupPlacementData type: object description: Group placement resource data properties: type: type: string enum: - placementGroup id: type: string description: Unique identifier of the placement (UUID v7) attributes: $ref: '#/components/schemas/organizationsGroupPlacementAttributes' relationships: $ref: '#/components/schemas/organizationsSlottedPlacementRelationships' description: >- JSON:API relationships for the placement. Always present on a group placement; the `slots` to-many relationship lists the slot resource identifiers. required: - type - id - attributes - relationships organizationsGroupPlacementAttributes: title: organizationsGroupPlacementAttributes type: object description: >- Attributes for a group placement. A group is configured like a batch-activation placement but has no refreshInterval. Slot detail is exposed via `relationships.slots` (resource identifiers) and the `batchActivationSlot` entries in `included`; request `?include=slots` (or a deeper path) to get the slot details. properties: name: type: string description: Name of the placement organizationId: type: string description: ID of the organization this placement belongs to required: - name - organizationId organizationsBatchActivationSlotAttributes: title: organizationsBatchActivationSlotAttributes type: object description: Attributes block for a `batchActivationSlot` resource. properties: alias: type: string description: Customer-defined alias for the slot, unique within the placement. shortDescription: type: string nullable: true description: Optional short description of the slot, limited to 50 characters. required: - alias organizationsBatchActivationSlotRelationships: title: organizationsBatchActivationSlotRelationships type: object description: Relationship block for a `batchActivationSlot` resource. properties: placement: $ref: '#/components/schemas/organizationsToOneRelationship' description: >- Reference to the placement that fills this slot. The referenced placement provides the slot's content strategy and offer-count cap; request `?include=slots.placement` to embed it in `included`. required: - placement organizationsIncludedResource: title: organizationsIncludedResource oneOf: - $ref: '#/components/schemas/organizationsContentStrategyInclusion' - $ref: '#/components/schemas/organizationsBatchActivationSlotInclusion' - $ref: '#/components/schemas/organizationsPlacementData' - $ref: '#/components/schemas/organizationsPushNotificationPlacementData' - $ref: '#/components/schemas/organizationsEmailPlacementData' description: >- Discriminated union of every resource type that can appear in the `included` array. The shape of each branch matches the corresponding primary-data resource (same attributes and relationships), keyed on the JSON:API `type` discriminant. discriminator: propertyName: type mapping: contentStrategy: '#/components/schemas/organizationsContentStrategyInclusion' batchActivationSlot: '#/components/schemas/organizationsBatchActivationSlotInclusion' placement: '#/components/schemas/organizationsPlacementData' placementPushNotification: '#/components/schemas/organizationsPushNotificationPlacementData' placementEmail: '#/components/schemas/organizationsEmailPlacementData' organizationsContentStrategyInclusion: title: organizationsContentStrategyInclusion type: object description: Content strategy as it appears in the `included` array. properties: type: type: string enum: - contentStrategy id: type: string attributes: $ref: '#/components/schemas/organizationsContentStrategyAttributes' required: - type - id - attributes organizationsBatchActivationSlotInclusion: title: organizationsBatchActivationSlotInclusion type: object description: Slot resource as it appears in the `included` array. properties: type: type: string enum: - batchActivationSlot id: type: string attributes: $ref: '#/components/schemas/organizationsBatchActivationSlotAttributes' relationships: $ref: '#/components/schemas/organizationsBatchActivationSlotRelationships' required: - type - id - attributes - relationships organizationsPlacementResource: title: organizationsPlacementResource type: object description: Single placement document, optionally with embedded related resources properties: data: $ref: '#/components/schemas/organizationsPlacementFormatUnion' description: Placement resource included: type: array items: $ref: '#/components/schemas/organizationsIncludedResource' nullable: true description: >- Related resources requested via the `include` query parameter. Each entry is keyed by its `type` discriminant (`contentStrategy`, `batchActivationSlot`, `placement`, `placementPushNotification`, `placementEmail`). required: - data organizationsPlacementListResponse: title: organizationsPlacementListResponse type: object description: Paginated list of placements properties: data: type: array items: $ref: '#/components/schemas/organizationsPlacementFormatUnion' description: Array of placement resources included: type: array items: $ref: '#/components/schemas/organizationsIncludedResource' nullable: true description: >- Related resources requested via the `include` query parameter. Each entry is keyed by its `type` discriminant (`contentStrategy`, `batchActivationSlot`, `placement`, `placementPushNotification`, `placementEmail`). links: $ref: '#/components/schemas/Links' nullable: true meta: $ref: '#/components/schemas/OrganizationPaginationMetadata' nullable: true description: Pagination metadata required: - data organizationsCreatePlacementRequestBody: title: organizationsCreatePlacementRequestBody type: object description: Request body for creating a placement properties: data: $ref: '#/components/schemas/organizationsCreatePlacementDataUnion' description: Placement data for creation required: - data organizationsCreatePlacementDataUnion: title: organizationsCreatePlacementDataUnion oneOf: - $ref: '#/components/schemas/organizationsCreateStandardPlacementData' - $ref: '#/components/schemas/organizationsCreatePushNotificationPlacementData' - $ref: '#/components/schemas/organizationsCreateEmailPlacementData' - $ref: '#/components/schemas/organizationsCreateBatchActivationPlacementData' - $ref: '#/components/schemas/organizationsCreateGroupPlacementData' description: Discriminated union for creating a placement discriminator: propertyName: type mapping: placement: '#/components/schemas/organizationsCreateStandardPlacementData' placementPushNotification: '#/components/schemas/organizationsCreatePushNotificationPlacementData' placementEmail: '#/components/schemas/organizationsCreateEmailPlacementData' placementBatchActivation: '#/components/schemas/organizationsCreateBatchActivationPlacementData' placementGroup: '#/components/schemas/organizationsCreateGroupPlacementData' organizationsCreateStandardPlacementData: title: organizationsCreateStandardPlacementData type: object description: Data for creating a standard placement properties: type: type: string enum: - placement attributes: $ref: '#/components/schemas/organizationsCreateStandardAttributes' description: Standard placement attributes for creation required: - type - attributes organizationsCreatePushNotificationPlacementData: title: organizationsCreatePushNotificationPlacementData type: object description: Data for creating a push-notification placement properties: type: type: string enum: - placementPushNotification attributes: $ref: '#/components/schemas/organizationsCreatePushNotificationAttributes' description: Push-notification placement attributes for creation required: - type - attributes organizationsCreateEmailPlacementData: title: organizationsCreateEmailPlacementData type: object description: Data for creating an email placement properties: type: type: string enum: - placementEmail attributes: $ref: '#/components/schemas/organizationsCreateEmailAttributes' description: Email placement attributes for creation required: - type - attributes organizationsCreateStandardAttributes: title: organizationsCreateStandardAttributes type: object description: Attributes for creating a standard placement properties: name: type: string description: Name of the placement displayName: type: string nullable: true description: >- Cardholder-facing title for the section (minimum 1 character). Omit to let clients use their default label. availableSlots: type: integer description: Number of available slots (minimum 1) contentStrategyId: type: string nullable: true description: ID of the content strategy to link this placement to required: - name - availableSlots organizationsCreatePushNotificationAttributes: title: organizationsCreatePushNotificationAttributes type: object description: Attributes for creating a push-notification placement properties: name: type: string description: Name of the placement status: $ref: '#/components/schemas/organizationsPlacementStatus' nullable: true description: >- Placement status. Defaults to ACTIVE on create; when omitted on update, the current status is preserved. cadence: $ref: '#/components/schemas/organizationsCadence' description: Delivery cadence for the notification contentStrategyId: type: string nullable: true description: ID of the content strategy to link this placement to required: - name - cadence organizationsCreateEmailAttributes: title: organizationsCreateEmailAttributes type: object description: Attributes for creating an email placement properties: name: type: string description: Name of the placement status: $ref: '#/components/schemas/organizationsPlacementStatus' nullable: true description: >- Placement status. Defaults to ACTIVE on create; when omitted on update, the current status is preserved. availableSlots: type: integer description: Number of available slots (minimum 1) cadence: $ref: '#/components/schemas/organizationsCadence' description: Delivery cadence for the email contentStrategyId: type: string nullable: true description: ID of the content strategy to link this placement to required: - name - availableSlots - cadence organizationsCreateBatchActivationPlacementData: title: organizationsCreateBatchActivationPlacementData type: object description: Data for creating a batch-activation placement properties: type: type: string enum: - placementBatchActivation attributes: $ref: '#/components/schemas/organizationsCreateBatchActivationAttributes' description: Batch-activation placement attributes for creation required: - type - attributes organizationsCreateBatchActivationSlot: title: organizationsCreateBatchActivationSlot type: object description: A slot in a batch-activation or group placement at creation time properties: placementId: type: string description: >- ID of another placement that fills this slot. The referenced placement provides both the content strategy and the limit on the number of offers available to the slot. alias: type: string description: Customer-defined alias for the slot, unique within the placement shortDescription: type: string nullable: true description: Optional short description of the slot, limited to 50 characters required: - placementId - alias organizationsCreateBatchActivationAttributes: title: organizationsCreateBatchActivationAttributes type: object description: Attributes for creating a batch-activation placement properties: name: type: string description: Name of the placement refreshInterval: type: string description: >- ISO-8601 duration controlling how often the activation cohort refreshes slots: type: array items: $ref: '#/components/schemas/organizationsCreateBatchActivationSlot' description: Slots that make up the activation cohort required: - name - refreshInterval - slots organizationsCreateGroupPlacementData: title: organizationsCreateGroupPlacementData type: object description: Data for creating a group placement properties: type: type: string enum: - placementGroup attributes: $ref: '#/components/schemas/organizationsCreateGroupAttributes' description: Group placement attributes for creation required: - type - attributes organizationsCreateGroupAttributes: title: organizationsCreateGroupAttributes type: object description: Attributes for creating a group placement properties: name: type: string description: Name of the placement slots: type: array items: $ref: '#/components/schemas/organizationsCreateBatchActivationSlot' description: Slots that make up the group required: - name - slots organizationsUpdatePlacementRequestBody: title: organizationsUpdatePlacementRequestBody type: object description: Request body for updating a placement properties: data: $ref: '#/components/schemas/organizationsUpdatePlacementDataUnion' description: Placement data for update required: - data organizationsUpdatePlacementDataUnion: title: organizationsUpdatePlacementDataUnion oneOf: - $ref: '#/components/schemas/organizationsUpdateStandardPlacementData' - $ref: '#/components/schemas/organizationsUpdatePushNotificationPlacementData' - $ref: '#/components/schemas/organizationsUpdateEmailPlacementData' - $ref: '#/components/schemas/organizationsUpdateBatchActivationPlacementData' - $ref: '#/components/schemas/organizationsUpdateGroupPlacementData' description: Discriminated union for updating a placement discriminator: propertyName: type mapping: placement: '#/components/schemas/organizationsUpdateStandardPlacementData' placementPushNotification: '#/components/schemas/organizationsUpdatePushNotificationPlacementData' placementEmail: '#/components/schemas/organizationsUpdateEmailPlacementData' placementBatchActivation: '#/components/schemas/organizationsUpdateBatchActivationPlacementData' placementGroup: '#/components/schemas/organizationsUpdateGroupPlacementData' organizationsUpdateStandardPlacementData: title: organizationsUpdateStandardPlacementData type: object description: Data for updating a standard placement properties: type: type: string enum: - placement attributes: $ref: '#/components/schemas/organizationsUpdateStandardAttributes' description: Standard placement attributes for update required: - type - attributes organizationsUpdatePushNotificationPlacementData: title: organizationsUpdatePushNotificationPlacementData type: object description: Data for updating a push-notification placement properties: type: type: string enum: - placementPushNotification attributes: $ref: '#/components/schemas/organizationsUpdatePushNotificationAttributes' description: Push-notification placement attributes for update required: - type - attributes organizationsUpdateEmailPlacementData: title: organizationsUpdateEmailPlacementData type: object description: Data for updating an email placement properties: type: type: string enum: - placementEmail attributes: $ref: '#/components/schemas/organizationsUpdateEmailAttributes' description: Email placement attributes for update required: - type - attributes organizationsUpdateStandardAttributes: title: organizationsUpdateStandardAttributes type: object description: Attributes for updating a standard placement. All fields are required. properties: name: type: string description: Name of the placement displayName: type: string nullable: true description: >- Cardholder-facing title for the section (minimum 1 character). Omit to clear it (PUT requires the full attribute set). availableSlots: type: integer description: Number of available slots (minimum 1) contentStrategyId: type: string nullable: true description: >- ID of the content strategy to link this placement to. Omit to clear any existing link (PUT requires the full attribute set, so a missing value unlinks the placement). required: - name - availableSlots organizationsUpdatePushNotificationAttributes: title: organizationsUpdatePushNotificationAttributes type: object description: >- Attributes for updating a push-notification placement. All fields are required. properties: name: type: string description: Name of the placement status: $ref: '#/components/schemas/organizationsPlacementStatus' nullable: true description: >- Placement status. Defaults to ACTIVE on create; when omitted on update, the current status is preserved. cadence: $ref: '#/components/schemas/organizationsCadence' description: Delivery cadence for the notification contentStrategyId: type: string nullable: true description: >- ID of the content strategy to link this placement to. Omit to clear any existing link (PUT requires the full attribute set, so a missing value unlinks the placement). required: - name - cadence organizationsUpdateEmailAttributes: title: organizationsUpdateEmailAttributes type: object description: Attributes for updating an email placement. All fields are required. properties: name: type: string description: Name of the placement status: $ref: '#/components/schemas/organizationsPlacementStatus' nullable: true description: >- Placement status. Defaults to ACTIVE on create; when omitted on update, the current status is preserved. availableSlots: type: integer description: Number of available slots (minimum 1) cadence: $ref: '#/components/schemas/organizationsCadence' description: Delivery cadence for the email contentStrategyId: type: string nullable: true description: >- ID of the content strategy to link this placement to. Omit to clear any existing link (PUT requires the full attribute set, so a missing value unlinks the placement). required: - name - availableSlots - cadence organizationsUpdateBatchActivationPlacementData: title: organizationsUpdateBatchActivationPlacementData type: object description: Data for updating a batch-activation placement properties: type: type: string enum: - placementBatchActivation attributes: $ref: '#/components/schemas/organizationsUpdateBatchActivationAttributes' description: Batch-activation placement attributes for update required: - type - attributes organizationsUpdateBatchActivationSlot: title: organizationsUpdateBatchActivationSlot type: object description: A slot in a batch-activation or group placement at update time properties: slotId: type: string nullable: true description: >- Existing slot identifier. Echo the value from a prior GET to keep the slot stable; omit to mint a fresh slot. If the placementId changes, the slotId is regenerated regardless of what was echoed. placementId: type: string description: >- ID of another placement that fills this slot. The referenced placement provides both the content strategy and the limit on the number of offers available to the slot. alias: type: string description: Customer-defined alias for the slot, unique within the placement shortDescription: type: string nullable: true description: Optional short description of the slot, limited to 50 characters required: - placementId - alias organizationsUpdateBatchActivationAttributes: title: organizationsUpdateBatchActivationAttributes type: object description: >- Attributes for updating a batch-activation placement. All fields are required. properties: name: type: string description: Name of the placement refreshInterval: type: string description: >- ISO-8601 duration controlling how often the activation cohort refreshes slots: type: array items: $ref: '#/components/schemas/organizationsUpdateBatchActivationSlot' description: >- Slots that make up the activation cohort. Slots present in the prior state but absent from this list are removed. required: - name - refreshInterval - slots organizationsUpdateGroupPlacementData: title: organizationsUpdateGroupPlacementData type: object description: Data for updating a group placement properties: type: type: string enum: - placementGroup attributes: $ref: '#/components/schemas/organizationsUpdateGroupAttributes' description: Group placement attributes for update required: - type - attributes organizationsUpdateGroupAttributes: title: organizationsUpdateGroupAttributes type: object description: Attributes for updating a group placement. All fields are required. properties: name: type: string description: Name of the placement slots: type: array items: $ref: '#/components/schemas/organizationsUpdateBatchActivationSlot' description: >- Slots that make up the group. Slots present in the prior state but absent from this list are removed. required: - name - slots NetworkBlockedErrorBody: title: NetworkBlockedErrorBody type: object description: Error response indicating that the network is blocked. properties: message: type: string description: A message indicating that the network is blocked. required: - message PingResponseObject: title: PingResponseObject type: object description: Response indicating the status of the ping. properties: message: type: string description: A message indicating the status of the ping. status: type: string description: The status of the ping. timestamp: type: string description: The timestamp of the ping. required: - message - status - timestamp TransactionsResponseData: title: TransactionsResponseData type: object properties: type: $ref: '#/components/schemas/ResourceType' id: type: string description: The request id of the pending job attributes: $ref: '#/components/schemas/Job' required: - type - id - attributes TransactionsRequestBody: title: TransactionsRequestBody type: object properties: data: type: array items: $ref: '#/components/schemas/Transactions' description: >- Discriminated union representing the request body for submitting a transaction. Use `type` to distinguish between the two: - `transaction`: For transactions requiring processing and matching by the Kard system. - `coreTransaction`: For transactions from core banking systems with limited card-level data. required: - data Transactions: title: Transactions oneOf: - $ref: '#/components/schemas/TransactionsRequest' - $ref: '#/components/schemas/CoreTransactionRequest' discriminator: propertyName: type mapping: transaction: '#/components/schemas/TransactionsRequest' coreTransaction: '#/components/schemas/CoreTransactionRequest' TransactionsRequest: title: TransactionsRequest type: object properties: type: type: string enum: - transaction id: type: string description: >- Unique identifier for the transaction event. This must be unique for each distinct event sent to the API. attributes: $ref: '#/components/schemas/TransactionsAttributes' required: - type - id - attributes TransactionsAttributes: title: TransactionsAttributes type: object properties: userId: type: string description: The ID of the user as defined on the issuers system amount: type: integer description: Transaction amount in cents subtotal: type: integer nullable: true description: >- The base amount in cents excluding additional charges (such as tips, taxes, and other fees). status: $ref: '#/components/schemas/TransactionStatus' description: Transaction status currency: type: string description: Currency of transaction description: type: string description: >- Description of transaction - usually includes merchant and other key details on transaction description2: type: string nullable: true description: >- Description2 of transaction — usually includes other merchant identifying information mcc: type: string nullable: true description: >- Merchant Category Code (usually a 4-digit numerical number). Note, this field is REQUIRED for SOME national offers. We HIGHLY RECOMMEND sending this field as it will be required in the near future. coreProviderId: type: string nullable: true description: Name of processor associated with transaction transactionDate: type: string format: date-time nullable: true description: >- Timestamp for REVERSED, RETURNED, DECLINED transaction events; REQUIRED for transactions with REVERSED, RETURNED, DECLINED status. Date string should be in ISO 8601 format i.e.`'YYYY-MM-DDThh:mm:ss.sTZD'` where TZD = time zone designator (Z or +hh:mm or -hh:mm) i.e. `1994-11-05T08:15:30-05:00` OR `1994-11-05T08:15:30Z` authorizationDate: type: string format: date-time nullable: true description: >- Timestamp for APPROVED transaction event; REQUIRED for transactions with APPROVED status, and HIGHLY RECOMMENDED to include for transactions with a SETTLED status. Date string should be in ISO 8601 format i.e.`'YYYY-MM-DDThh:mm:ss.sTZD'` where TZD = time zone designator (Z or +hh:mm or -hh:mm) i.e. `1994-11-05T08:15:30-05:00 OR 1994-11-05T08:15:30Z` settledDate: type: string format: date-time nullable: true description: >- Timestamp for SETTLED transaction event, REQUIRED for transactions with SETTLED status. Date string should be in ISO 8601 format i.e.`'YYYY-MM-DDThh:mm:ss.sTZD'` where TZD = time zone designator (Z or +hh:mm or -hh:mm) i.e. `1994-11-05T08:15:30-05:00` OR `1994-11-05T08:15:30Z` merchant: $ref: '#/components/schemas/Merchant' nullable: true description: Merchant details cardPresence: type: string nullable: true description: Whether card was present at time of transaction panEntryMode: type: string nullable: true description: PAN entry mode cardBIN: type: string description: >- Bank identification number (BIN). Must be a valid BIN of 6 digits. If over 6 digits, please send first 6. cardLastFour: type: string description: Card last four digits. authorizationCode: type: string nullable: true description: Transaction approval code retrievalReferenceNumber: type: string nullable: true description: Retrieval Reference Number systemTraceAuditNumber: type: string nullable: true description: System Trace Audit Number acquirerReferenceNumber: type: string nullable: true description: Acquirer Reference Number direction: $ref: '#/components/schemas/DirectionType' description: The direction in which the funds flow - DEBIT or CREDIT paymentType: $ref: '#/components/schemas/TransactionPaymentType' description: The type of payment involved in the transaction. cardNetwork: $ref: '#/components/schemas/CardNetwork' nullable: true description: The card network associated with the transaction transactionId: type: string description: The transaction ID cardProductId: type: string nullable: true description: The card product ID associated with the transaction userZipCode: type: string nullable: true description: The zip code of the user who made the transaction processorMids: $ref: '#/components/schemas/ProcessorMid' nullable: true description: Network specific merchant IDs (MIDs) associated with the transaction accountId: type: string nullable: true description: An account identifier associated to transaction required: - userId - amount - status - currency - description - cardBIN - cardLastFour - direction - paymentType - transactionId CoreTransactionRequest: title: CoreTransactionRequest type: object properties: type: type: string enum: - coreTransaction id: type: string description: >- Unique identifier for the transaction event. This must be unique for each distinct event sent to the API. attributes: $ref: '#/components/schemas/CoreTransactionAttributes' required: - type - id - attributes CoreTransactionAttributes: title: CoreTransactionAttributes type: object properties: userId: type: string description: The ID of the user as defined on the issuers system transactionId: type: string description: The transaction ID from the core banking system amount: type: integer description: Transaction amount in cents currency: type: string description: Currency of transaction in ISO 4217 alpha-3 format description: type: string description: >- Description of transaction - usually includes merchant and other key details on transaction direction: $ref: '#/components/schemas/DirectionType' description: The direction in which the funds flow - DEBIT or CREDIT status: type: string enum: - SETTLED description: Transaction status (always SETTLED for core transactions) settledDate: type: string format: date-time description: >- Timestamp when transaction was settled. Date string should be in ISO 8601 format i.e.'YYYY-MM-DDThh:mm:ss.sTZD' where TZD = time zone designator (Z or +hh:mm or -hh:mm) i.e. 1994-11-05T08:15:30-05:00 OR 1994-11-05T08:15:30Z authorizationDate: type: string format: date-time description: >- Timestamp for transaction authorization. Date string should be in ISO 8601 format i.e.'YYYY-MM-DDThh:mm:ss.sTZD' where TZD = time zone designator (Z or +hh:mm or -hh:mm) i.e. 1994-11-05T08:15:30-05:00 OR 1994-11-05T08:15:30Z financialInstitutionName: type: string nullable: true description: >- Deprecated. Use `financialInstitutionId` instead. Name of the financial institution. financialInstitutionId: type: string nullable: true description: Unique identifier of the financial institution cardLastFours: type: array items: type: string nullable: true description: >- Last four digits of the card(s) that may have been used for the transaction. When the issuer cannot determine which specific card was used, multiple values are provided as candidates. required: - userId - transactionId - amount - currency - description - direction - status - settledDate - authorizationDate TransactionsResponse: title: TransactionsResponse type: object properties: data: $ref: '#/components/schemas/TransactionsResponseData' required: - data TransactionsMultiResponse: title: TransactionsMultiResponse type: object properties: data: $ref: '#/components/schemas/TransactionsResponseData' required: - data allOf: - $ref: '#/components/schemas/ErrorResponse' CreateAuditRequestBody: title: CreateAuditRequestBody type: object properties: data: type: array items: $ref: '#/components/schemas/CreateAuditRequestDataUnion' required: - data CreateAuditRequestDataUnion: title: CreateAuditRequestDataUnion oneOf: - $ref: '#/components/schemas/AuditRequestData' discriminator: propertyName: type mapping: audit: '#/components/schemas/AuditRequestData' AuditRequestData: title: AuditRequestData type: object properties: type: type: string enum: - audit attributes: $ref: '#/components/schemas/AuditAttributes' required: - type - attributes AuditAttributes: title: AuditAttributes type: object properties: auditCode: type: integer description: >- Audit Code - Enum. Please submit the code that is most relevant to your audit request. merchantName: type: string description: Merchant name related to the transaction audit auditDescription: type: string description: Audit Description. Please provide more details around the audit transactionId: type: string description: Transaction ID from issuer to audit required: - auditCode - merchantName - auditDescription - transactionId CreateAuditResponseBody: title: CreateAuditResponseBody type: object properties: data: type: array items: $ref: '#/components/schemas/CreateAuditResponseDataUnion' required: - data CreateAuditMultiStatusResponse: title: CreateAuditMultiStatusResponse type: object properties: data: type: array items: $ref: '#/components/schemas/CreateAuditResponseDataUnion' nullable: true allOf: - $ref: '#/components/schemas/ErrorResponse' CreateAuditResponseDataUnion: title: CreateAuditResponseDataUnion oneOf: - $ref: '#/components/schemas/AuditResponseData' discriminator: propertyName: type mapping: audit: '#/components/schemas/AuditResponseData' AuditResponseData: title: AuditResponseData type: object properties: type: type: string enum: - audit id: type: string description: Audit Request ID attributes: $ref: '#/components/schemas/AuditResponseAttributes' required: - type - id - attributes AuditResponseAttributes: title: AuditResponseAttributes type: object properties: transactionId: type: string description: Cardlinked Transaction ID required: - transactionId Merchant: title: Merchant type: object properties: id: type: string nullable: true description: >- Acquirer Merchant Identification Number (MID) — usually a 15 digit numerical identifier code. Note, this field is REQUIRED for local offers. We HIGHLY RECOMMEND sending this field as it will be required in the near future. name: type: string description: Merchant name associated with transaction addrStreet: type: string nullable: true description: Merchant street address associated with transaction. addrCity: type: string nullable: true description: Merchant address city associated with transaction. addrState: $ref: '#/components/schemas/States' nullable: true description: Merchant address state associated with transaction. addrZipcode: type: string nullable: true description: Merchant address zip code associated with transaction. addrCountry: type: string nullable: true description: Merchant address country associated with transaction. latitude: type: string nullable: true description: Merchant latitude geocoordinate associated with transaction. longitude: type: string nullable: true description: Merchant longitude geocoordinate associated with transaction. storeId: type: string nullable: true description: Merchant store ID where transaction originated from required: - name TransactionStatus: title: TransactionStatus type: string enum: - APPROVED - SETTLED - REVERSED - RETURNED - DECLINED TransactionPaymentType: title: TransactionPaymentType type: string enum: - CARD DirectionType: title: DirectionType type: string enum: - DEBIT - CREDIT States: title: States type: string enum: - AL - AK - AS - AZ - AR - CA - CO - CT - DE - DC - FM - FL - GA - GU - HI - ID - IL - IN - IA - KS - KY - LA - ME - MH - MD - MA - MI - MN - MS - MO - MT - NE - NV - NH - NJ - NM - NY - NC - ND - MP - OH - OK - OR - PW - PA - PR - RI - SC - SD - TN - TX - UT - VT - VI - VA - WA - WV - WI - WY PaymentStatus: title: PaymentStatus type: string enum: - UNPAID - PAID_IN_FULL RewardedTransactionUnion: title: RewardedTransactionUnion oneOf: - $ref: '#/components/schemas/RewardedTransaction' - $ref: '#/components/schemas/ApprovedTransaction' discriminator: propertyName: type mapping: rewardedTransaction: '#/components/schemas/RewardedTransaction' approvedTransaction: '#/components/schemas/ApprovedTransaction' RewardedTransaction: title: RewardedTransaction type: object properties: type: type: string enum: - rewardedTransaction id: type: string description: Unique transaction identifier attributes: $ref: '#/components/schemas/RewardedTransactionAttributes' relationships: $ref: '#/components/schemas/RewardedTransactionRelationships' required: - type - id - attributes - relationships RewardedTransactionAttributes: title: RewardedTransactionAttributes type: object properties: status: type: string enum: - SETTLED description: Status of the rewarded transaction transactionId: type: string description: The transaction identifier transactionAmountInCents: type: integer description: Transaction amount in cents transactionTimestamp: type: string format: date-time description: Timestamp of the transaction in ISO 8601 format paidToIssuer: $ref: '#/components/schemas/PaymentStatus' description: Payment status to issuer commissionEarned: $ref: '#/components/schemas/CommissionEarnedDetails' payoutTimestamp: type: string format: date-time nullable: true description: >- Timestamp representing the month when the transaction has been paid out to issuer components: $ref: '#/components/schemas/OfferComponents' nullable: true description: >- UI component data for the reward, built from the offer state persisted on the matched transaction (e.g. a progress bar for progressive and punch-card offers). Omitted when the reward carries no persisted state. required: - status - transactionId - transactionAmountInCents - transactionTimestamp - paidToIssuer - commissionEarned ApprovedTransaction: title: ApprovedTransaction type: object properties: type: type: string enum: - approvedTransaction id: type: string description: Unique transaction identifier attributes: $ref: '#/components/schemas/ApprovedTransactionAttributes' relationships: $ref: '#/components/schemas/RewardedTransactionRelationships' required: - type - id - attributes - relationships ApprovedTransactionAttributes: title: ApprovedTransactionAttributes type: object properties: status: type: string enum: - APPROVED description: Status of the approved transaction transactionId: type: string description: The transaction identifier transactionAmountInCents: type: integer description: Transaction amount in cents transactionTimestamp: type: string format: date-time description: Timestamp of the transaction in ISO 8601 format required: - status - transactionId - transactionAmountInCents - transactionTimestamp CommissionEarnedDetails: title: CommissionEarnedDetails type: object properties: user: $ref: '#/components/schemas/CommissionValue' required: - user RewardedTransactionRelationships: title: RewardedTransactionRelationships type: object properties: user: $ref: '#/components/schemas/RelationshipSingle' merchant: $ref: '#/components/schemas/RelationshipSingle' offer: $ref: '#/components/schemas/RelationshipSingle' required: - user - merchant - offer TransactionIncludedResource: title: TransactionIncludedResource oneOf: - $ref: '#/components/schemas/TransactionMerchantResource' - $ref: '#/components/schemas/TransactionOfferResource' discriminator: propertyName: type mapping: merchant: '#/components/schemas/TransactionMerchantResource' offer: '#/components/schemas/TransactionOfferResource' TransactionMerchantResource: title: TransactionMerchantResource type: object properties: type: type: string enum: - merchant id: type: string description: Merchant identifier attributes: $ref: '#/components/schemas/TransactionMerchantAttributes' description: Merchant attributes required: - type - id - attributes TransactionMerchantAttributes: title: TransactionMerchantAttributes type: object properties: name: type: string description: Merchant name assets: type: array items: $ref: '#/components/schemas/MerchantAsset' nullable: true description: >- Tracked asset images for the merchant (logo, banner, etc.). Each asset URL is signed for attribution tracking and should be loaded as-is by the client. required: - name MerchantAsset: title: MerchantAsset type: object properties: type: $ref: '#/components/schemas/MerchantAssetType' description: The type of asset being tracked. url: type: string description: Attribution-signed URL for loading the asset. alt: type: string nullable: true description: Alt text describing the asset for accessibility. required: - type - url MerchantAssetType: title: MerchantAssetType type: string enum: - IMG_VIEW - BANNER_VIEW TransactionOfferResource: title: TransactionOfferResource type: object properties: type: type: string enum: - offer id: type: string description: Offer identifier attributes: $ref: '#/components/schemas/TransactionOfferAttributes' description: Offer attributes required: - type - id - attributes TransactionOfferAttributes: title: TransactionOfferAttributes type: object properties: purchaseChannel: type: array items: type: string description: Purchase channels required: - purchaseChannel RewardedTransactionStatus: title: RewardedTransactionStatus type: string enum: - APPROVED - SETTLED EarnedRewardsRange: title: EarnedRewardsRange type: string enum: - 12M - 6M - 3M - YTD description: >- Time window for earned rewards queries, ending now. `YTD` starts at January 1 of the current year (UTC). GetEarnedRewardsMeta: title: GetEarnedRewardsMeta type: object properties: lifetimeRewardsInCents: type: integer description: >- Lifetime rewards earned by the user across matched transactions in cents, within the window selected by `filter[range]` (default last 12 months). By default all matched transactions are included regardless of payment status; pass `filter[paidInFullOnly]=true` to restrict the total to transactions paid in full to the issuer (`paidToIssuer` is `PAID_IN_FULL`). required: - lifetimeRewardsInCents ProcessorMid: title: ProcessorMid oneOf: - $ref: '#/components/schemas/VisaMid' discriminator: propertyName: processor mapping: VISA: '#/components/schemas/VisaMid' VisaMid: title: VisaMid type: object properties: processor: type: string enum: - VISA mids: $ref: '#/components/schemas/VisaMidDetails' description: Merchant ID (MID) associated with the processor required: - processor - mids VisaMidDetails: title: VisaMidDetails type: object properties: vmid: type: string description: Visa Merchant ID (VMID) associated with the transaction vsid: type: string description: Visa Store ID (VSID) associated with the transaction required: - vmid - vsid GetEarnedRewardsResponse: title: GetEarnedRewardsResponse type: object properties: data: type: array items: $ref: '#/components/schemas/RewardedTransactionUnion' links: $ref: '#/components/schemas/Links' meta: $ref: '#/components/schemas/GetEarnedRewardsMeta' description: Additional metadata for the earned rewards response. included: type: array items: $ref: '#/components/schemas/TransactionIncludedResource' nullable: true description: Additional resources referenced in the response required: - data - links - meta FileUploadType: title: FileUploadType type: string enum: - incomingTransactionsFile - historicalTransactionsFile description: >- Specifies the category of transaction file being uploaded. Use `incomingTransactionsFile` for new, real-time transactions that need to be processed and matched as they arrive. Use `historicalTransactionsFile` for historical transaction ingestion. CreateFileUploadRequestBody: title: CreateFileUploadRequestBody type: object properties: data: type: array items: $ref: '#/components/schemas/CreateFileUploadData' description: List of file upload requests (1–10 items per request). required: - data CreateFileUploadData: title: CreateFileUploadData type: object properties: type: $ref: '#/components/schemas/FileUploadType' attributes: $ref: '#/components/schemas/CreateFileUploadAttributes' required: - type - attributes CreateFileUploadAttributes: title: CreateFileUploadAttributes type: object properties: filename: type: string description: >- Name of the file to upload, including extension (e.g. "transaction_12345.jsonl") required: - filename CreateFileUploadUrlResponse: title: CreateFileUploadUrlResponse type: object properties: data: type: array items: $ref: '#/components/schemas/FileUploadUrlData' description: List of created file upload sessions. required: - data FileUploadUrlData: title: FileUploadUrlData type: object properties: type: $ref: '#/components/schemas/FileUploadType' id: type: string description: Upload session ID for traceability attributes: $ref: '#/components/schemas/FileUploadUrlAttributes' required: - type - id - attributes FileUploadUrlAttributes: title: FileUploadUrlAttributes type: object properties: url: type: string description: |- Presigned PUT URL for uploading the file directly to storage. Use HTTP PUT with binary body. Expires after 15 minutes. expiresIn: type: integer description: Time in seconds until the presigned URL expires (900) required: - url - expiresIn CreateUsersObject: title: CreateUsersObject type: object properties: data: type: array items: $ref: '#/components/schemas/UserRequestDataUnion' required: - data UserRequestDataUnion: title: UserRequestDataUnion oneOf: - $ref: '#/components/schemas/UserRequestData' discriminator: propertyName: type mapping: user: '#/components/schemas/UserRequestData' UserRequestData: title: UserRequestData type: object properties: type: type: string enum: - user id: $ref: '#/components/schemas/UserId' attributes: $ref: '#/components/schemas/UserRequestAttributes' required: - type - id - attributes UserRequestAttributes: title: UserRequestAttributes type: object properties: enrolledRewards: type: array items: $ref: '#/components/schemas/EnrolledRewardsType' description: >- Rewards programs to enroll the user in. If an empty array is supplied, the user will not be enrolled in any programs. zipCode: type: string nullable: true description: Zipcode of user email: type: string nullable: true description: Email address of user hashedEmail: type: string nullable: true description: Hashed email address of user (using SHA-256) phoneNumber: type: string nullable: true description: Phone number of user in E.164 format birthYear: type: string nullable: true description: Birth year of user historicalTransactionsSent: type: boolean nullable: true description: >- Indicates whether historical transactions have been sent for this user required: - enrolledRewards UpdateUserRequestAttributes: title: UpdateUserRequestAttributes type: object properties: enrolledRewards: type: array items: $ref: '#/components/schemas/EnrolledRewardsType' description: >- Rewards programs to enroll the user in. If an empty array is supplied, the user will not be enrolled in any programs. zipCode: type: string nullable: true description: Zipcode of user email: type: string nullable: true description: Email address of user hashedEmail: type: string nullable: true description: Hashed email address of user (using SHA-256) phoneNumber: type: string nullable: true description: Phone number of user in E.164 format birthYear: type: string nullable: true description: Birth year of user historicalTransactionsSent: type: boolean nullable: true description: >- Set to `true` to confirm that historical transactions have been sent for this user. This is a one-way flag: once `true` it cannot be set back to `false`, and a request attempting to do so is rejected. required: - enrolledRewards UpdateUserRequestData: title: UpdateUserRequestData type: object properties: type: type: string enum: - user id: $ref: '#/components/schemas/UserId' attributes: $ref: '#/components/schemas/UpdateUserRequestAttributes' required: - type - id - attributes UpdateUserRequestDataUnion: title: UpdateUserRequestDataUnion oneOf: - $ref: '#/components/schemas/UpdateUserRequestData' discriminator: propertyName: type mapping: user: '#/components/schemas/UpdateUserRequestData' UpdateUserObject: title: UpdateUserObject type: object properties: data: $ref: '#/components/schemas/UpdateUserRequestDataUnion' required: - data UserResponseObject: title: UserResponseObject type: object properties: data: $ref: '#/components/schemas/UserRequestDataUnion' required: - data DeleteUserResponseObject: title: DeleteUserResponseObject type: object properties: data: $ref: '#/components/schemas/UserResponseUnionNoData' required: - data UserResponseUnionNoData: title: UserResponseUnionNoData oneOf: - $ref: '#/components/schemas/UserResponseNoData' discriminator: propertyName: type mapping: user: '#/components/schemas/UserResponseNoData' UserResponseNoData: title: UserResponseNoData type: object properties: type: type: string enum: - user id: $ref: '#/components/schemas/UserId' attributes: $ref: '#/components/schemas/EmptyObject' required: - type - id - attributes CreateUsersMultiStatusResponse: title: CreateUsersMultiStatusResponse type: object properties: data: type: array items: $ref: '#/components/schemas/UserRequestDataUnion' nullable: true allOf: - $ref: '#/components/schemas/ErrorResponse' usersCreateAttributionRequestObject: title: usersCreateAttributionRequestObject type: object properties: data: type: array items: $ref: '#/components/schemas/usersCreateAttributionRequestUnion' description: >- Discriminated union representing the request body for submitting attribution events. Use `type` to distinguish between the two: - `offerAttribution`: Events related to viewing or interacting with an offer. - `notificationAttribution`: Events related to viewing or interacting with a notification. required: - data usersCreateAttributionRequestUnion: title: usersCreateAttributionRequestUnion oneOf: - $ref: '#/components/schemas/usersOfferAttributionRequest' - $ref: '#/components/schemas/usersNotificationAttributionRequest' - $ref: '#/components/schemas/usersPlacementSlotAttributionRequest' discriminator: propertyName: type mapping: offerAttribution: '#/components/schemas/usersOfferAttributionRequest' notificationAttribution: '#/components/schemas/usersNotificationAttributionRequest' placementSlotAttribution: '#/components/schemas/usersPlacementSlotAttributionRequest' usersOfferAttributionRequest: title: usersOfferAttributionRequest type: object properties: type: type: string enum: - offerAttribution attributes: $ref: '#/components/schemas/usersOfferAttributionAttributes' required: - type - attributes usersOfferAttributionAttributes: title: usersOfferAttributionAttributes type: object properties: entityId: type: string description: The offer ID eventCode: $ref: '#/components/schemas/usersEventCode' medium: $ref: '#/components/schemas/usersOfferMedium' eventDate: type: string format: date-time description: |- The timestamp of the attribution event. Must be in ISO 8601 format (e.g., "2025-01-01T00:00:00Z"). state: $ref: '#/components/schemas/usersAttributionState' nullable: true description: Placement context for the attribution event required: - entityId - eventCode - medium - eventDate usersNotificationAttributionRequest: title: usersNotificationAttributionRequest type: object properties: type: type: string enum: - notificationAttribution attributes: $ref: '#/components/schemas/usersNotificationAttributionAttributes' required: - type - attributes usersNotificationAttributionAttributes: title: usersNotificationAttributionAttributes type: object properties: entityId: type: string description: The notification ID eventCode: $ref: '#/components/schemas/usersEventCode' medium: $ref: '#/components/schemas/usersNotificationMedium' eventDate: type: string format: date-time description: |- The timestamp of the attribution event. Must be in ISO 8601 format (e.g., "2025-01-01T00:00:00Z"). state: $ref: '#/components/schemas/usersAttributionState' nullable: true description: Placement context for the attribution event required: - entityId - eventCode - medium - eventDate usersPlacementSlotAttributionRequest: title: usersPlacementSlotAttributionRequest type: object properties: type: type: string enum: - placementSlotAttribution attributes: $ref: '#/components/schemas/usersPlacementSlotAttributionAttributes' required: - type - attributes usersPlacementSlotAttributionAttributes: title: usersPlacementSlotAttributionAttributes type: object description: >- Attributes for a slot-level activation event on a batch-activation placement. A slot activation also writes per-offer `offerAttribution` ACTIVATE events for every offer resolved by the slot's content strategy (see `ActivatePlacementSlot`). properties: entityId: type: string description: The slot ID (matches `state.slotId`) eventCode: $ref: '#/components/schemas/usersEventCode' medium: $ref: '#/components/schemas/usersPlacementSlotMedium' eventDate: type: string format: date-time description: |- The timestamp of the attribution event. Must be in ISO 8601 format (e.g., "2025-01-01T00:00:00Z"). state: $ref: '#/components/schemas/usersAttributionState' nullable: true description: Placement context for the attribution event required: - entityId - eventCode - medium - eventDate usersEventCode: title: usersEventCode type: string enum: - IMPRESSION - VIEW - ACTIVATE - BOOST description: The event code of attribution event. usersOfferMedium: title: usersOfferMedium type: string enum: - BROWSE - EMAIL - MAP - SEARCH - CTA - PUSH description: >- Where the offer attribution event is taking place in your rewards experience. usersAttributionState: title: usersAttributionState type: object properties: rank: type: integer nullable: true description: The position of the offer in the list shown to the user (1-indexed) filters: type: array items: $ref: '#/components/schemas/usersAttributionFilter' nullable: true description: The active filters when the user saw the offer placementId: type: string nullable: true description: >- Unique identifier of the placement the attribution event originated from slotId: type: string nullable: true description: Stable identifier for the slot within the placement usersAttributionFilter: title: usersAttributionFilter type: object properties: name: type: string value: type: string required: - name - value usersNotificationMedium: title: usersNotificationMedium type: string enum: - PUSH - EMAIL description: >- Where the notification attribution event is taking place in your rewards experience. usersPlacementSlotMedium: title: usersPlacementSlotMedium type: string enum: - CTA description: >- Where the placement-slot attribution event is taking place in your rewards experience. usersCreateAttributionResponse: title: usersCreateAttributionResponse type: object properties: data: $ref: '#/components/schemas/JobResponse' required: - data usersActivateOfferIncludeOption: title: usersActivateOfferIncludeOption type: string enum: - offer description: Options for what to include in the activate offer response usersActivateOfferResponse: title: usersActivateOfferResponse type: object properties: data: $ref: '#/components/schemas/usersActivateOfferResponseData' included: type: array items: $ref: '#/components/schemas/usersActivateOfferIncluded' nullable: true required: - data usersActivateOfferIncluded: title: usersActivateOfferIncluded oneOf: - $ref: '#/components/schemas/usersOfferDataUnion' - $ref: '#/components/schemas/usersCategoryIncluded' usersActivateOfferResponseData: title: usersActivateOfferResponseData type: object properties: type: type: string id: type: string attributes: $ref: '#/components/schemas/usersActivateOfferResponseAttributes' required: - type - id - attributes usersActivateOfferResponseAttributes: title: usersActivateOfferResponseAttributes type: object properties: entityId: type: string eventCode: type: string medium: type: string eventDate: type: string format: date-time required: - entityId - eventCode - medium - eventDate usersBoostOfferIncludeOption: title: usersBoostOfferIncludeOption type: string enum: - offer description: Options for what to include in the boost offer response usersBoostOfferResponse: title: usersBoostOfferResponse type: object properties: data: $ref: '#/components/schemas/usersBoostOfferResponseData' included: type: array items: $ref: '#/components/schemas/usersBoostOfferIncluded' nullable: true required: - data usersBoostOfferIncluded: title: usersBoostOfferIncluded oneOf: - $ref: '#/components/schemas/usersOfferDataUnion' - $ref: '#/components/schemas/usersCategoryIncluded' usersBoostOfferResponseData: title: usersBoostOfferResponseData type: object properties: type: type: string id: type: string attributes: $ref: '#/components/schemas/usersBoostOfferResponseAttributes' required: - type - id - attributes usersBoostOfferResponseAttributes: title: usersBoostOfferResponseAttributes type: object properties: entityId: type: string eventCode: type: string medium: type: string eventDate: type: string format: date-time required: - entityId - eventCode - medium - eventDate usersActivatePlacementSlotResponse: title: usersActivatePlacementSlotResponse type: object description: Ack payload for a slot activation request. properties: data: $ref: '#/components/schemas/usersActivatePlacementSlotResponseData' required: - data usersActivatePlacementSlotResponseData: title: usersActivatePlacementSlotResponseData type: object properties: type: type: string id: type: string description: The slot-level attribution event id attributes: $ref: '#/components/schemas/usersActivatePlacementSlotResponseAttributes' required: - type - id - attributes usersActivatePlacementSlotResponseAttributes: title: usersActivatePlacementSlotResponseAttributes type: object properties: placementId: type: string description: Unique identifier of the placement slotId: type: string description: Stable identifier for the slot within the placement eventCode: type: string medium: type: string eventDate: type: string format: date-time offerIds: type: array items: type: string description: >- All offer IDs that resolved under the slot's content strategy and had per-offer `offerAttribution` ACTIVATE events written. The partner can use this to render the batch immediately without an extra round-trip. required: - placementId - slotId - eventCode - medium - eventDate - offerIds usersWebViewTokenResponse: title: usersWebViewTokenResponse type: object description: An OAuth token response. properties: access_token: type: string expires_in: type: integer token_type: type: string required: - access_token - expires_in - token_type usersOffersResponseObject: title: usersOffersResponseObject type: object properties: data: type: array items: $ref: '#/components/schemas/usersOfferDataUnion' links: $ref: '#/components/schemas/Links' included: type: array items: $ref: '#/components/schemas/usersEligibilityOfferIncluded' nullable: true meta: $ref: '#/components/schemas/usersOffersMeta' nullable: true required: - data - links usersOffersMeta: title: usersOffersMeta type: object description: Metadata about the full result set across all pages properties: availableCategories: type: array items: $ref: '#/components/schemas/usersCategoryIncluded' nullable: true description: >- All distinct categories available across the entire filtered result set, not just the current page placementName: type: string nullable: true description: >- Display name of the placement, resolved server-side from its id. Populated only on the Get Placement Content endpoint; absent on the Get Offers By User endpoint. usersBatchesResponseObject: title: usersBatchesResponseObject type: object description: >- Ordered list of slots for a batch-activation or group placement, with freshness fields and per-slot offer sets. properties: data: type: array items: $ref: '#/components/schemas/usersPlacementBatchData' meta: $ref: '#/components/schemas/usersBatchesMeta' nullable: true required: - data usersBatchesMeta: title: usersBatchesMeta type: object description: Metadata about the placement. properties: placementName: type: string nullable: true description: Display name of the placement, resolved server-side from its id. usersPlacementBatchData: title: usersPlacementBatchData type: object description: >- One slot in a batch-activation or group placement, with freshness fields and the offers that resolve under the slot's content strategy. properties: id: type: string description: Stable identifier for the slot within the placement type: type: string enum: - placementBatch attributes: $ref: '#/components/schemas/usersPlacementBatchAttributes' required: - id - type - attributes usersPlacementBatchAttributes: title: usersPlacementBatchAttributes type: object description: Attributes of a placement batch slot. properties: name: type: string description: >- Display name for the slot. Falls back to the slot's customer-defined alias, or — when the alias is absent — the name of the placement referenced by the slot. isActive: type: boolean description: >- Whether the slot is still considered "fresh" for the user. Set to false only when the slot's `expiresAt` is in the past AND the slot resolves to a non-empty offer set; an empty offer set keeps the slot active so partner UIs do not promote "tap to refresh" with nothing to show. Always true for slots of a group placement, which has no activation cycle. lastActivatedAt: type: string format: date-time nullable: true description: >- Timestamp of the most recent placementSlotAttribution ACTIVATE event for this (user, placement, slot). Absent for cold slots that have never been activated. expiresAt: type: string format: date-time nullable: true description: >- Computed as `lastActivatedAt + placement.refreshInterval`. Absent for cold slots that have never been activated. components: $ref: '#/components/schemas/OfferComponents' nullable: true description: >- Slot-level UI components. Carries `shortDescription` and `longDescription` (activation copy derived from the parent placement's `refreshInterval`), plus either a `cta` (POST to the slot's activate endpoint) when the slot has no active (non-expired) activation, or a `logoFlare` decoration when it does — `cta` and `logoFlare` are mutually exclusive on a single slot. Omitted for slots of a group placement, which has no activation cycle. assets: type: array items: $ref: '#/components/schemas/usersAsset' nullable: true description: >- Slot-level visual assets. Currently a single `IMG_VIEW` SVG showing the slot's initials, themed via the `--icon-fill` CSS custom property. offers: type: array items: $ref: '#/components/schemas/usersOfferDataUnion' description: >- The set of offers eligible for the user under this slot's content strategy. required: - name - isActive - offers usersPlacementContentResponse: title: usersPlacementContentResponse oneOf: - $ref: '#/components/schemas/usersOffersResponseObject' - $ref: '#/components/schemas/usersBatchesResponseObject' description: >- Combined placement-content response. The placement is resolved server-side and the response is returned verbatim as one of two variants: a standard placement yields the offers response (`standardOffer` resources with `links`, optional `included` categories, and `meta`), while a batch-activation or group placement yields the batches response (`placementBatch` slot resources). Callers distinguish the two by each resource's `type` rather than a separate discriminator. usersLocationsResponseObject: title: usersLocationsResponseObject type: object properties: data: type: array items: $ref: '#/components/schemas/usersLocationData' links: $ref: '#/components/schemas/Links' included: type: array items: $ref: '#/components/schemas/usersEligibilityLocationIncluded' nullable: true required: - data - links usersLocationData: title: usersLocationData type: object properties: type: type: string enum: - location id: $ref: '#/components/schemas/MongoId' description: Location ID in Kard's system attributes: $ref: '#/components/schemas/usersLocationAttributes' relationships: $ref: '#/components/schemas/usersLocationRelationships' nullable: true description: Related resources to the offer required: - type - id - attributes usersOfferDataUnion: title: usersOfferDataUnion oneOf: - $ref: '#/components/schemas/usersStandardOffer' discriminator: propertyName: type mapping: standardOffer: '#/components/schemas/usersStandardOffer' usersStandardOfferCore: title: usersStandardOfferCore type: object properties: id: $ref: '#/components/schemas/MongoId' description: Offer ID in Kard's system attributes: $ref: '#/components/schemas/usersStandardOfferFields' required: - id - attributes usersStandardOffer: title: usersStandardOffer type: object properties: type: type: string enum: - standardOffer relationships: $ref: '#/components/schemas/usersEligibilityOfferRelationship' nullable: true allOf: - $ref: '#/components/schemas/usersStandardOfferCore' required: - type usersStandardOfferFields: title: usersStandardOfferFields type: object properties: {} allOf: - $ref: '#/components/schemas/usersOfferCommonFields' usersOfferRelationship: title: usersOfferRelationship type: object properties: offers: $ref: '#/components/schemas/RelationshipMultiple' category: $ref: '#/components/schemas/RelationshipMultiple' required: - offers - category usersOfferCommonFields: title: usersOfferCommonFields type: object properties: terms: type: string description: Terms and conditions on offer maxRedemptions: type: integer nullable: true description: Maximum times cardholder can redeem offer, if applicable name: type: string description: Name of offer purchaseChannel: type: array items: $ref: '#/components/schemas/PurchaseChannel' userReward: $ref: '#/components/schemas/usersCommission' assets: type: array items: $ref: '#/components/schemas/usersAsset' description: Assets associated with offer startDate: type: string format: date-time description: Beginning date of offer (UTC) expirationDate: type: string format: date-time description: Expiration date of offer if applicable (UTC) isTargeted: type: boolean description: >- True returns only targeted offers, false returns only non-targeted offers minTransactionAmount: $ref: '#/components/schemas/usersAmount' nullable: true description: >- Minimum Transaction Amount required to redeem offer, if available on offer maxTransactionAmount: $ref: '#/components/schemas/usersAmount' nullable: true description: >- Maximum Transaction Amount allowed to redeem offer, if available on offer minRewardAmount: $ref: '#/components/schemas/usersAmount' nullable: true description: Minimum Reward Amount, if available on offer maxRewardAmount: $ref: '#/components/schemas/usersAmount' nullable: true description: Maximum Reward Amount, if available on offer websiteUrl: type: string nullable: true description: URL to the website of the offer provider description: type: string nullable: true description: Description of the offer components: $ref: '#/components/schemas/OfferComponents' nullable: true description: >- UI component data for the offer, returned when supportedComponents query parameter is provided required: - terms - name - purchaseChannel - userReward - assets - startDate - expirationDate - isTargeted usersComponentType: title: usersComponentType type: string enum: - shortDescription - longDescription - baseReward - boostedReward - cta - tags - detailTags - logoFlare - progressBar description: Available UI component types for offers usersOfferSortOptions: title: usersOfferSortOptions type: string enum: - startDate - '-startDate' - expirationDate - '-expirationDate' - name - '-name' usersLocationSortOptions: title: usersLocationSortOptions type: string enum: - locationName - '-locationName' usersEligibilityOfferRelationship: title: usersEligibilityOfferRelationship oneOf: - $ref: '#/components/schemas/usersCategoryRelationshipObject' usersEligibilityOfferIncluded: title: usersEligibilityOfferIncluded oneOf: - $ref: '#/components/schemas/usersCategoryIncluded' usersCategoryRelationshipObject: title: usersCategoryRelationshipObject type: object properties: category: $ref: '#/components/schemas/usersCategoryRelationship' required: - category usersCategoryRelationship: title: usersCategoryRelationship type: object properties: data: type: array items: $ref: '#/components/schemas/usersCategoryData' required: - data usersCategoryIncluded: title: usersCategoryIncluded type: object properties: attributes: $ref: '#/components/schemas/usersCategoryFields' required: - attributes allOf: - $ref: '#/components/schemas/usersCategoryIdentifier' usersCategoryData: title: usersCategoryData type: object properties: {} allOf: - $ref: '#/components/schemas/usersCategoryIdentifier' usersCategoryIdentifier: title: usersCategoryIdentifier type: object properties: id: type: string description: id of the category type: type: string enum: - category required: - id - type usersCategoryFields: title: usersCategoryFields type: object properties: name: $ref: '#/components/schemas/CategoryOption' description: Name of the category required: - name usersCommission: title: usersCommission type: object properties: type: $ref: '#/components/schemas/CommissionType' value: type: number format: double required: - type - value usersAmount: title: usersAmount type: object properties: type: $ref: '#/components/schemas/usersAmountType' value: type: integer required: - type - value usersAmountType: title: usersAmountType type: string enum: - CENTS usersAsset: title: usersAsset type: object properties: type: type: string description: >- What the asset shows. `IMG_VIEW` is the merchant logo, `BANNER_VIEW` a promotional banner, and `LOCATION_IMG_VIEW` a photo of the location. New values may be added over time. url: type: string description: URL of the asset containing an attribution token alt: type: string description: Alt text of the asset required: - type - url - alt usersEligibilityLocationIncluded: title: usersEligibilityLocationIncluded oneOf: - $ref: '#/components/schemas/usersOfferDataUnion' - $ref: '#/components/schemas/usersCategoryIncluded' usersLocationAttributes: title: usersLocationAttributes type: object properties: name: type: string address: $ref: '#/components/schemas/usersEligibilityLocationAddress' coordinates: $ref: '#/components/schemas/usersCoordinates' phone: type: string operationHours: $ref: '#/components/schemas/usersOperationHours' partnerIds: type: array items: $ref: '#/components/schemas/usersLocationPartnerId' description: >- List of ids associated with the location from third party partners. Only applicable for LOCAL locations. cuisine: $ref: '#/components/schemas/CuisineOption' nullable: true description: >- The kind of food or venue this location offers, for example "Pizza Restaurant". rating: $ref: '#/components/schemas/usersLocationRating' nullable: true description: Customer rating for this location. priceLevel: type: string nullable: true description: >- Typical price range for this location, rendered as dollar signs from "$" (least expensive) to "$$$$" (most expensive). required: - name - address - coordinates - phone - operationHours - partnerIds - cuisine - rating - priceLevel usersLocationRating: title: usersLocationRating type: object description: Customer rating for a location. properties: value: type: number format: double description: Restaurant star rating. Rating is out of 5. count: type: integer nullable: true description: >- Number of ratings the score is based on. Null when a count is not available. required: - value - count usersLocationPartnerId: title: usersLocationPartnerId type: object properties: type: $ref: '#/components/schemas/usersLocationPartnerIdType' id: type: string required: - type - id usersLocationPartnerIdType: title: usersLocationPartnerIdType type: string enum: - google usersEligibilityLocationAddress: title: usersEligibilityLocationAddress type: object properties: street: type: string city: type: string state: type: string zipCode: type: string required: - street - city - state - zipCode usersCoordinates: title: usersCoordinates type: object properties: longitude: type: number format: double latitude: type: number format: double required: - longitude - latitude usersOperationHours: title: usersOperationHours type: object properties: periods: type: array items: $ref: '#/components/schemas/usersOperationPeriod' weekdayText: type: array items: type: string required: - periods - weekdayText usersOperationPeriod: title: usersOperationPeriod type: object properties: close: $ref: '#/components/schemas/usersOperationTime' open: $ref: '#/components/schemas/usersOperationTime' required: - close - open usersOperationTime: title: usersOperationTime type: object properties: day: type: integer time: type: string required: - day - time usersLocationRelationships: title: usersLocationRelationships type: object properties: {} allOf: - $ref: '#/components/schemas/usersOfferRelationship' securitySchemes: BearerAuth: type: http scheme: bearer servers: - url: https://rewards-api.getkard.com description: Production - url: https://test-rewards-api.getkard.com description: Sandbox