Accessing the Card Catalog
Introduction
The Hawk Marketplace Rewards Catalog Processing API allows you to access the catalog of card products that have been made available for you to order.
The card catalog is specifically configured to your sub-organization and client programs in the Hawk Marketplace platform. It is not a global catalog of all products available from Blackhawk Network. If you do not see a product you believe should be available for you to order, or you would like to add a new product to your catalog, reach out to your Account Manager.
Using the Catalog API
We recommend syncing with the catalog API once a day to pull the most current information about the products available to you. This will ensure you always have the latest card images, terms and conditions and available product denominations to order.
The image below shows a sample use case where pulling products via the Catalog API would be useful.
Diagram showing a sample Hawk Marketplace API Integration
The catalog API can be called by Client Program or by Sub Organization ID.
Calling the Catalog API by Client Program
To call the Catalog API by Client Program we will be using /clientProgram/byKey
.
Method | Service | API | Type |
---|---|---|---|
GET | rewardsCatalogProcessing | clientProgram/byKey â Explore | Synchronous |
URI: https://apipp.blackhawknetwork.com/rewardsCatalogProcessing/v1/clientProgram/byKey
From our application, when calling /clientProgram/byKey
, we need to send the following parameters in the HTTP header.
Parameter | Description | Type | Required |
---|---|---|---|
merchantId | The Merchant ID (MID) is a string identifier, provided to you by your account manager. | String | Yes |
requestId | A globally unique string identifier specified by the application making the request. | String | Yes |
accept | This should be set to the following string to ensure all characters are correctly encoded in the response:Accept: application/json; charset=utf-8 | String | No |
In our example we will be sending the following values in the header:
Content-Type: application/json
Accept: application/json; charset=utf-8
merchantId:1234
requestId:2019-08-16T16:41:00-0600
We will also need to send the clientProgramId in the URL as follows:
https://apipp.blackhawknetwork.com/rewardsCatalogProcessing/v1/clientProgram/byKey?clientProgramId=43586508
The following HTTP status codes may be returned in the response header:
HTTP Status Code | Meaning | Notes |
---|---|---|
200 | Operation Complete | The query returned successfully. |
4XX | Invalid Request | Check the JSON error response provided. In most cases you will find the request had missing information or was formatted improperly. |
5XX | System Error | Blackhawk Network encountered an internal error trying to process your order. Reach out to your Account Manager for more information. |
Assuming the query was successful a JSON object will be returned in the response containing the following information.
ClientProgram
Name | Description | Type | Possible Values |
---|---|---|---|
clientProgramID | The queried Program ID. Also known as Quote ID. | Integer | |
programName | The descriptive name of the program | String | |
programType | This indicates if the program is physical or digital. | String | PHYSICAL, DIGITAL |
currency | The product currency. | String | Example: USD, CAD |
products | List of available products | Object |
Products
The products object contains the following information about each product:
Name | Description | Type |
---|---|---|
contentProviderCode | Content provider code | String |
productName | Product Name | String |
productDescription | Product Description | String |
parentBrandName | Parent Brand Name | String |
redemptionInfo | Redemption Information | String |
termsAndConditions | The terms and conditions for the product | Object |
productImage | URL to the image for the product. This is usually a representative card image that can be presented to the customer. | String |
logoImage | URL to the logo image for the merchant. This is only available for some kind of products for some merchants. | String |
valueRestrictions | Indicates what values/denominations the product can be ordered in. Orders that do not fit this criteria will be rejected. | Object |
offFaceDiscountPercent | If there is a face discount the percentage will be provided here. | Number |
expirationDescription | A textual value that can be used to describe the expiration terms to the customer. For example: "3 months". | String |
expiration | More detailed information about the expiration for this product. | Object |
cardholderFees | Details of all the fees that will be applied to the cardholder. | Object Array |
isSweep | Indicates if this is a sweep product. | boolean |
Terms and Conditions
Name | Description | Type |
---|---|---|
type | This indicates if the terms and conditions are included directly as a string or if a link has been provided. Possible values are: INLINE,LINK | String |
url | The URL to the terms and conditions. | String |
text | The text of the terms and conditions. | String |
Value Restrictions
Name | Description | Type |
---|---|---|
minimum | Minimum value for the denomination that can be ordered. | Number |
maximum | Maximum value for the denomination that can be ordered. | Number |
exclusivelyAllowedValues | List of exclusively available values. | Array of numbers |
Expiration
Name | Description | Type |
---|---|---|
type | Type of expiration applicable to the product. Possible values are: ROLLING,STATIC | String |
numberofMonths | Expiry time in number of months. | Integer |
date | Specific date of expiration. | String (date-time) |
Cardholder Fees
Note this is an array of objects. One object will be returned for each fee.
Name | Description | Type |
---|---|---|
calculationType | The type of calculation use for the fee. Possible values are: AMOUNT,PERCENT | String |
name | Fee name. For example: "Conversion Currency Fee". | String |
amount | Fee amount. | Number |
percent | Fee percentage | Number |
Shown below are some different examples of information returned for different kinds of products:
{
"clientProgramId": 43308603,
"programName": "Virtual Prepaid Account",
"programType": "DIGITAL",
"currency": "USD",
"products": [
{
"productImage": "https://d30xemkaawaj37.cloudfront.net/resized/default-virtual-disc-385x245.png",
"valueRestrictions":
{
"minimum": 0,
"maximum": 1000
},
"expirationDescription": "3 months",
"expiration":
{
"type": "ROLLING",
"numberOfMonths": 3
},
"cardholderFees":
[{
"calculationType": "PERCENT",
"name": "Conversion Currency Fee",
"percent": 2
},
{
"calculationType": "AMOUNT",
"name": "Cardholder Replacement Fee",
"amount": 15
},
{
"calculationType": "AMOUNT",
"name": "Virtual Conversion Cardholder Fee",
"amount": 3
},
{
"calculationType": "AMOUNT",
"name": "Expedited Delivery Fee",
"amount": 20
}]
}]
}
{
"clientProgramId": 13066099,
"programName": "Park and Company US Egift",
"programType": "DIGITAL",
"currency": "USD",
"products": [
{
"contentProviderCode": "GapOptions_eGift",
"productName": "Athleta ",
"productDescription": "You can get a pair of jeans at Gap, a cashmere sweater at Banana Republic, a graphic tee at Old Navy, and a swimsuit at Athleta, all with just one card! Options gift cards can be redeemed at Gap, Old Navy, Banana Republic and Athleta stores across the US, Canada and Puerto Rico, including Outlet and Factory Stores, and online at gap.com, oldnavy.com, bananarepublic.com, and athleta.com.",
"parentBrandName": "Athleta ",
"termsAndConditions": {
"type": "INLINE",
"text": "This order will be fulfilled with the Options eGiftCard. This eGiftCard is issued by and represents an obligation of Direct Consumer Services (âDCSâ). The eGiftCard may be redeemed for merchandise at any Gap brand, Old Navy, Banana Republic, or Athleta location, including Outlet and Factory stores. The eGiftCard may also be redeemed online for merchandise at gap.com, oldnavy.com, bananarepublic.com, or athleta.com. If you return merchandise originally purchased with an eGiftCard, any refund will be issued in the form of a plastic gift card issued by DCS which may be used at any of these stores or websites. Any merchandise purchased with an eGiftCard is subject to the applicable store or online return policies. Purchases will be deducted from the amount of this eGiftCard until the value reaches zero. This eGiftCard may not be used or redeemed with certain promotional offers and may not be applied as payment on any account. You may not use an eGiftCard to purchase other eGiftCards. Additional value may be added to this eGiftCard at any Gap, Old Navy or Banana Republic store. Redeemable for cash when the balance is less than $5 or as otherwise required by law. Restricted to use in the USA, Puerto Rico and Canada. By purchasing this eGiftCard, you agree that the laws of the State of California, without regard to principles of conflict of laws, will govern this Agreement. Limit 5 eGiftCards redeemable per online transaction.\n\n"
},
"productImage": "http://dmyxigrg1v9vl.cloudfront.net/images/merchant-cards/gap-options.png",
"logoImage": "http://dmyxigrg1v9vl.cloudfront.net/images/merchant-logos/Athleta.png",
"valueRestrictions": {
"minimum": 10,
"maximum": 250
},
"locale": "EN"
},
{
"contentProviderCode": "GapOptions_eGift",
"productName": "Banana Republic ",
"productDescription": "You can get a pair of jeans at Gap, a cashmere sweater at Banana Republic, a graphic tee at Old Navy, and a swimsuit at Athleta, all with just one card! Options gift cards can be redeemed at Gap, Old Navy, Banana Republic and Athleta stores across the US, Canada and Puerto Rico, including Outlet and Factory Stores, and online at gap.com, oldnavy.com, bananarepublic.com, and athleta.com.",
"parentBrandName": "Banana Republic ",
"termsAndConditions": {
"type": "INLINE",
"text": "This order will be fulfilled with the Options eGiftCard. This eGiftCard is issued by and represents an obligation of Direct Consumer Services (âDCSâ). The eGiftCard may be redeemed for merchandise at any Gap brand, Old Navy, Banana Republic, or Athleta location, including Outlet and Factory stores. The eGiftCard may also be redeemed online for merchandise at gap.com, oldnavy.com, bananarepublic.com, or athleta.com. If you return merchandise originally purchased with an eGiftCard, any refund will be issued in the form of a plastic gift card issued by DCS which may be used at any of these stores or websites. Any merchandise purchased with an eGiftCard is subject to the applicable store or online return policies. Purchases will be deducted from the amount of this eGiftCard until the value reaches zero. This eGiftCard may not be used or redeemed with certain promotional offers and may not be applied as payment on any account. You may not use an eGiftCard to purchase other eGiftCards. Additional value may be added to this eGiftCard at any Gap, Old Navy or Banana Republic store. Redeemable for cash when the balance is less than $5 or as otherwise required by law. Restricted to use in the USA, Puerto Rico and Canada. By purchasing this eGiftCard, you agree that the laws of the State of California, without regard to principles of conflict of laws, will govern this Agreement. Limit 5 eGiftCards redeemable per online transaction.\n\n"
},
"productImage": "http://dmyxigrg1v9vl.cloudfront.net/images/merchant-cards/gap-options.png",
"logoImage": "http://dmyxigrg1v9vl.cloudfront.net/images/merchant-logos/BananaRepublic.png",
"valueRestrictions": {
"minimum": 10,
"maximum": 250
},
"locale": "EN"
}
]
}
{
"clientProgramId": 13066088,
"programName": "Park and Company Reloadable Visa",
"programType": "PHYSICAL",
"currency": "USD",
"products": [ {
"productImage": "https://d30rrwwq6cckt4.cloudfront.net/resized/53ef8db0-ae9e-40a4-9c25-00c945bb5b22-385x245.png",
"valueRestrictions": {
"minimum": 0,
"maximum": 0,
"exclusivelyAllowedValues": []
},
"expirationDescription": "2020-06-30",
"expiration": {
"type": "STATIC",
"date": "2020-06-30"
},
"cardholderFees": [
{
"calculationType": "AMOUNT",
"name": "Monthly Maintenance Fee",
"amount": 2.5
},
{
"calculationType": "AMOUNT",
"name": "Check Refund Fee",
"amount": 0
},
{
"calculationType": "AMOUNT",
"name": "Card Refund Fee",
"amount": 15
},
{
"calculationType": "PERCENT",
"name": "Conversion Currency Fee",
"percent": 2
},
{
"calculationType": "AMOUNT",
"name": "Expedited Delivery Fee",
"amount": 20
}
]
}]
}
{
"clientProgramId": 12345678,
"programName": "US Closed Loop-Bulk",
"programType": "PHYSICAL",
"currency": "USD",
"products": [{
"contentProviderCode": "TheHomeDepot",
"productName": "Home Depot Gift Card",
"productDescription": "The Home DepotÂŽ helps doers do more with their time and money. From free delivery on over one million online items to image and voice search in our award-winning app, The Home Depot gift card makes shopping for home improvement easier than ever. All from the worldâs largest home improvement retailer. Itâs a good time to be a doer.",
"parentBrandName": "Home DepotÂŽ",
"termsAndConditions": {
"type": "INLINE",
"text": "Gift Card is valid for the purchase of merchandise/services at any The Home DepotÂŽ store in the U.S., Canada and online at HomeDepot.com. Gift Card is not a credit/debit card and is not redeemable for cash or credit unless required by law. Gift Card cannot be applied to any credit or loan balance, Tool Rental Deposits, or for in-home purchases. To replace a lost or stolen Gift Card, visit your local store. Lost, stolen or damaged Gift Cards will not be replaced without proof of purchase. Replacement value is the value of the Gift Card at the time it is reported lost or stolen. Gift Cards purchased with cash will not be replaced unless required by law. Returns for purchases made with this Gift Card are subject to The Home Depotâs Returns Policy (details available at any The Home Depot store) and eligible refunds will be issued in store credit. Gift Card may be deactivated or rejected if fraud is suspected in the issuerâs sole discretion. Check your balance at any The Home Depot store or online. Reload Gift Card value at any The Home Depot store or online at HomeDepot.com. For cross-border redemptions, Gift Card is redeemable at The Home Depotâs applicable local currency exchange rate at the time of redemption. Gift Card is issued by Home Depot Incentives, Inc. Š 2020 Home Depot Product Authority, LLC. All rights reserved."
},
"productImage": "https://dmyxigrg1v9vl.blackhawknetwork.com/gcmimages/product/xlarge/84151.png",
"valueRestrictions": {
"minimum": 5,
"maximum": 1000
},
"offFaceDiscountPercent": -1.0
}, {
"contentProviderCode": "GameStop",
"productName": "GameStop",
"productDescription": "GameStop is a family of specialty retail brands that makes the most popular technologies affordable and simple.",
"parentBrandName": "GameStop",
"termsAndConditions": {
"type": "INLINE",
"text": "This gift card is redeemable only for the purchase of merchandise only in the U.S. at GameStop, ThinkGeek, EBGames, Babbage's, and Planet X stores and online at GameStop.com. Card does not expire or impose any fees. Except where required by law, it may not be returned, redeemed for cash, or applied as payment on any account, and will not be replaced if lost or stolen. Not responsible for unauthorized use. This card is not a credit card or a debit card and carries no warranties, express or implied. This card is issued by and represents solely the obligation of Marketing Control Services, Inc. (a Virginia corporation), which reserves the right to change these terms and conditions at any time. Use or acceptance of this card constitutes acceptance of these terms and conditions. To obtain your card balance, visit www.gamestop.com.\r\n\r\n"
},
"productImage": "https://dmyxigrg1v9vl.cloudfront.net/images/merchant-cards/game-stop.png",
"logoImage": "https://dmyxigrg1v9vl.cloudfront.net/images/merchant-logos/GamestopLogo.png",
"valueRestrictions": {
"minimum": 15,
"maximum": 500
},
"offFaceDiscountPercent": -2.1
},
{
"contentProviderCode": "DardenBrands",
"productName": "Bahama BreezeÂŽ",
"productDescription": "Bahama Breeze is the restaurant that brings you the feeling of a Caribbean escape, offering the food, drink and atmosphere you would find in the islands! For locations, visit us at www.bahamabreeze.com.",
"parentBrandName": "Bahama Breeze (Darden)",
"redemptionInfo": "DardenÂŽ Restaurants Gift Card can be redeemed at any Olive GardenÂŽ, LongHorn SteakhouseÂŽ, Cheddarâs Scratch KitchenÂŽ, Bahama BreezeÂŽ, Seasons 52ÂŽ or Yard HouseÂŽ restaurant in the U.S.",
"termsAndConditions": {
"type": "INLINE",
"text": "Use of this Card constitutes acceptance of the Gift Card terms and conditions. This Gift Card is issued by and represents an obligation solely of Darden SV, Inc. (âDardenâ). Each time you use it, we'll deduct that amount from the balance until you've used the full balance of the card. (1) Except where required by law, this gift card is not redeemable for cash. (2) We can't replace the value on this card if it's lost or stolen. (3) Valid at participating restaurants in the U.S. (4) Approval is required to advertise this card; (5) This eGift Card may not be used to purchase alcohol where prohibited by law; (6) eGift Card does not expire; (7) This eGift Card deemed purchase from and issued in the State of Florida; (8) Risk of loss and title to the eGift Card passes to the purchaser upon electronic transmission to the recipient; (9) eGift Card balance may not be transferred to a physical gift card; however, eGift Card may be printed or reprinted for redemption. \r\n\r\nFor eGift Card balance, activity and complete terms and conditions (including agreement to arbitrate and waiver of jury trial) visit www.darden.com or call toll-free 1-877-500-9706. Š 2018 Darden Concepts, Inc."
},
"productImage": "https://dmyxigrg1v9vl.cloudfront.net/images/merchant-cards/darden.png",
"valueRestrictions": {
"minimum": 5,
"maximum": 250
},
"offFaceDiscountPercent": -2.1
}, {
"contentProviderCode": "DardenBrands",
"productName": "DardenÂŽ Restaurants Gift Card",
"productDescription": "One Card, All the Favorites! With over 1,800 restaurants in all 50 states, the Darden Gift Card is One Card with All the Favorites including Olive GardenÂŽ, LongHorn SteakhouseÂŽ, Cheddarâs Scratch KitchenÂŽ, Yard HouseÂŽ, Seasons 52ÂŽ and Bahama BreezeÂŽ",
"parentBrandName": "Darden",
"redemptionInfo": "DardenÂŽ Restaurants Gift Card can be redeemed at any Olive GardenÂŽ, LongHorn SteakhouseÂŽ, Cheddarâs Scratch KitchenÂŽ, Bahama BreezeÂŽ, Seasons 52ÂŽ or Yard HouseÂŽ restaurant in the U.S.",
"termsAndConditions": {
"type": "INLINE",
"text": "Use of this Card constitutes acceptance of the Gift Card terms and conditions. This Gift Card is issued by and represents an obligation solely of Darden SV, Inc. (âDardenâ). Valid at participating restaurants in the U.S. Each time you use it, weâll deduct that amount from the balance until youâve used the full balance of the card. (1) Except where required by law, this gift card is not redeemable for cash. (2) We canât replace it if itâs lost or stolen. (3) Approval required to advertise this card. For Gift Card balance, activity and complete terms and conditions (including agreement to arbitrate and waiver of jury trial) visit www.darden.com or call toll-free 1-877-500-9706 Š 2020 Darden Concepts, Inc."
},
"productImage": "https://dmyxigrg1v9vl.cloudfront.net/images/merchant-cards/darden.png",
"valueRestrictions": {
"minimum": 5,
"maximum": 250
},
"offFaceDiscountPercent": -2.1
}, {
"contentProviderCode": "DardenBrands",
"productName": "LongHorn SteakhouseÂŽ",
"productDescription": "LongHorn Steakhouse is known for fresh, boldly seasoned and expertly grilled steaks â like the signature bone-in Outlaw RibeyeÂŽ â all served in a relaxed, warm atmosphere inspired by a rancher's home. For more information and to find a location near you, visit www.longhornsteakhouse.com.",
"parentBrandName": "LongHorn Darden",
"redemptionInfo": "DardenÂŽ Restaurants Gift Card can be redeemed at any Olive GardenÂŽ, LongHorn SteakhouseÂŽ, Cheddarâs Scratch KitchenÂŽ, Bahama BreezeÂŽ, Seasons 52ÂŽ or Yard HouseÂŽ restaurant in the U.S.",
"termsAndConditions": {
"type": "INLINE",
"text": "Use of this Card constitutes acceptance of the Gift Card terms and conditions. This Gift Card is issued by and represents an obligation solely of Darden SV, Inc. (âDardenâ). Each time you use it, we'll deduct that amount from the balance until you've used the full balance of the card. (1) Except where required by law, this gift card is not redeemable for cash. (2) We can't replace the value on this card if it's lost or stolen. (3) Valid at participating restaurants in the U.S. (4) Approval is required to advertise this card; (5) This eGift Card may not be used to purchase alcohol where prohibited by law; (6) eGift Card does not expire; (7) This eGift Card deemed purchase from and issued in the State of Florida; (8) Risk of loss and title to the eGift Card passes to the purchaser upon electronic transmission to the recipient; (9) eGift Card balance may not be transferred to a physical gift card; however, eGift Card may be printed or reprinted for redemption. \r\n\r\nFor eGift Card balance, activity and complete terms and conditions (including agreement to arbitrate and waiver of jury trial) visit www.darden.com or call toll-free 1-877-500-9706. Š 2018 Darden Concepts, Inc."
},
"productImage": "https://dmyxigrg1v9vl.cloudfront.net/images/merchant-cards/darden.png",
"valueRestrictions": {
"minimum": 5,
"maximum": 250
},
"offFaceDiscountPercent": -2.1
}, {
"contentProviderCode": "DardenBrands",
"productName": "Olive GardenÂŽ",
"productDescription": "Olive Garden delights guests with a genuine Italian dining experience, featuring a range of fresh, simple and delicious dishes, including many inspired by our Culinary Institute of Tuscany in Italy, and an award-winning wine list. For locations, visit us at www.olivegarden.com.",
"parentBrandName": "Olive Garden (Darden)",
"redemptionInfo": "DardenÂŽ Restaurants Gift Card can be redeemed at any Olive GardenÂŽ, LongHorn SteakhouseÂŽ, Cheddarâs Scratch KitchenÂŽ, Bahama BreezeÂŽ, Seasons 52ÂŽ or Yard HouseÂŽ restaurant in the U.S.",
"termsAndConditions": {
"type": "INLINE",
"text": "Use of this Card constitutes acceptance of the Gift Card terms and conditions. This Gift Card is issued by and represents an obligation solely of Darden SV, Inc. (âDardenâ). Each time you use it, we'll deduct that amount from the balance until you've used the full balance of the card. (1) Except where required by law, this gift card is not redeemable for cash. (2) We can't replace the value on this card if it's lost or stolen. (3) Valid at participating restaurants in the U.S. (4) Approval is required to advertise this card; (5) This eGift Card may not be used to purchase alcohol where prohibited by law; (6) eGift Card does not expire; (7) This eGift Card deemed purchase from and issued in the State of Florida; (8) Risk of loss and title to the eGift Card passes to the purchaser upon electronic transmission to the recipient; (9) eGift Card balance may not be transferred to a physical gift card; however, eGift Card may be printed or reprinted for redemption. \r\n\r\nFor eGift Card balance, activity and complete terms and conditions (including agreement to arbitrate and waiver of jury trial) visit www.darden.com or call toll-free 1-877-500-9706. Š 2018 Darden Concepts, Inc."
},
"productImage": "https://dmyxigrg1v9vl.cloudfront.net/images/merchant-cards/darden.png",
"valueRestrictions": {
"minimum": 5,
"maximum": 250
},
"offFaceDiscountPercent": -2.1
}, {
"contentProviderCode": "DardenBrands",
"productName": "Seasons 52ÂŽ",
"productDescription": "Seasons 52 is a celebration of whatâs good now. Seasonally inspired ingredients at their peak of freshness. Rustic cooking techniques that bring out natural flavors and create flavorful dishes that are simply lighter. And an ever-changing selection of global wines. All in a casually sophisticated setting. Come discover whatâs good now. Visit us online at Seasons52.com.",
"parentBrandName": "Seasons 52 (Darden)",
"redemptionInfo": "DardenÂŽ Restaurants Gift Card can be redeemed at any Olive GardenÂŽ, LongHorn SteakhouseÂŽ, Cheddarâs Scratch KitchenÂŽ, Bahama BreezeÂŽ, Seasons 52ÂŽ or Yard HouseÂŽ restaurant in the U.S.",
"termsAndConditions": {
"type": "INLINE",
"text": "Use of this Card constitutes acceptance of the Gift Card terms and conditions. This Gift Card is issued by and represents an obligation solely of Darden SV, Inc. (âDardenâ). Each time you use it, we'll deduct that amount from the balance until you've used the full balance of the card. (1) Except where required by law, this gift card is not redeemable for cash. (2) We can't replace the value on this card if it's lost or stolen. (3) Valid at participating restaurants in the U.S. (4) Approval is required to advertise this card; (5) This eGift Card may not be used to purchase alcohol where prohibited by law; (6) eGift Card does not expire; (7) This eGift Card deemed purchase from and issued in the State of Florida; (8) Risk of loss and title to the eGift Card passes to the purchaser upon electronic transmission to the recipient; (9) eGift Card balance may not be transferred to a physical gift card; however, eGift Card may be printed or reprinted for redemption. \r\n\r\nFor eGift Card balance, activity and complete terms and conditions (including agreement to arbitrate and waiver of jury trial) visit www.darden.com or call toll-free 1-877-500-9706. Š 2018 Darden Concepts, Inc."
},
"productImage": "https://dmyxigrg1v9vl.cloudfront.net/images/merchant-cards/darden.png",
"valueRestrictions": {
"minimum": 5,
"maximum": 250
},
"offFaceDiscountPercent": -2.1
}, {
"contentProviderCode": "DardenBrands",
"productName": "Yard HouseÂŽ",
"productDescription": "Yard House is an upscale, casual eatery known for its extensive menu of contemporary American cuisine, classic rock music and an endless fleet of tap handle featuring craft, import and specialty ales & lagers. For locations, visit us at www.yardhouse.com.",
"parentBrandName": "Yard House (Darden)",
"redemptionInfo": "DardenÂŽ Restaurants Gift Card can be redeemed at any Olive GardenÂŽ, LongHorn SteakhouseÂŽ, Cheddarâs Scratch KitchenÂŽ, Bahama BreezeÂŽ, Seasons 52ÂŽ or Yard HouseÂŽ restaurant in the U.S.",
"termsAndConditions": {
"type": "INLINE",
"text": "Use of this Card constitutes acceptance of the Gift Card terms and conditions. This Gift Card is issued by and represents an obligation solely of Darden SV, Inc. (âDardenâ). Each time you use it, we'll deduct that amount from the balance until you've used the full balance of the card. (1) Except where required by law, this gift card is not redeemable for cash. (2) We can't replace the value on this card if it's lost or stolen. (3) Valid at participating restaurants in the U.S. (4) Approval is required to advertise this card; (5) This eGift Card may not be used to purchase alcohol where prohibited by law; (6) eGift Card does not expire; (7) This eGift Card deemed purchase from and issued in the State of Florida; (8) Risk of loss and title to the eGift Card passes to the purchaser upon electronic transmission to the recipient; (9) eGift Card balance may not be transferred to a physical gift card; however, eGift Card may be printed or reprinted for redemption. \r\n\r\nFor eGift Card balance, activity and complete terms and conditions (including agreement to arbitrate and waiver of jury trial) visit www.darden.com or call toll-free 1-877-500-9706. Š 2018 Darden Concepts, Inc."
},
"productImage": "https://dmyxigrg1v9vl.cloudfront.net/images/merchant-cards/darden.png",
"valueRestrictions": {
"minimum": 5,
"maximum": 250
},
"offFaceDiscountPercent": -2.1
}, {
"contentProviderCode": "DardenBrands",
"productName": "Cheddar's Scratch KitchenÂŽ",
"productDescription": "Cheddarâs Scratch Kitchen believes in simple, honest and natural ingredients. Scratch-made recipes, handcrafted with care and time. Scratch cooking is about doing things the right way instead of the easy way and Cheddarâs Scratch Kitchen invests time and effort to prepare every meal by hand. When a meal is prepared and cooked fresh, it not only tastes better, it makes you feel good. This is why Cheddarâs Scratch Kitchen slow-cooks and house-smokes their meats early in the morning, like their Baby Back Ribs. And theyâre constantly chopping, whisking, sautĂŠing and stirring, so theyâre ready whenever youâre ready to eat.",
"parentBrandName": "DardenÂŽ Restaurants, Inc.",
"redemptionInfo": "DardenÂŽ Restaurants Gift Card can be redeemed at any Olive GardenÂŽ, LongHorn SteakhouseÂŽ, Cheddarâs Scratch KitchenÂŽ, Bahama BreezeÂŽ, Seasons 52ÂŽ or Yard HouseÂŽ restaurant in the U.S.",
"termsAndConditions": {
"type": "INLINE",
"text": "Use of this Card constitutes acceptance of the Gift Card terms and conditions. This Gift Card is issued by and represents an obligation solely of Darden SV, Inc. (âDardenâ). Each time you use it, we'll deduct that amount from the balance until you've used the full balance of the card. (1) Except where required by law, this gift card is not redeemable for cash. (2) We can't replace the value on this card if it's lost or stolen. (3) Valid at participating restaurants in the U.S. (4) Approval is required to advertise this card; (5) This eGift Card may not be used to purchase alcohol where prohibited by law; (6) eGift Card does not expire; (7) This eGift Card deemed purchase from and issued in the State of Florida; (8) Risk of loss and title to the eGift Card passes to the purchaser upon electronic transmission to the recipient; (9) eGift Card balance may not be transferred to a physical gift card; however, eGift Card may be printed or reprinted for redemption. \r\n\r\nFor eGift Card balance, activity and complete terms and conditions (including agreement to arbitrate and waiver of jury trial) visit www.darden.com or call toll-free 1-877-500-9706. Š 2018 Darden Concepts, Inc."
},
"productImage": "https://dmyxigrg1v9vl.cloudfront.net/images/merchant-cards/darden.png",
"valueRestrictions": {
"minimum": 5,
"maximum": 250
},
"offFaceDiscountPercent": -2.1
}, {
"contentProviderCode": "Macys",
"productName": "Macy's",
"productDescription": "Use your Macyâs gift card at the âWorldâs Most Famous Storeâ. It gives you access to everything Macyâs is renowned for: designer collections, the seasonâs newest and best trends, the latest home styles, or the perfect gift for any occasion. Shop at over 700 Macyâs stores nationwide or online at macys.com. Plus, Macyâs Gift Cards never expire or incur fees.",
"parentBrandName": "Macy's",
"termsAndConditions": {
"type": "INLINE",
"text": "Macyâs gift cards may be used to purchase merchandise and in-store services at any Macyâs store or on-line at macys.com, only. They may not be redeemed for cash (except as required by law) nor applied as a payment or credit to any card account. Card receipts will show any remaining balance. Terms & Conditions apply to all gift cards. See back of card for details.\nMacyâs is not a sponsor or co-sponsor of this program. The Macyâs name and logo are registered trademarks of Macyâs Inc. Please refer to back of Gift Card for complete terms and condition of use.\n\n"
},
"productImage": "https://dmyxigrg1v9vl.cloudfront.net/images/merchant-cards/macys.png",
"logoImage": "",
"valueRestrictions": {
"minimum": 25,
"maximum": 145,
"exclusivelyAllowedValues": [
25,
40,
50,
60,
65,
70,
75,
80,
85,
100,
105,
120,
125,
140,
145
]
},
"offFaceDiscountPercent": -1.5
}
]
}
Calling the Catalog API by Sub Organization ID
To call the Catalog API by Sub Organization ID we will be using /clientProgramsBySubOrg
.
Method | Service Name | Service Type |
---|---|---|
GET | clientProgramsBySubOrg â Explore | Synchronous |
From our application, when calling /clientProgramsBySubOrg
, we need to send the following parameters in the HTTP header.
Parameter | Description | Type | Required |
---|---|---|---|
MerchantId | The Merchant ID (MID) is a string identifier issued by BHN to each merchant for billing purposes. | String | Yes |
RequestId | A unique identifier for each order provided by you (the caller). The requestId value must be unique for each request and can have a maximum of 50 characters. | String | Yes |
Accept | This should be set to the following string to ensure all characters are correctly encoded in the response:Accept: application/json; charset=utf-8 | String | No |
In our example we will be sending the following values in the header:
Content-Type: application/json
Accept: application/json; charset=utf-8
merchantId:1234
requestId:2019-08-16T16:41:00-0600
We will also need to send the subOrgId in the URL as follows:
https://apipp.blackhawknetwork.com/rewardsCatalogProcessing/v1/clientProgramsBySubOrg?subOrgId=12345
The following HTTP status codes may be returned in the response header:
HTTP Status Code | Meaning | Notes |
---|---|---|
200 | Operation Complete | The query returned successfully. |
4XX | Invalid Request | Check the JSON error response provided. In most cases you will find the request had missing information or was formatted improperly. |
5XX | System Error | Blackhawk Network encountered an internal error trying to process your order. Reach out to your Account Manager for more information. |
Assuming the query was successful a JSON object will be returned in the response containing the following information.
In our case, since we are querying by subOrgID the response is an array of client programs associated with the provided Sub Organization ID instead of just one program. Refer to the detailed object information in the Calling the Catalog API by Program section above.
Here is a sample JSON response when calling by subOrgID:
{
"current": "https://apipp.blackhawknetwork.com/rewardsCatalogProcessing/v1/clientProgramsBySubOrg",
"totalCount": 10,
"currentResults": [
{
"clientProgramId": 95000309,
"programName": "VISA Reload ATM ACH CK BT NO FEES Alternative FIS",
"programType": "PHYSICAL",
"currency": "USD",
"products": [ {
"productImage": "https://d29xemkaawaj37.cloudfront.net/resized/default-visa-385x245.png",
"valueRestrictions": {
"minimum": 0,
"maximum": 99999
},
"expirationDescription": "2027-06-01",
"expiration": {
"type": "STATIC",
"date": "2027-06-01"
},
"cardholderFees": [
{
"calculationType": "AMOUNT",
"name": "ACH Transfer Fee",
"amount": 10
},
{
"calculationType": "AMOUNT",
"name": "AME ATM Domestic Withdrawal Fee",
"amount": 1.75
}
]
}]
},
{
"clientProgramId": 95000375,
"programName": "Open Loop Visa Bulk ANO CC Standard Activation",
"programType": "PHYSICAL",
"currency": "USD",
"products": [ {
"productImage": "https://d29xemkaawaj37.cloudfront.net/resized/20190506201514_Executive Silver Visa-no denom-3-4 line.png-385x245.png",
"valueRestrictions": {"minimum": 0},
"expirationDescription": "5 months",
"expiration": {
"type": "ROLLING",
"numberOfMonths": 5
},
"cardholderFees": [
{
"calculationType": "AMOUNT",
"name": "Expedited Replacement Fee $20.00",
"amount": 20
},
{
"calculationType": "PERCENT",
"name": "Currency Conversion 2%",
"percent": 2
},
{
"calculationType": "AMOUNT",
"name": "Replace Card Fee $10",
"amount": 5
}
]
}]
},
{
"clientProgramId": 95000383,
"programName": "Promo Visa Bulk ANO - Data Validation-Activation Code",
"programType": "PHYSICAL",
"currency": "USD",
"products": [ {
"productImage": "https://d29xemkaawaj37.cloudfront.net/resized/20190506201514_Executive Silver Visa-no denom-3-4 line.png-385x245.png",
"valueRestrictions": {"minimum": 0},
"expirationDescription": "20 months",
"expiration": {
"type": "ROLLING",
"numberOfMonths": 20
},
"cardholderFees": [
{
"calculationType": "PERCENT",
"name": "Currency Conversion 2%",
"percent": 2
},
{
"calculationType": "AMOUNT",
"name": "Expedited Replacement Fee $20.00",
"amount": 20
},
{
"calculationType": "AMOUNT",
"name": "Replace Card Fee $10",
"amount": 10
}
]
}]
},
{
"clientProgramId": 95000402,
"programName": "Visa Personalized Bulk no PID",
"programType": "PHYSICAL",
"currency": "USD",
"products": [ {
"productImage": "https://d29xemkaawaj37.cloudfront.net/resized/20190506201514_Executive Silver Visa-no denom-3-4 line.png-385x245.png",
"valueRestrictions": {
"minimum": 1,
"maximum": 2000
},
"expirationDescription": "23 months",
"expiration": {
"type": "ROLLING",
"numberOfMonths": 23
},
"cardholderFees": [
{
"calculationType": "AMOUNT",
"name": "Replacement Fee $6.95 No Free",
"amount": 6.95
},
{
"calculationType": "AMOUNT",
"name": "Expedited Replacement Fee $20.00",
"amount": 20
},
{
"calculationType": "PERCENT",
"name": "Currency Conversion 2%",
"percent": 2
}
]
}]
},
{
"clientProgramId": 95000403,
"programName": "Visa Personalized Bulk - Client Supplied PID",
"programType": "PHYSICAL",
"currency": "USD",
"products": [ {
"productImage": "https://d29xemkaawaj37.cloudfront.net/resized/20190506201514_Executive Silver Visa-no denom-3-4 line.png-385x245.png",
"valueRestrictions": {
"minimum": 0,
"maximum": 0
},
"expirationDescription": "6 months",
"expiration": {
"type": "ROLLING",
"numberOfMonths": 6
},
"cardholderFees": [
{
"calculationType": "PERCENT",
"name": "Currency Conversion 2%",
"percent": 2
},
{
"calculationType": "AMOUNT",
"name": "Expedited Replacement Fee $20.00",
"amount": 20
},
{
"calculationType": "AMOUNT",
"name": "Replacement Fee $6.95 No Free",
"amount": 6.95
}
]
}]
},
{
"clientProgramId": 95000417,
"programName": "Visa Personalized Individual - System Generated PID",
"programType": "PHYSICAL",
"currency": "USD",
"products": [ {
"productImage": "https://d29xemkaawaj37.cloudfront.net/resized/20190506201514_Executive Silver Visa-no denom-3-4 line.png-385x245.png",
"valueRestrictions": {
"minimum": 1,
"maximum": 2000
},
"expirationDescription": "12 months",
"expiration": {
"type": "ROLLING",
"numberOfMonths": 12
},
"cardholderFees": [
{
"calculationType": "AMOUNT",
"name": "Expedited Replacement Fee $20.00",
"amount": 20
},
{
"calculationType": "AMOUNT",
"name": "Replacement Fee $6.95 No Free",
"amount": 6.95
},
{
"calculationType": "PERCENT",
"name": "Currency Conversion 2%",
"percent": 2
}
]
}]
},
{
"clientProgramId": 95000422,
"programName": "Visa PERS Individual Suppress Carrier Msg - Waive Shipping",
"programType": "PHYSICAL",
"currency": "USD",
"products": [ {
"productImage": "https://d29xemkaawaj37.cloudfront.net/resized/20190506201514_Executive Silver Visa-no denom-3-4 line.png-385x245.png",
"valueRestrictions": {
"minimum": 1,
"maximum": 2000
},
"expirationDescription": "22 months",
"expiration": {
"type": "ROLLING",
"numberOfMonths": 22
},
"cardholderFees": [
{
"calculationType": "PERCENT",
"name": "Currency Conversion 2%",
"percent": 2
},
{
"calculationType": "AMOUNT",
"name": "Replacement Fee $6.95 No Free",
"amount": 6.95
},
{
"calculationType": "AMOUNT",
"name": "Expedited Replacement Fee $20.00",
"amount": 20
}
]
}]
},
{
"clientProgramId": 95000436,
"programName": "Bulk ANO Suppress 4th Line & Carrier Msg - No Defined Denom",
"programType": "PHYSICAL",
"currency": "USD",
"products": [ {
"productImage": "https://d29xemkaawaj37.cloudfront.net/resized/20190506201514_Executive Silver Visa-no denom-3-4 line.png-385x245.png",
"valueRestrictions": {
"minimum": 0,
"exclusivelyAllowedValues": [
100,
25,
50,
75
]
},
"expirationDescription": "24 months",
"expiration": {
"type": "ROLLING",
"numberOfMonths": 24
},
"cardholderFees": [
{
"calculationType": "AMOUNT",
"name": "Expedited Replacement Fee $20.00",
"amount": 20
},
{
"calculationType": "PERCENT",
"name": "Currency Conversion 2%",
"percent": 2
},
{
"calculationType": "AMOUNT",
"name": "Replace Card Fee $10",
"amount": 10
}
]
}]
},
{
"clientProgramId": 95000461,
"programName": "Bulk Anonymous Data Capture",
"programType": "PHYSICAL",
"currency": "USD",
"products": [ {
"productImage": "https://d29xemkaawaj37.cloudfront.net/resized/20190506201514_Executive Silver Visa-no denom-3-4 line.png-385x245.png",
"valueRestrictions": {"minimum": 0},
"expirationDescription": "18 months",
"expiration": {
"type": "ROLLING",
"numberOfMonths": 18
},
"cardholderFees": [
{
"calculationType": "AMOUNT",
"name": "Replace Card Fee $10",
"amount": 10
},
{
"calculationType": "AMOUNT",
"name": "Expedited Replacement Fee $20.00",
"amount": 20
},
{
"calculationType": "PERCENT",
"name": "Currency Conversion 2%",
"percent": 2
}
]
},
}]
{
"clientProgramId": 95000465,
"programName": "Personalized Ind Credit Card - Client Supplied PID",
"programType": "PHYSICAL",
"currency": "USD",
"products": [ {
"productImage": "https://d29xemkaawaj37.cloudfront.net/resized/default-mc-385x245.png",
"valueRestrictions": {
"minimum": 1,
"maximum": 75000
},
"expirationDescription": "24 months",
"expiration": {
"type": "ROLLING",
"numberOfMonths": 24
},
"cardholderFees": [
{
"calculationType": "AMOUNT",
"name": "Replace Card Fee $10",
"amount": 10
},
{
"calculationType": "AMOUNT",
"name": "Expedited Replacement Fee $20.00",
"amount": 20
},
{
"calculationType": "PERCENT",
"name": "Currency Conversion 2%",
"percent": 2
},
{
"calculationType": "AMOUNT",
"name": "Replacement Fee $6.95",
"amount": 6.95
}
]
}]
}
]
}
Updated about 1 month ago