rewards

Get Eligible Locations

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. When none of the locationNameSort, citySort and stateSort query parameters are provided, locations are returned newest first (descending createdDate); if latitude and longitude are provided, locations are ordered by ascending distance from that point first, then newest first.<br/> <b>Required scopes:</b> rewards:read

get/rewards/merchant/locations/user/{referringPartnerUserId}

Request

  • Base URL: https://rewards-api.getkard.com
  • URL: https://rewards-api.getkard.com/rewards/merchant/locations/user/{referringPartnerUserId}
  • Auth: HTTP bearer

Path parameters

referringPartnerUserIdstring required

Referring partner user ID from issuer that specifies user

Query parameters

pageinteger

Page number [>= 0], (default = 0)

limitinteger

Maximum number of locations to be returned [1 - 200], (default = 200)

locationNameSort'1' | '-1'

Sort location names (1 for A-Z, -1 for Z-A)

citySort'1' | '-1'

Sort city names (1 for A-Z, -1 for Z-A)

stateSort'1' | '-1'

Sort state names (1 for A-Z, -1 for Z-A)

locationNamestring

Name of location

citystring

City of location; <b>REQUIRES</b> state query parameter

zipCodestring

Zip Code of location; <b>CANNOT</b> provide State, City, Longitude, Latitude, or Radius query params when using zipCode

state'AL' | 'AK' | 'AS' | 'AZ' | 'AR' | 'CA' | 'CO' | 'CT' | 'DE' | 'DC' | 'FM' | 'FL' | 'GA' | 'GU' | 'HI' | 'ID' | 'IL' | 'IN' | 'IA' | 'KS' | 'KY' | 'LA' | 'ME' | 'MH' | 'MD' | 'MA' | 'MI' | 'MN' | 'MS' | 'MO' | 'MT' | 'NE' | 'NV' | 'NH' | 'NJ' | 'NM' | 'NY' | 'NC' | 'ND' | 'MP' | 'OH' | 'OK' | 'OR' | 'PW' | 'PA' | 'PR' | 'RI' | 'SC' | 'SD' | 'TN' | 'TX' | 'UT' | 'VT' | 'VI' | 'VA' | 'WA' | 'WV' | 'WI' | 'WY'

State of location; <b>REQUIRES</b> city field

googleIdstring

GoogleId from location

source'NATIONAL' | 'LOCAL'

Source of the merchant associated to the location

category'Arts & Entertainment' | 'Baby, Kids & Toys' | 'Books & Digital Media' | 'Clothing, Shoes & Accessories' | 'Computers, Electronics & Software' | 'Convenience' | 'Gas' | 'Department Stores' | 'Food & Beverage' | 'Health & Beauty' | 'Home & Garden' | 'Miscellaneous' | 'Occasions & Gifts' | 'Pets' | 'Sports & Outdoors' | 'Supplies & Services' | 'Travel'

Category of merchant. Please use URL Encode for non single word categories. (Food & Beverage should be Food%20%26%20Beverage)

Category of merchant associated with location. Please use URL Encode for non single word categories. (Food & Beverage should be Food%20%26%20Beverage)

longitudenumber double

Longitude to search locations from [-180 - 180], <b>REQUIRES</b> latitude field

latitudenumber double

Latitude to search locations from [-90 - 90], <b>REQUIRES</b> longitude field

radiusinteger

Radius to search for locations in miles [1 - 50], (default = 10). <b>REQUIRES</b> longitude & latitude fields

includeLocalboolean

When included, the response will include local merchant locations alongside national merchant locations. If omitted, the response will only contain national merchant locations.

createdDateStartstring date-time

Time in string format for location createdDate search start (UTC)

createdDateEndstring date-time

Time in string format for location createdDate search end (UTC)

supportedComponents'shortDescription' | 'longDescription' | 'baseReward' | 'boostedReward' | 'cta' | 'tags' | 'detailTags' | 'logoFlare' | 'progressBar'

Available UI component types for offers

UI component types to include in included offers.

Response

Response with status 200

_idstring required

The unique identifier for a document in the database

merchantIdstring required

Merchant ID in Kard's system associated to location

namestring required

Name of the location

locationType'INSTORE' required
phonestring required

Phone number for location

googleIdstring

GoogleId of location

createdDatestring date-time required

Created date of location in Kard's system (UTC)

lastModifiedstring date-time required

Last modified date of location in Kard's system (UTC)

source'NATIONAL' | 'LOCAL' required

Source of the merchant associated to the location

category'Arts & Entertainment' | 'Baby, Kids & Toys' | 'Books & Digital Media' | 'Clothing, Shoes & Accessories' | 'Computers, Electronics & Software' | 'Convenience' | 'Gas' | 'Department Stores' | 'Food & Beverage' | 'Health & Beauty' | 'Home & Garden' | 'Miscellaneous' | 'Occasions & Gifts' | 'Pets' | 'Sports & Outdoors' | 'Supplies & Services' | 'Travel' required

Category of merchant. Please use URL Encode for non single word categories. (Food & Beverage should be Food%20%26%20Beverage)

Changes

No recorded changes to this operation across all 1 revision of this API.