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 IntegrationDiagram showing a sample Hawk Marketplace API Integration

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
to be used during reconciliation and to facilitate idempotence.

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/201

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 globally unique string identifier specified by the application making the request
to be used during reconciliation and to facilitate idempotence.

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/201

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
               }
            ]
         }]
      }
   ]
}

Did this page help you?