> This page is for version Legacy. > For other versions, use one of these documentation indexes: > - 2024-10-01 (default): https://docs.getkard.com/2024-10-01/llms.txt > - Legacy: https://docs.getkard.com/legacy/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.getkard.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getkard.com/_mcp/server. # Get Eligible Locations GET https://rewards-api.getkard.com/rewards/merchant/locations/user/{referringPartnerUserId} 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. 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. Required scopes: `rewards:read` Reference: https://docs.getkard.com/legacy/api/rewards/locations/get-locations-by-user ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Servers - `https://rewards-api.getkard.com` (Production, default) - `https://test-rewards-api.getkard.com` (Sandbox) ## Request ### Path parameters - `referringPartnerUserId` (string, required) — Referring partner user ID from issuer that specifies user ### Query parameters - `page` (integer, optional) — Page number [>= 0], (default = 0) - `limit` (integer, optional) — Maximum number of locations to be returned [1 - 200], (default = 200) - `locationNameSort` (enum, optional) — Sort location names (1 for A-Z, -1 for Z-A) - Allowed values: `1`, `-1` - `citySort` (enum, optional) — Sort city names (1 for A-Z, -1 for Z-A) - Allowed values: `1`, `-1` - `stateSort` (enum, optional) — Sort state names (1 for A-Z, -1 for Z-A) - Allowed values: `1`, `-1` - `locationName` (string, optional) — Name of location - `city` (string, optional) — City of location; REQUIRES state query parameter - `zipCode` (string, optional) — Zip Code of location; CANNOT provide State, City, Longitude, Latitude, or Radius query params when using zipCode - `state` (enum, optional) — State of location; REQUIRES city field - Allowed values: `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` - `googleId` (string, optional) — GoogleId from location - `source` (enum, optional) — Source of the merchant associated to the location - Allowed values: `NATIONAL`, `LOCAL` - `category` (enum, optional) — Category of merchant associated with location. Please use URL Encode for non single word categories. (Food & Beverage should be Food%20%26%20Beverage) - Allowed values: `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` - `longitude` (double, optional) — Longitude to search locations from \[-180 - 180], REQUIRES latitude field - `latitude` (double, optional) — Latitude to search locations from \[-90 - 90], REQUIRES longitude field - `radius` (integer, optional) — Radius to search for locations in miles \[1 - 50], (default = 10). REQUIRES longitude & latitude fields - `includeLocal` (boolean, optional) — When included, the response will include local merchant locations alongside national merchant locations. If omitted, the response will only contain national merchant locations. - `createdDateStart` (datetime, optional) — Time in string format for location createdDate search start (UTC) - `createdDateEnd` (datetime, optional) — Time in string format for location createdDate search end (UTC) - `supportedComponents` (enum, optional) — UI component types to include in included offers. - Allowed values: `shortDescription`, `longDescription`, `baseReward`, `boostedReward`, `cta`, `tags`, `detailTags`, `logoFlare`, `progressBar` ## Response ### 200 - `list of LocationWithFullOffer` ## Errors ### 500 Internal Server Error - `string` ### 400 Invalid Request - `InvalidRequestUnion` ### 404 Does Not Exist Error - `string` ### 401 Unauthorized Error - `message` (string, required) ## Types ### LocationWithFullOffer - `_id` (string, required) — Location ID in Kard's system - `address` (Address, required) — Address of location - `category` (enum, required) — Category of merchant associated with location - Allowed values: `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` - `createdDate` (datetime, required) — Created date of location in Kard's system (UTC) - `geoLocation` (GeoLocation, required) — Geo-coordinates of location - `lastModified` (datetime, required) — Last modified date of location in Kard's system (UTC) - `locationType` (enum, required) — Type of offer associated to location, will always be in INSTORE - Allowed values: `INSTORE` - `merchant` (LocationsMerchantWithAttribution, required) — Merchant object associated with location - `merchantId` (string, required) — Merchant ID in Kard's system associated to location - `name` (string, required) — Name of the location - `offers` (list of FullLocationsOffer, required) — Offers associated to the location - `phone` (string, required) — Phone number for location - `source` (enum, required) — Source of the merchant associated to the location - Allowed values: `NATIONAL`, `LOCAL` - `googleId` (string, optional) — GoogleId of location - `operationHours` (OperatingHours, optional) — Hours of operation for location ### RequestValidationErrorResponse - `errors` (list of string, required) ### Address - `street` (string, required) - `city` (string, required) - `state` (enum, required) - Allowed values: `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` - `zipCode` (string, required) ### GeoLocation - `longitude` (double, required) — Longitude of location - `latitude` (double, required) — Latitude of location ### LocationsMerchantWithAttribution - `_id` (string, required) — Merchant ID in Kard's system - `acceptedCards` (list of enum, required) - Allowed values: `VISA`, `MASTERCARD`, `AMERICAN EXPRESS`, `DISCOVER` - `category` (enum, required) — Category of merchant - Allowed values: `Arts & Entertainment`, `Baby, Kids & Toys`, `Books & Digital Media`, `Clothing, Shoes & Accessories`, `Computers, Electronics & Software`, `Convenience`, `Gas`, `Department Stores`, `Food & Beverage`, `Health & Beauty`, `Home & Garden`, `Miscellaneous`, `Occasions & Gifts`, `Pets`, `Sports & Outdoors`, `Supplies & Services`, `Travel` - `description` (string, required) — Description of merchant - `name` (string, required) — Name of merchant - `type` (enum, required) — Merchant type - Allowed values: `CARDLINKED`, `AFFILIATE` - `websiteURL` (string, required) — Website URL associated with merchant - `imgUrl` (string, required, deprecated) — \[Deprecated — Please use imgUrl on the offer object which contain attribution tokens] - `bannerImgUrl` (string, optional, deprecated) — \[Deprecated — Please use bannerImgUrl on the offer object which contain attribution tokens] ### FullLocationsOffer - `_id` (string, required) — Offer Id in Kard's system - `commissionType` (enum, required) — Type of commission on offer (% or a flat $) - Allowed values: `FLAT`, `PERCENT` - `createdDate` (datetime, required) — Create date of offer (UTC) - `expirationDate` (datetime, required) — Expiration date of offer if applicable (UTC) - `isLocationSpecific` (boolean, required) — Is offer location specific - `isTargeted` (boolean, required) — True returns targeted offers, false returns targeted and non-targeted offers - `lastModified` (datetime, required) — Last modified date of offer (UTC) - `name` (string, required) — Name of offer - `offerType` (enum, required) — Type of offer (whether it is run online or in-store) - Allowed values: `INSTORE`, `ONLINE` - `redeemableOnce` (boolean, required) — Is the offer redeemable once - `source` (enum, required) — Source of merchant associated to the offer - Allowed values: `NATIONAL`, `LOCAL` - `startDate` (datetime, required) — Beginning date of offer (UTC) - `terms` (string, required) — Terms and conditions on offer - `totalCommission` (double, required) — Commission going to issuer and cardholder - `bannerImgUrl` (string, optional) — Banner image URL asset containing attribution tokens - `category` (enum, optional) — Category of merchant associated with offer - Allowed values: `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` - `imgUrl` (string, optional) — Image URL asset containing attribution tokens - `issuersCommission` (double, optional) — Commission going to the issuer - `maxRewardAmount` (integer, optional) — Max Reward Amount for Offer, if available - `maxTransactionAmount` (integer, optional) — Max Transaction Amount for Offer, if available - `minRewardAmount` (integer, optional) — Min Reward Amount for Offer, if available - `minTransactionAmount` (integer, optional) — Min Transaction Amount for Offer, if available - `usersCommission` (double, optional) — Commission going to user ### OperatingHours - `SUNDAY` (string, optional) - `MONDAY` (string, optional) - `TUESDAY` (string, optional) - `WEDNESDAY` (string, optional) - `THURSDAY` (string, optional) - `FRIDAY` (string, optional) - `SATURDAY` (string, optional) ## Examples **Response** ```json [ { "_id": "5e27318c9b346f00087fba8l", "address": { "street": "120 Main St", "city": "Philadelphia", "state": "PA", "zipCode": "19147" }, "category": "Food & Beverage", "createdDate": "2021-10-05T21:47:11.994Z", "geoLocation": { "longitude": -75.1446869, "latitude": 39.9419429 }, "lastModified": "2024-05-10T01:38:11.542Z", "locationType": "INSTORE", "merchant": { "_id": "615cc7df498bed0009bbf3bf", "acceptedCards": [ "AMERICAN EXPRESS", "MASTERCARD", "VISA" ], "category": "Food & Beverage", "description": "Description of the merchant", "name": "Some Merchant", "type": "CARDLINKED", "websiteURL": "http://somemerchant.com", "imgUrl": "https://images.somemerchant.com", "bannerImgUrl": "https://banner.somemerchant.com" }, "merchantId": "615cc7df498bed0009bbf3bf", "name": "Some Location", "offers": [ { "_id": "5e27318c9b346f00087fbb5c", "commissionType": "PERCENT", "createdDate": "2022-01-01T05:00:00Z", "expirationDate": "2022-01-01T05:00:00Z", "isLocationSpecific": false, "isTargeted": true, "lastModified": "2022-01-01T05:00:00Z", "name": "Some offer", "offerType": "INSTORE", "redeemableOnce": true, "source": "NATIONAL", "startDate": "2022-01-01T05:00:00Z", "terms": "some terms", "totalCommission": 4.3, "bannerImgUrl": "www.banner.com", "category": "Food & Beverage", "imgUrl": "www.image.com", "issuersCommission": 1.8, "maxRewardAmount": 20, "maxTransactionAmount": 20, "minRewardAmount": 5, "minTransactionAmount": 5, "usersCommission": 2.5 } ], "phone": "(123) 555-8880", "source": "LOCAL", "googleId": "ChIJUwU6IZrIxokRgX-V0_Y0eXx", "operationHours": { "SUNDAY": "4:00PM - 10:00PM", "MONDAY": "4:30PM - 10:00PM", "TUESDAY": "4:30PM - 10:00PM", "WEDNESDAY": "4:30PM - 10:00PM", "THURSDAY": "4:30PM - 10:00PM", "FRIDAY": "4:30PM - 11:00PM", "SATURDAY": "4:30PM - 11:00PM" } } ] ``` **SDK Code** ```python import requests url = "https://rewards-api.getkard.com/rewards/merchant/locations/user/%7BreferringPartnerUserId%7D" querystring = {"limit":"1","page":"0"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://rewards-api.getkard.com/rewards/merchant/locations/user/%7BreferringPartnerUserId%7D?limit=1&page=0'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://rewards-api.getkard.com/rewards/merchant/locations/user/%7BreferringPartnerUserId%7D?limit=1&page=0" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://rewards-api.getkard.com/rewards/merchant/locations/user/%7BreferringPartnerUserId%7D?limit=1&page=0") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://rewards-api.getkard.com/rewards/merchant/locations/user/%7BreferringPartnerUserId%7D?limit=1&page=0") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://rewards-api.getkard.com/rewards/merchant/locations/user/%7BreferringPartnerUserId%7D?limit=1&page=0', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://rewards-api.getkard.com/rewards/merchant/locations/user/%7BreferringPartnerUserId%7D?limit=1&page=0"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://rewards-api.getkard.com/rewards/merchant/locations/user/%7BreferringPartnerUserId%7D?limit=1&page=0")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```