Kard
Kard Rewards API

Kard Rewards API (version 2024-10-01) — enroll users, submit transactions for CLO matching, fetch offers/locations, manage attributions, placements, content strategies, and earned-reward webhook subscriptions.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.1.0
info:
  title: API Reference
  version: 1.0.0
paths:
  /v2/issuers/{organizationId}/transactions:
    post:
      operationId: create
      summary: Create Incoming Transactions
      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.<br/>

        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.

        - `matchedTransaction`: For pre-matched transactions that need validation on match by the Kard system.

        - `coreTransaction`: For transactions from core banking systems with limited card-level data.<br/>


        <b>Required scopes:</b> `transaction:write`<br/>

        <b>Note:</b> `Maximum of 500 transactions can be created per request`.
      tags:
        - transactions
      parameters:
        - name: organizationId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_commons:OrganizationId'
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '202':
          description: Response with status 202
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_transactions:TransactionsResponse'
        '207':
          description: Error response with status 207
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_transactions:TransactionsMultiResponse'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
        '401':
          description: Error response with status 401
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
        '409':
          description: Error response with status 409
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
        '500':
          description: Error response with status 500
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_transactions:TransactionsRequestBody'
  /v2/issuers/{organizationId}/transactions/uploads:
    post:
      operationId: create-bulk-transactions-upload-url
      summary: Create Bulk Transactions Upload URL
      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.

        <b>Required scopes:</b> `files:write`
      tags:
        - transactions
      parameters:
        - name: organizationId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_commons:OrganizationId'
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Response with status 201
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_transactions:CreateFileUploadUrlResponse'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
        '401':
          description: Error response with status 401
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
        '403':
          description: Error response with status 403
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
        '500':
          description: Error response with status 500
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_transactions:CreateFileUploadRequestBody'
  /v2/issuers/{organizationId}/users/{userId}/audits:
    post:
      operationId: create-audits
      summary: Create Audits
      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.<br/>

        <b>Required scopes:</b> `audit:write`
      tags:
        - transactions
      parameters:
        - name: organizationId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_commons:OrganizationId'
        - name: userId
          in: path
          description: The ID of the user as defined on the issuers system
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Response with status 201
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_transactions:CreateAuditResponseBody'
        '207':
          description: Error response with status 207
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_transactions:CreateAuditMultiStatusResponse'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
        '401':
          description: Error response with status 401
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
        '409':
          description: Error response with status 409
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
        '500':
          description: Error response with status 500
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_transactions:CreateAuditRequestBody'
  /v2/issuers/{organizationId}/users/{userId}/earned-rewards:
    get:
      operationId: get-earned-rewards
      summary: Get Earned Rewards
      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[paidInFullOnly]=true` to restrict the
        response to matched transactions that have been paid in full to the issuer (`paidToIssuer` is `PAID_IN_FULL`).

        <br/>

        <b>Required scopes:</b> `transaction:read`

        <br/>

        <b>Query Limit:</b> Maximum of 12 months of transaction data can be queried.
      tags:
        - transactions
      parameters:
        - name: organizationId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_commons: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
        - name: page[before]
          in: query
          description: Cursor for previous page (base64-encoded timestamp + transaction ID)
          required: false
          schema:
            type: string
        - name: page[size]
          in: query
          description: Number of results per page
          required: false
          schema:
            type: integer
        - 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/type_transactions:RewardedTransactionStatus'
        - 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
        - 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
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_transactions:GetEarnedRewardsResponse'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
        '401':
          description: Error response with status 401
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
        '500':
          description: Error response with status 500
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
  /v2/issuers/{organizationId}/users/{userId}/uploads:
    post:
      operationId: create
      summary: Create Upload
      description: >-
        <b>Deprecated.</b> This endpoint is deprecated in favor of the [Create Bulk Transactions Upload
        URL](/2024-10-01/api/transactions/create-bulk-transactions-upload-url) endpoint. New integrations should use the
        bulk flow outlined in the [Historical Transaction
        Uploads](/2024-10-01/api/integration-guides/historical-transaction-uploads) integration guide.


        Call this endpoint to create an upload session and retrieve an upload ID. Using the upload ID in the [Add Upload
        Part](/2024-10-01/api/transactions/uploads/create-part) endpoint, historical transactions can be sent in batches
        for further processing.

        <b>Required scopes:</b> `transaction:write`
      tags:
        - users > uploads
      parameters:
        - name: organizationId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_commons:OrganizationId'
        - name: userId
          in: path
          description: The ID of the user as defined on the issuers system
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_users/uploads:CreateUploadResponseObject'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
        '401':
          description: Error response with status 401
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
        '500':
          description: Error response with status 500
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_users/uploads:CreateUploadRequestObject'
  /v2/issuers/{organizationId}/users/{userId}/uploads/{uploadId}/parts:
    put:
      operationId: create-part
      summary: Add Upload Part
      description: >-
        <b>Deprecated.</b> This endpoint is deprecated in favor of the [Create Bulk Transactions Upload
        URL](/2024-10-01/api/transactions/create-bulk-transactions-upload-url) endpoint. New integrations should use the
        bulk flow outlined in the [Historical Transaction
        Uploads](/2024-10-01/api/integration-guides/historical-transaction-uploads) integration guide.


        Call this endpoint using the upload ID provided in the [Create
        Upload](/2024-10-01/api/transactions/uploads/create) endpoint to add parts to your upload. Currently, this
        endpoint supports adding historical transactions.

        <b>Required scopes:</b> `transaction:write`

        <b>Note:</b> `Maximum of 500 transactions can be uploaded per request`.
      tags:
        - users > uploads
      parameters:
        - name: organizationId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_commons:OrganizationId'
        - name: userId
          in: path
          description: The ID of the user as defined on the issuers system
          required: true
          schema:
            type: string
        - name: uploadId
          in: path
          description: The upload ID identifying the upload session to add parts
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_users/uploads:CreateUploadPartResponseObject'
        '207':
          description: Error response with status 207
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_users/uploads:CreateUploadPartMultiStatusResponse'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
        '401':
          description: Error response with status 401
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
        '500':
          description: Error response with status 500
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_users/uploads:CreateUploadPartRequestObject'
  /v2/issuers/{organizationId}/users/{userId}/uploads/{uploadId}:
    put:
      operationId: update
      summary: Update Upload
      description: >-
        <b>Deprecated.</b> This endpoint is deprecated in favor of the [Create Bulk Transactions Upload
        URL](/2024-10-01/api/transactions/create-bulk-transactions-upload-url) endpoint. New integrations should use the
        bulk flow outlined in the [Historical Transaction
        Uploads](/2024-10-01/api/integration-guides/historical-transaction-uploads) integration guide.


        Call this endpoint to update your upload session. Currently, you can signal completing a historical transactions
        upload.

        <b>Required scopes:</b> `transaction:write`
      tags:
        - users > uploads
      parameters:
        - name: organizationId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_commons:OrganizationId'
        - name: userId
          in: path
          description: The ID of the user as defined on the issuers system
          required: true
          schema:
            type: string
        - name: uploadId
          in: path
          description: The upload ID identifying the upload session to update
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_users/uploads:UpdateUploadResponseObject'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
        '401':
          description: Error response with status 401
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
        '409':
          description: Error response with status 409
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
        '500':
          description: Error response with status 500
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_users/uploads:UpdateUploadRequestObject'
  /v2/issuers/{organizationId}/users:
    post:
      operationId: create
      summary: Create Users
      description: |-
        Call this endpoint to enroll a specified user into your rewards program.<br/>

        <b>Required scopes:</b>&nbsp;&nbsp;`user:write`<br/>
        <b>Note:</b> `Maximum of 100 users can be created per request`.
      tags:
        - users
      parameters:
        - name: organizationId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_commons:OrganizationId'
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '201':
          description: Response with status 201
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_users:CreateUsersObject'
        '207':
          description: Error response with status 207
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_users:CreateUsersMultiStatusResponse'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
        '401':
          description: Error response with status 401
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
        '409':
          description: Error response with status 409
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
        '500':
          description: Error response with status 500
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_users:CreateUsersObject'
  /v2/issuers/{organizationId}/users/{userId}:
    put:
      operationId: update
      summary: Update User
      description: |-
        Call this endpoint to update the details on a specified user.<br/>

        <b>Required scopes:</b> `user:update`
      tags:
        - users
      parameters:
        - name: organizationId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_commons:OrganizationId'
        - name: userId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_commons:UserId'
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_users:UserResponseObject'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
        '401':
          description: Error response with status 401
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
        '500':
          description: Error response with status 500
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/type_users:UpdateUserObject'
    delete:
      operationId: delete
      summary: Delete User
      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.<br/>


        <b>Required scopes:</b> `user:delete`
      tags:
        - users
      parameters:
        - name: organizationId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_commons:OrganizationId'
        - name: userId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_commons:UserId'
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_users:DeleteUserResponseObject'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
        '401':
          description: Error response with status 401
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
        '500':
          description: Error response with status 500
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
    get:
      operationId: get
      summary: Get User By ID
      description: |-
        Call this endpoint to fetch the details on a specified user.<br/>
        <br/>
        <b>Required scopes:</b>&nbsp;&nbsp;`user:read`
      tags:
        - users
      parameters:
        - name: organizationId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_commons:OrganizationId'
        - name: userId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_commons:UserId'
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_users:UserResponseObject'
        '401':
          description: Error response with status 401
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
        '500':
          description: Error response with status 500
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
  /v2/issuers/{organizationId}/users/{userId}/offers:
    get:
      operationId: offers
      summary: Get Offers By User
      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).<br/>

        <b>Required scopes:</b> `rewards:read`
      tags:
        - users > Rewards
      parameters:
        - name: organizationId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_commons:OrganizationId'
        - name: userId
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/type_commons:UserId'
        - name: page[size]
          in: query
          required: false
          schema:
            type: integer
        - name: page[after]
          in: query
          required: false
          schema:
            type: string
        - name: page[before]
          in: query
          required: false
          schema:
            type: string
        - 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
        - name: filter[purchaseChannel]
          in: query
          required: false
          schema:
            type: array
            items:
              $ref: '#/components/schemas/type_commons:PurchaseChannel'
        - name: filter[category]
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/type_commons:CategoryOption'
        - name: filter[isTargeted]
          in: query
          required: false
          schema:
            type: boolean
        - name: sort
          in: query
          description: If provided, response will be sorted by the specified fields
          required: false
          schema:
            $ref: '#/components/schemas/type_users/rewards:OfferSortOptions'
        - name: include
          in: query
          description: CSV list of included resources in the response (e.g "categories"). Allowed value is `categories`.
          required: false
          schema:
            type: string
        - name: supportedComponents
          in: query
          description: UI component types to include in the response.
          required: false
          schema:
            $ref: '#/components/schemas/type_users/rewards:ComponentType'
        - name: Authorization
          in: header
          description: Bearer authentication
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_users/rewards:OffersResponseObject'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
        '401':
          description: Error response with status 401
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
        '500':
          description: Error response with status 500
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons:ErrorResponse'
  /v2/issuers/{organizationId}/users/{userId}/locations:
    get:
      operationId: locations
      summary: Get Locations By User
      description: >-
        Retrieve national and local geographic locations that a specified 

# --- truncated at 32 KB (272 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kard/refs/heads/main/openapi/kard-api-reference-openapi.yaml
Kard Rewards API

Documentation

Specifications

Other Resources

OpenAPI Specification
