Kard rewards API

openapi: 3.2.0
info:
  title: Reference Rewards API
  version: 1.0.0
servers:
- url: https://rewards-api.getkard.com
  description: Production
- url: https://test-rewards-api.getkard.com
  description: Sandbox
tags:
- name: rewards
paths:
  /rewards/merchant/user/{referringPartnerUserId}:
    get:
      operationId: get-merchants-by-user
      summary: Get Eligible Merchants
      description: 'Retrieve national merchants data that a specified user has eligible national offers at. Call this endpoint to build out your [targeted offers UX experience](https://github.com/kard-financial/kard-postman?tab=readme-ov-file#b-targeted-offers). Local merchants and offers details can be found by calling the [Get Eligible Locations](/legacy/api/rewards/locations/get-locations-by-user) endpoint with the `includeLocal` query parameter.<br/>

        <b>Required scopes:</b> `rewards:read`'
      tags:
      - rewards
      parameters:
      - name: referringPartnerUserId
        in: path
        description: Referring partner user ID from issuer that specifies user
        required: true
        schema:
          type: string
      - name: page
        in: query
        description: Page number [>= 0], (default = 0)
        required: false
        schema:
          type: integer
      - name: limit
        in: query
        description: Maximum number of merchants to be returned [1 - 200], (default = 200)
        required: false
        schema:
          type: integer
      - name: category
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_CategoryOption'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/type_rewards_MerchantWithAttribution'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_InvalidRequestUnion'
        '401':
          description: Error response with status 401
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_UnauthorizedErrorBody'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Error response with status 500
          content:
            application/json:
              schema:
                type: string
  /rewards/merchant/{id}:
    get:
      operationId: get-merchant-by-id
      summary: Get Merchant by ID
      description: 'Retrieve merchant data for a specific Kard merchant ID.<br/>

        <b>Required scopes:</b> `rewards:read`'
      tags:
      - rewards
      parameters:
      - name: id
        in: path
        description: The Kard merchant ID to query
        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_rewards_GetMerchantByIdResponse'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_InvalidRequestUnion'
        '401':
          description: Error response with status 401
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_UnauthorizedErrorBody'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Error response with status 500
          content:
            application/json:
              schema:
                type: string
  /rewards/merchant:
    get:
      operationId: get-merchants
      summary: Get Merchants
      description: 'Retrieve ALL national and local merchant data regardless of whether a user is eligible to see them. This endpoint is a legacy endpoint and will no longer be maintained soon. Instead, use [Get Eligible Merchants](/legacy/api/rewards/merchants/get-merchants-by-user) to retrieve national merchant data and build your [targeted offers UX experience](https://github.com/kard-financial/kard-postman?tab=readme-ov-file#b-targeted-offers). Local merchants and offers details can be found by calling the [Get Eligible Locations](/legacy/api/rewards/locations/get-locations-by-user) endpoint with the `includeLocal` query parameter.<br/>

        <b>Required scopes:</b> `rewards:read`'
      tags:
      - rewards
      parameters:
      - name: page
        in: query
        description: Page number [>= 0], (default = 0)
        required: false
        schema:
          type: integer
      - name: limit
        in: query
        description: Maximum number of merchants [1 - 200], (default = 200)
        required: false
        schema:
          type: integer
      - name: source
        in: query
        description: Merchant source
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_Source'
      - name: category
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_CategoryOption'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/type_rewards_Merchant'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_InvalidRequestUnion'
        '401':
          description: Error response with status 401
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_UnauthorizedErrorBody'
        '500':
          description: Error response with status 500
          content:
            application/json:
              schema:
                type: string
  /rewards/merchant/offers/user/{referringPartnerUserId}:
    get:
      operationId: get-offers-by-user
      summary: Get Eligible Offers
      description: 'Retrieve national offers data that a specified user is eligible for. Call this endpoint to build out your [targeted offers UX experience](https://github.com/kard-financial/kard-postman?tab=readme-ov-file#b-targeted-offers). Local merchants and offers details can be found by calling the [Get Eligible Locations](/legacy/api/rewards/locations/get-locations-by-user) endpoint with the `includeLocal` query parameter.<br/>

        <b>Required scopes:</b> `rewards:read`'
      tags:
      - rewards
      parameters:
      - name: referringPartnerUserId
        in: path
        description: Referring partner user ID from issuer that specifies user
        required: true
        schema:
          type: string
      - name: page
        in: query
        description: Page number [>= 0], (default = 0)
        required: false
        schema:
          type: integer
      - name: limit
        in: query
        description: Maximum number of offers to be returned [1 - 200], (default = 200)
        required: false
        schema:
          type: integer
      - name: merchantId
        in: query
        description: Merchant ID in Kard's system
        required: false
        schema:
          type: string
      - name: offerType
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_OfferType'
      - name: category
        in: query
        description: Category of merchant associated with offer. Please use URL Encode for non single word categories. (Food & Beverage should be Food%20%26%20Beverage)
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_CategoryOption'
      - name: isTargeted
        in: query
        description: True returns targeted offers, false returns targeted and non-targeted offers
        required: false
        schema:
          type: boolean
      - name: startDateSort
        in: query
        description: Sort offer start dates chronologically (1 for ascending, -1 for descending)
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_SortOptions'
      - name: expirationDateSort
        in: query
        description: Sort offer expiration dates chronologically (1 for ascending, -1 for descending)
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_SortOptions'
      - name: merchantNameSort
        in: query
        description: Sort merchant names (1 for A-Z, -1 for Z-A)
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_SortOptions'
      - name: supportedComponents
        in: query
        description: UI component types to include in the response.
        required: false
        schema:
          $ref: '#/components/schemas/type_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:
                type: array
                items:
                  $ref: '#/components/schemas/type_rewards_OfferWithAttribution'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_InvalidRequestUnion'
        '401':
          description: Error response with status 401
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_UnauthorizedErrorBody'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Error response with status 500
          content:
            application/json:
              schema:
                type: string
  /rewards/merchant/offers:
    get:
      operationId: get-offers
      summary: Get Offers
      description: 'Retrieve ALL national and local offer data regardless of whether a user is eligible to see them. This endpoint is a legacy endpoint and will no longer be maintained soon. Instead, use [Get Eligible Offers](/legacy/api/rewards/offers/get-offers-by-user) to retrieve national merchant data and build your [targeted offers UX experience](https://github.com/kard-financial/kard-postman?tab=readme-ov-file#b-targeted-offers). Local merchants and offers details can be found by calling the [Get Eligible Locations](/legacy/api/rewards/locations/get-locations-by-user) endpoint with the `includeLocal` query parameter.<br/>

        <b>Required scopes:</b> `rewards:read`'
      tags:
      - rewards
      parameters:
      - name: page
        in: query
        description: Page number [>= 0], (default = 0)
        required: false
        schema:
          type: integer
      - name: limit
        in: query
        description: Maximum number of offers [1 - 200], (default = 200)
        required: false
        schema:
          type: integer
      - name: source
        in: query
        description: Source of merchant associated with offer
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_Source'
      - name: category
        in: query
        description: Category of merchant associated with offer. Please use URL Encode for non single word categories. (Food & Beverage should be Food%20%26%20Beverage)
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_CategoryOption'
      - name: name
        in: query
        description: Name of offer
        required: false
        schema:
          type: string
      - name: offerType
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_OfferType'
      - name: merchantId
        in: query
        description: Merchant ID in Kard's system
        required: false
        schema:
          type: string
      - name: isTargeted
        in: query
        description: True returns targeted offers, false returns targeted and non-targeted offers
        required: false
        schema:
          type: boolean
      - name: startDateStart
        in: query
        description: Time in string format for offer startDate search (UTC)
        required: false
        schema:
          type: string
          format: date-time
      - name: startDateEnd
        in: query
        description: Time in string format for offer startDate search (UTC)
        required: false
        schema:
          type: string
          format: date-time
      - name: expirationDateStart
        in: query
        description: Time in string format for offer expirationDate search (UTC)
        required: false
        schema:
          type: string
          format: date-time
      - name: expirationDateEnd
        in: query
        description: Time in string format for offer expirationDate search (UTC)
        required: false
        schema:
          type: string
          format: date-time
      - name: startDateSort
        in: query
        description: Sort offer start dates chronologically (1 for ascending, -1 for descending)
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_SortOptions'
      - name: expirationDateSort
        in: query
        description: Sort offer expiration dates chronologically (1 for ascending, -1 for descending)
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_SortOptions'
      - name: merchantNameSort
        in: query
        description: Sort merchant names (1 for A-Z, -1 for Z-A)
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_SortOptions'
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/type_rewards_Offer'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_InvalidRequestUnion'
        '401':
          description: Error response with status 401
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_UnauthorizedErrorBody'
        '500':
          description: Error response with status 500
          content:
            application/json:
              schema:
                type: string
  /rewards/merchant/locations/user/{referringPartnerUserId}:
    get:
      operationId: get-locations-by-user
      summary: Get Eligible Locations
      description: 'Retrieve national and local geographic locations data that a specified user has eligible in-store offers at. To include local merchant locations, include the `includeLocal` query parameter. Call this endpoint to build out your [targeted offers](https://github.com/kard-financial/kard-postman?tab=readme-ov-file#b-targeted-offers) and [map-specific UX experiences](https://github.com/kard-financial/kard-postman#c-discover-clos-near-you-map-view). Please note that Longitude and Latitude fields are prioritized over State, City and Zipcode.<br/>

        <b>Required scopes:</b> `rewards:read`'
      tags:
      - rewards
      parameters:
      - name: referringPartnerUserId
        in: path
        description: Referring partner user ID from issuer that specifies user
        required: true
        schema:
          type: string
      - name: page
        in: query
        description: Page number [>= 0], (default = 0)
        required: false
        schema:
          type: integer
      - name: limit
        in: query
        description: Maximum number of locations to be returned [1 - 200], (default = 200)
        required: false
        schema:
          type: integer
      - name: locationNameSort
        in: query
        description: Sort location names (1 for A-Z, -1 for Z-A)
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_SortOptions'
      - name: citySort
        in: query
        description: Sort city names (1 for A-Z, -1 for Z-A)
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_SortOptions'
      - name: stateSort
        in: query
        description: Sort state names (1 for A-Z, -1 for Z-A)
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_SortOptions'
      - name: locationName
        in: query
        description: Name of location
        required: false
        schema:
          type: string
      - name: city
        in: query
        description: City of location; <b>REQUIRES</b> state query parameter
        required: false
        schema:
          type: string
      - name: zipCode
        in: query
        description: Zip Code of location; <b>CANNOT</b> provide State, City, Longitude, Latitude, or Radius query params when using zipCode
        required: false
        schema:
          type: string
      - name: state
        in: query
        description: State of location; <b>REQUIRES</b> city field
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_State'
      - name: googleId
        in: query
        description: GoogleId from location
        required: false
        schema:
          type: string
      - name: source
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_Source'
      - name: category
        in: query
        description: Category of merchant associated with location. Please use URL Encode for non single word categories. (Food & Beverage should be Food%20%26%20Beverage)
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_CategoryOption'
      - name: longitude
        in: query
        description: Longitude to search locations from [-180 - 180], <b>REQUIRES</b> latitude field
        required: false
        schema:
          type: number
          format: double
      - name: latitude
        in: query
        description: Latitude to search locations from [-90 - 90], <b>REQUIRES</b> longitude field
        required: false
        schema:
          type: number
          format: double
      - name: radius
        in: query
        description: Radius to search for locations in miles [1 - 50], (default = 10). <b>REQUIRES</b> longitude & latitude fields
        required: false
        schema:
          type: integer
      - name: includeLocal
        in: query
        description: When included, the response will include local merchant locations alongside national merchant locations. If omitted, the response will only contain national merchant locations.
        required: false
        schema:
          type: boolean
      - name: createdDateStart
        in: query
        description: Time in string format for location createdDate search start (UTC)
        required: false
        schema:
          type: string
          format: date-time
      - name: createdDateEnd
        in: query
        description: Time in string format for location createdDate search end (UTC)
        required: false
        schema:
          type: string
          format: date-time
      - name: supportedComponents
        in: query
        description: UI component types to include in included offers.
        required: false
        schema:
          $ref: '#/components/schemas/type_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:
                type: array
                items:
                  $ref: '#/components/schemas/type_rewards_LocationWithFullOffer'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_InvalidRequestUnion'
        '401':
          description: Error response with status 401
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_UnauthorizedErrorBody'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Error response with status 500
          content:
            application/json:
              schema:
                type: string
  /rewards/merchant/location/{id}:
    get:
      operationId: get-location-by-id
      summary: Get Location by ID
      description: 'Retrieve location data for a specific Kard location ID.<br/>

        <b>Required scopes:</b> `rewards:read`'
      tags:
      - rewards
      parameters:
      - name: id
        in: path
        description: The Kard location ID to query
        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_rewards_Location'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_InvalidRequestUnion'
        '401':
          description: Error response with status 401
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_UnauthorizedErrorBody'
        '404':
          description: Error response with status 404
          content:
            application/json:
              schema:
                type: string
        '500':
          description: Error response with status 500
          content:
            application/json:
              schema:
                type: string
  /rewards/merchant/locations/{merchantId}:
    get:
      operationId: get-locations-by-merchant-id
      summary: Get Locations by Merchant ID
      description: 'Retrieve all locations associated to a specific Kard merchant ID.<br/>

        <b>Required scopes:</b> `rewards:read`'
      tags:
      - rewards
      parameters:
      - name: merchantId
        in: path
        description: The Kard merchant ID to query
        required: true
        schema:
          type: string
      - name: page
        in: query
        description: Page number [>= 0], (default = 0)
        required: false
        schema:
          type: integer
      - name: limit
        in: query
        description: Maximum number of locations [1 - 200], (default = 200)
        required: false
        schema:
          type: integer
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/type_rewards_Location'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_InvalidRequestUnion'
        '401':
          description: Error response with status 401
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_UnauthorizedErrorBody'
        '500':
          description: Error response with status 500
          content:
            application/json:
              schema:
                type: string
  /rewards/merchant/locations:
    get:
      operationId: get-locations
      summary: Get Locations
      description: 'Retrieve ALL national and local geographic locations data regardless of whether a user is eligible to see them. This endpoint is a legacy endpoint and will no longer be maintained soon. Instead, use [Get Eligible Locations](/legacy/api/rewards/locations/get-locations-by-user) to build your [map-specific UX experiences](https://github.com/kard-financial/kard-postman#c-discover-clos-near-you-map-view).<br/>

        <b>Required scopes:</b> `rewards:read`'
      tags:
      - rewards
      parameters:
      - name: page
        in: query
        description: Page number [>= 0], (default = 0)
        required: false
        schema:
          type: integer
      - name: limit
        in: query
        description: Maximum number of locations [1 - 200], (default = 200)
        required: false
        schema:
          type: integer
      - name: googleId
        in: query
        description: GoogleId from location
        required: false
        schema:
          type: string
      - name: city
        in: query
        description: City of location; <b>REQUIRES</b> state query parameter
        required: false
        schema:
          type: string
      - name: zipCode
        in: query
        description: Zip Code of location; <b>CANNOT</b> provide State, City, Longitude, Latitude, or Radius query params when using zipCode
        required: false
        schema:
          type: string
      - name: state
        in: query
        description: State of location; <b>REQUIRES</b> city field
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_State'
      - name: locationNameSort
        in: query
        description: Sort location names (1 for A-Z, -1 for Z-A)
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_SortOptions'
      - name: citySort
        in: query
        description: Sort city names (1 for A-Z, -1 for Z-A)
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_SortOptions'
      - name: stateSort
        in: query
        description: Sort state names (1 for A-Z, -1 for Z-A)
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_SortOptions'
      - name: longitude
        in: query
        description: Longitude to search locations from [-180 - 180], <b>REQUIRES</b> latitude field
        required: false
        schema:
          type: integer
      - name: latitude
        in: query
        description: Latitude to search locations from [-90 - 90], <b>REQUIRES</b> longitude field
        required: false
        schema:
          type: integer
      - name: radius
        in: query
        description: Radius to search for locations in miles [1 - 50], (default = 10). <b>REQUIRES</b> longitude & latitude fields
        required: false
        schema:
          type: integer
      - name: source
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_Source'
      - name: category
        in: query
        description: Category of merchant associated with location. Please use URL Encode for non single word categories. (Food & Beverage should be Food%20%26%20Beverage)
        required: false
        schema:
          $ref: '#/components/schemas/type_commons_CategoryOption'
      - name: locationName
        in: query
        description: Name of location
        required: false
        schema:
          type: string
      - name: createdDateStart
        in: query
        description: Time in string format for location createdDate search start (UTC)
        required: false
        schema:
          type: string
          format: date-time
      - name: createdDateEnd
        in: query
        description: Time in string format for location createdDate search start (UTC)
        required: false
        schema:
          type: string
          format: date-time
      - name: Authorization
        in: header
        description: Bearer authentication
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Response with status 200
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/type_rewards_LocationWithPartialOffer'
        '400':
          description: Error response with status 400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_InvalidRequestUnion'
        '401':
          description: Error response with status 401
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/type_commons_UnauthorizedErrorBody'
        '500':
          description: Error response with status 500
          content:
            application/json:
              schema:
                type: string
components:
  schemas:
    type_rewards_Merchant:
      type: object
      properties:
        _id:
          $ref: '#/components/schemas/type_commons_MongoId'
          description: Merchant ID in Kard's system
        name:
          type: string
          description: Merchant name
        description:
          type: string
          description: Merchant description - usually a blurb outlining more details about the merchant
        websiteURL:
          type: string
          description: Merchant's URL website
        category:
          $ref: '#/components/schemas/type_commons_CategoryOption'
          description: Category of merchant
        acceptedCards:
          type: array
          items:
            $ref: '#/components/schemas/type_commons_AcceptedCards'
        source:
          $ref: '#/components/schemas/type_commons_Source'
          description: Merchant source
        createdDate:
          type: string
          format: date-time
          description: Created date of merchant in Kard's system (UTC)
        lastModified:
          type: string
          format: date-time
          description: Last modified date of merchant in Kard's system (UTC)
        offers:
          type: array
          items:
            $ref: '#/components/schemas/type_rewards_MerchantOffer'
          description: Offers associated to the merchant
        imgUrl:
          type: string
          description: Merchant image asset URL
        bannerImgUrl:
          type: string
          description: Merchant banner image asset URL
      required:
      - _id
      - name
      - description
      - websiteURL
      - category
      - acceptedCards
      - source
      - createdDate
      - lastModified
      - offers
      - imgUrl
      title: Merchant
    type_rewards_LocationsOffer:
      type: object
      properties:
        _id:
          $ref: '#/co

# --- truncated at 32 KB (67 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kard/refs/heads/main/openapi/kard-rewards-api-openapi.yml