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. Local merchants and offers details can be found by calling the Get Eligible Locations endpoint with the `includeLocal` query parameter.


        Required scopes: `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.


        Required scopes: `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 to retrieve national merchant data and build your targeted offers UX experience. Local merchants and offers details can be found by calling the Get Eligible Locations endpoint with the `includeLocal` query parameter.


        Required scopes: `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. Local merchants and offers details can be found by calling the Get Eligible Locations endpoint with the `includeLocal` query parameter.


        Required scopes: `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 to retrieve national merchant data and build your targeted offers UX experience. Local merchants and offers details can be found by calling the Get Eligible Locations endpoint with the `includeLocal` query parameter.


        Required scopes: `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 and map-specific UX experiences. Please note that Longitude and Latitude fields are prioritized over State, City and Zipcode.


        Required scopes: `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.


        Required scopes: `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.


        Required scopes: `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 to build your map-specific UX experiences.


        Required scopes: `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_OfferMerchant:
      type: object
      properties:
        _id:
          $ref: '#/components/schemas/type_commons_MongoId'
          description: Merchant ID in Kard's system
        name:
          type: string
          description: Name of merchant
        description:
          type: string
          description: Description of merchant
        type:
          $ref: '#/components/schemas/type_commons_EnrolledRewardsType'
          description: Type of merchant
        websiteURL:
          type: string
          description: Website URL of merchant
        category:
          $ref: '#/components/schemas/type_commons_CategoryOption'
          description: Category of merchant
        acceptedCards:
          type: array
          items:
            $ref: '#/components/schemas/type_commons_AcceptedCards'
        imgUrl:
          type: string
          description: Merchant image asset URL
        bannerImgUrl:
          type: string
          description: Merchant banner image asset URL
      required:
      - _id
      - name
      - description
      - type
      - websiteURL
      - category
      - acceptedCards
      - imgUrl
      description: Merchant associated with the offer
      title: OfferMerchant
    type_commons_GeoLocation:
      type: object
      properties:
        longitude:
          type: number
          format: double
          description: Longitude of location
        latitude:
          type: number
          format: double
          description: Latitude of location
      required:
      - longitude
      - latitude
      title: GeoLocation
    type_rewards_LocationsMerchant:
      type: object
      properties:
        _id:
          $ref: '#/components/schemas/type_commons_MongoId'
          description: Merchant ID in Kard's system
        name:
          type: string
          description: Name of merchant
        description:
          type: string
          description: Description of merchant
        websiteURL:
          type: string
          description: Website URL associated with merchant
        type:
          $ref: '#/components/schemas/type_commons_EnrolledRewardsType'
          description: Merchant type
        category:
          $ref: '#/components/schemas/type_commons_CategoryOption'
          description: Category of merchant
        acceptedCards:
          type: array
          items:
            $ref: '#/components/schemas/type_commons_AcceptedCards'
        imgUrl:
          type: string
          description: Merchant image asset URL
        bannerImgUrl:
          type: string
          description: Merchant banner image asset URL
      required:
      - _id
      - name
      - description
      - websiteURL
      - type
      - category
      - acceptedCards
      - imgUrl
      title: LocationsMerchant
    type_commons_State:
      type: string
      enum:
      - AL
      - AK
      - AS
      - AZ
      - AR
  

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