Read Product Lines by Criteria

Introduction

This API returns a list of product line entities for the product lines that meet the specified criteria and cursor view parameters.

Method	Service Name	Service Type
GET	productManagement/v1/readProductLines	Synchronous

Post-Production URI: https://api.certification.blackhawknetwork.com/productManagement/v1/readProductLines?{first}={firstIndex}&{maximum}={maximumNumofEntries}&{sortKey}=(summary|details).{attributeName}&{ascending}={true|false}&{exactMatch}={true|false}&{caseSensitive}={true|false}&{lt|le|gt|ge|eq|ne}({summary|details}.{attributeName},{attributeValue})
Production URI: https://api.blackhawknetwork.com/productManagement/v1/readProductLines?{first}={firstIndex}&{maximum}={maximumNumofEntries}&{sortKey}=(summary|details).{attributeName}&{ascending}={true|false}&{exactMatch}={true|false}&{caseSensitive}={true|false}&{lt|le|gt|ge|eq|ne}({summary|details}.{attributeName},{attributeValue})

Request Header Attributes

Note that all three of the header attributes are optional; however, if you want idempotency support then you should specify all three on every request.

Parameter	Description	Type	Required
requestorId	A value defined by the client application that can be used to uniquely identify that client application. If the client application does not specify a value, a globally unique identifier will be filled in automatically.	String	N
requestId	A value defined by the client application that can be used to uniquely identify that specific request from the client. This value should be set if the client application wants to take advantage of an idempotent operation on a service.	String	N
previousAttempts	The number of times this same request has been attempted unsuccessfully before. A value that is greater than zero will cause the service to view this request as a retry attempt and it will be treated idempotently.	Integer	N

In our example we will be sending the following values in the header:

Content-Type: application/json
requestorId: 1234
requestId: 2019-06-12T15:35:28-0500
previousAttempts: 0

Request Elements

Since this is a get request the request elements need to be sent in the URI itself. https://api.blackhawknetwork.com/productManagement/v1/readProductLines?{first}={firstIndex}&{maximum}={maximumNumofEntries}&{sortKey}=(summary|details).{attributeName}&{ascending}={true|false}&{exactMatch}={true|false}&{caseSensitive}={true|false}&{lt|le|gt|ge|eq|ne}({summary|details}.{attributeName},{attributeValue})

The following parameters are available:

Parameter	Description	Type	Required
first	The index of the first entity in this cursor view of the list. The default first index is zero referring to the first entity in the full list.	Integer String	N
maximum	The maximum number of entities to be shown in this cursor view of the list. The default value is 10.	Integer String	N
sortKey	The name of the attribute that should be used for ordering the results. If this value is not provided, then there is no explicit sorting of the results. Only attributes in product line summary can be used for for ordering the results.	String	N
ascending	Whether or not the results are sorted in ascending order. The default value is true.	Boolean String	N
exactMatch	Flag to exactly match the provided supported features.	Boolean	N
caseSensitive	Flag to exactly match the case of the supported features.	Boolean	N

Response Elements

The following elements are returned in the response.

Name	Description	Type
productLine	List of matching product line entities.	List
total	Int	Total count returned from the query.
parameters	List	The Request Elements specified in the request or their default values if none specified.

Product Line

Name	Description	Type	Max. Length	Mandatory
entityId	A reference to the URI for the product line.	URI	255	N
summary	The entity Product Line Summary.	Entity		Y
details	The entity Product Line Details.	Entity		N

Product Line Summary

Name	Description	Type	Max Length	Mandatory
entityId	A reference to the URI for the product line.	URI	255	N
brandName	The name of the brand.	String	255	Y
brandLogoImage	The URI of the logo image of the brand.	String	255	N
productLineName	Name of the product line.	String		Y
brandId	ID of the brand.	String	26	N
productLineStatus	The status of the product line. The possible values are in the Product Line Status enumeration.	Enum		N
accountType	The account type of the product line. The possible values are in the Account Type enumeration.	Enum		N
paymentNetworkType	The payment network type of the product line. The possible values are in the Payment Network Type enumeration.	Enum		N
startDate	The date from which the product line becomes active.	Date		Y
endDate	The date at which the product line becomes inactive.	Date		N
locale	The two-character ISO 639-1 language code followed by the two-character country code, separated by an underscore, e.g., en_US.	Locale	5	N

^ Back to Product Line

Product Line Status

Enum Value	Description
DRAFT	New product line in draft mode.
ACTIVATED	Product line in active mode.
SUSPENDED	Product line in suspended mode.

^ Back to Product Line Summary

Account Type

Enum Value	Description
CREDIT_CARD	Credit card
GIFT_CARD	Gift card
LOYALTY_CARD	Loyalty card
PHONE_CARD	Phone card

^ Back to Product Line Summary

Payment Network Type

Enum Value	Description
VISA	Visa
MASTERCARD	Master Card
DISCOVER	Discover
AMEX	American Express

^ Back to Product Line Summary

Product Line Details

Name	Description	Type	Max. Length	Mandatory
creatorId	A reference to the URI for the person who created this product line	URI	255	N
updaterId	A reference to the URI for the person who last updated this product line	URI	255	N
notes	Any notes associated with the last update of the product line	String	255	N
createdTimestamp	Date and time (UTC) at which the entity was created	Date		N
updatedTimestamp	Date and time (UTC) at which the entity was last updated	Date		N
productLineDescription	The description of the product line	String	1024	N
customerServicePhoneNumber	The customer service phone number	String	255	N
customerServiceWebsite	The customer service website URI	String	255	N
termsAndConditions	The set of Terms And Conditions of the product line	Set		N
cardNumberLabel	The text that represents the card number in the card	String	255	N
defaultProductId	The default product ID of the product line	String	255	N
defaultCurrency	The default currency supported by the product line	String	3	Y
bankIdentificationNumbers	The set of bank identification numbers supported by the product line	Set		N
pinRequired	Whether a PIN is required for cards of this product line	Boolean		N
supportedFeatures	The features supported by the product line	Set		N
activationType	The types of activation supported for the cards under this product line	Activation Type		Y
pinCharacteristics	The PIN characteristics of the card. The presence of this field indicates that the CardDetails.securityCode is required for redemption.	Pin Characteristics		N
defaultRedemptionCharacteristics	The default redemption characteristics of the product line	Redemption Characteristics		N
defaultReloadCharacteristics	The default reload characteristics of the product line	Reload Characteristics		N
productAffiliation	The list of product affiliations	List		N
defaultProductFees	The list of product fees	List		N
defaultProductImages	The set of default product images for this product line	Set		N
defaultFulfillmentCharacteristics	The list of fulfillment characteristics of the product line	List		N
balanceCharacteristics	The balance characteristics of the cards of this product line	Balance Characteristics		N
lostStolenCharacteristics	The lost-stolen characteristics for this product line	Lost Stolen Characteristics		N

^ Back to Product Line

Terms and Conditions

Name	Description	Type	Max. Length	Mandatory
id	The primary key for this entity.This is used only for internal purposes.	String	26	N
termsAndConditions	The terms and conditions of the product line	String		N
termsAndConditionsType	The type of terms and conditions	Terms And Conditions Type		Y

^ Back to Product Line Details

Terms And Conditions Type

Enum Value	Description
WEB	Web
EMAIL	Email
PHYSICAL	Physical

^ Back to Terms and Conditions

Supported Features

Enum Value	Description
PHYSICAL_CARD	Product line supports physical card
VIRTUAL_CARD	Product Line supports virtual card
REPLACEABLE_CARD	Product Line supports card replacement
TRANSFERABLE_CARD	Product line supports transferring card ownership
BALANCE_MERGES	Product line supports merging card balances
CARDS_EXPIRE	Cards supported by the product line have an expiration date
WALLET_ADD_QR_CODE	Card supports QR code
UNIVERSAL_BALANCE_INQUIRY	Product Line supports universal balance inquiry
PARTIAL_BALANCE_INQUIRY	Product Line only supports partial balance inquiry
REDEMPTION	Product Line supports redemption on the card
VOID_REDEMPTION	Product Line supports void of the redemption done on the card
RELOAD	Product Line supports reload of the card
VOID_RELOAD	Product Line supports void of the reload done on the card
REGIFT	Product line supports Regift
TRANSACTION_HISTORY	Product line supports transaction history on card
VOID_ACTIVATION	Product Line supports void activation
HAS_PHONE_SUPPORT_AT_POS	Product Line supports scanning a barcode from a mobile phone during redemption

^ Back to Product Line Details

PIN Characteristics

Name	Description	Type	Max. Length	Mandatory
pinLabel	The text that represents the security PIN on the card	String	255	Y
pinLocation	The possible places on the card where the security PIN can be located	Location		Y
pinType	The types of PINs that the cards under this product line can have	Pin Type		Y

^ Back to Product Line Details

PIN Location

Enum Value	Description
FRONT	Front of the card
BACK	Back of the card

^ Back to PIN Characteristics

PIN Type

Enum Value	Description
SCRATCH_OFF	Scratch off
PRINTED	Printed
SEPARATE	Separate

^ Back to PIN Characteristics

Redemption Characteristics

Name	Description	Type	Max. Length	Mandatory
redemptionWebsite	The website where a card can be redeemed	String	255	N
additionalDataLabel	The text of the additional data on the card needed for redemption	String	255	N
redemptionMode	This enumerated type captures the possible types of redemption for a card	Redemption Mode		N
manualEntryFormat	The format of the redemption data if entered manually	String	255	N
barCodeCharacteristics	The set of barcode characteristics of the card	Set		N
redemptionText	The Redemption Text entity for the product line. This field is being retained for backwards compatibility. Clients should prefer to use the newer redemptionTexts field.	Redemption Text		N
redemptionTexts	Set of Redemption Text entities for the product line. This is the preferred method of associating redemption text entities to product lines. The redemptionText field has been retained for backwards compatibility.	Set		N
redemptionOptions	The possible redemption options available for the products under this product line	Set		N
magneticStripeCharacteristics	The magnetic stripe characteristics of the product line	Magnetic Stripe Characteristics		N
isBarCodeScanSupported	Add card by scanning in Bar Code (when scanning in a card using bar code, is bar code number = redemption number).	Boolean		N
productExpirationDate	Static expiration date for the card	Date		N
rollingExpirationDays	Number of days to determine dynamic expiration date that is dependent on the date of activation	Int		N

^ Back to Product Line Details

Redemption Mode

Enum Value	Description
BAR_CODE	Bar Code
MAGNETIC_STRIPE	Magnetic Stripe
NEAR_FIELD	Near Field
MANUAL_ENTRY	User Entered

^ Back to Redemption Characteristics

Barcode Characteristics

Name	Description	Type	Max. Length	Mandatory
id	The primary key for the entity.This is used only for internal purposes	String	26	N
barCodeFormat	The format of the bar code	String	255	N
barCodeType	This enumerated type captures the possible barcode types	Barcode Type		N
barCodeSubType	This enumerated type captures the possible barcode subtypes	Barcode Subtype		N

^ Back to Redemption Characteristics

Barcode Type

Enum Value	Description
ONE_DIMENSIONAL	One Dimensional
TWO_DIMENSIONAL	Two Dimensional

^ Back to Barcode Characteristics

Barcode Sub Type

Enum Value	Description
CA128	Bar Code is of type CA128
PDF417	Bar Code is of type PDF417
QRCODE	Bar Code is of type QR Code

^ Back to Barcode Characteristics

Redemption Text

Name	Description	Type	Max. Length	Mandatory
id	The primary key of the entity. This is used only for internal purposes.	String	26	N
text	The redemption text instructs how to redeem a card.	String	8192	N
redemptionTextType	The possible redemption text types available for the cards under this product line.	Redemption Text Type		N

^ Back to Redemption Characteristics

Redemption Text Type

Enum Value	Description
REDEMPTION_INFORMATION	Redemption Information
IN_STORE_INSTRUCTIONS	In-store instructions
ON_LINE_INSTRUCTIONS	Online instructions
REDEMPTION_LINE_1	Redemption line 1
REDEMPTION_LINE_2	Redemption line 2
SALES_ASSOCIATE_INSTRUCTIONS	Sales associate instructions

^ Back to Redemption Text

Redemption Options

Enum Value	Description
ON_LINE	Redemption available online
IN_STORE	Redemption available only in store

^ Back to Redemption Characteristics

Magnetic Stripe Characteristics

Name	Description	Type	Max. Length	Mandatory
redemptionTracks	The track number(s) on the magnetic stripe which should be used for redemption	Set		N
track1Format	The format of Track 1	String	255	N
track2Format	The format of Track 2	String	255	N
track3Format	The format of Track 3	String	255	N

^ Back to Redemption Characteristics

Reload Characteristics

Name	Description	Type	Mandatory
minReloadAmount	The minimum amount that has to be reloaded on a card	BigDecimal	N
maxReloadAmount	The maximum amount that can be reloaded on a card	BigDecimal	N
isReloadable	Indicates if the card is reloadable	Boolean	N

^ Back to Product Line Details

Product Affiliation

Name	Description	Type	Max. Length	Mandatory
companyId	The unique ID for the company	String	255	N
affiliationType	This enumeration captures the possible systems from which the balance of the card can be obtained	Affiliation Type		Y
id	The primary key of the entity. This is used only for internal purposes.	String		N

^ Back to Product Line Details

Affiliation Type

Enum Value	Description
CONTENT_PROVIDER	Content provider
ISSUER	Issuer of the physical card
ISSUER_DIVISION	Issuer division
PROCESSOR	Processor, i.e. who generated the card number
PROCESSOR_DIVISION	Processor division

^ Back to Product Affiliation

Product Fees

Name	Description	Type	Max. Length	Mandatory
chargeAmount	The charge amount	BigDecimal		N
feeType	This enumeration captures the possible fee types	Fee Type		N
id	The primary key of the entity. This is used only for internal purposes.	String	26	N

^ Back to Product Line Details

Fee Type

Enum Value	Description
CUSTOMIZATION	Legal disclaimer image
PURCHASE	Purchase
INACTIVITY	Inactivity
TRANSACTION	Transaction
REPLACEMENT	Replacement

^ Back to Product Fees

Product Images

Name	Description	Type	Max. Length	Mandatory
frontImage	The image on the front of the card	String	255	N
backImage	The image on the back of the card	String	255	N
imageSize	This enumeration captures the possible sizes of image	Image Size		N
imageType	This enumeration captures the possible types of image	Image Type		N
id	The primary key of the entity. This is used only for internal purposes.	String	255	N

^ Back to Product Line Details

Image Size

Enum Value	Description
SMALL	Small Image (119x76)
MEDIUM	Medium Image (144x92)
LARGE	Large Image (240x153)
EXTRA_LARGE	Extra Large Image (308x198)

^ Back to Product Images

Image Type

Enum Value	Description
LEGAL_DISCLAIMER	Legal disclaimer image
TERMS_CONDITIONS	Terms and conditions image
PRINT_ON_DEMAND_IMAGE	Print on demand image

^ Back to Product Images

Fulfillment Characteristics

Name	Description	Type	Max. Length	Mandatory
id	The primary key for the entity. This is used only for internal purposes.	String		N
fulfillmentInformation	Fulfillment information	String	1024	N
holdTimeSeconds	Hold time in seconds	BigDecimal		N
printingType	Printing type	Printing Type		N
provisioningType	Provisioning type	Provisioning Type		N
fulfillmentMethod	Fulfillment method	Fulfillment Method		N

^ Back to Product Line Details

Printing Type

Enum Value	Description
PRINT_ON_DEMAND	Print on demand
PRE_PRINTED	Pre-printed for physical card
SEMI_PRE_PRINTED	Semi pre-printed for physical card
CUSTOM_PRINT_ON_DEMAND	Custom print-on-demand for physical card

^ Back to Fulfillment Characteristics

Provisioning Type

Enum Value	Description
PHYSICAL	Provisioning type for physical card
DIGITAL	Provisioning type for digital card

^ Back to Fulfillment Characteristics

Fulfillment Method

Enum Value	Description
SHIPMENT	Shipment for physical card
EMAIL	Email for virtual card
URL	URL for virtual card
IMAGEDATA	Image data for virtual card
SMS	SMS for virtual card

^ Back to Fulfillment Characteristics

Balance Characteristics

Name	Description	Type	Mandatory
areBalancesTransferable	Indicates whether balance transfer can be done for the cards that belong to this product line	Boolean	N
balanceLockTimeFrame	Time to wait for the next balance inquiry	Integer	N
hasUniversalBISupport	Whether the cards under the product line have universal support for balance inquiry	Boolean	N
pinRequiredforBI	Whether the PIN is required for balance inquiry	Boolean	N

^ Back to Product Line Details

Lost Stolen Characteristics

Name	Description	Type	Max. Length	Mandatory
lostStolenPolicyText	The lost and stolen policy text for the cards	String	2048	N
lostStolenContactPhone	The contact number in order to report lost or stolen cards	String	50	N
isLostStolenPolicyAutomated	Whether the lost and stolen policy is automated	Boolean		N

^ Back to Product Line Details

Sample Request and Response

Click on the tabs below to see a sample GET request and the sample response.

GET /productManagement/v1/readProductLines?first=0&maximum=10&sortKey=summary.brandName&ascending=true&exactMatch=false&caseSensitive=false&eq(summary.productLineStatus,ACTIVATED)&ge(details.createdTimestamp,2013-06-01T21:12:00.000%2B0000)&le(details.createdTimestamp,2020-06-02T21:12:00.000%2B0000) HTTP/1.1
requestorID: ZPZB7DDS20PNHALMZCBX14RVCM
Content-Type: application/json; charset=UTF-8
Accept: application/json; charset=UTF-8
Host: api.blackhawknetwork.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.2 (java 1.5)

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
Cache-Control: max-age=3600
Date: Tue, 09 Jul 2013 18:41:44 GMT
Content-Type: application/json
Content-Length: 5673

{
   "results":[
      {
         "entityId":"https://api.blackhawknetwork.com/productManagement/v1/productLine/LRWMS0GDZSJ6PAD180DC937T2M",
         "summary":{
            "entityId":"https://api.blackhawknetwork.com/productManagement/v1/productLine/LRWMS0GDZSJ6PAD180DC937T2M",
            "productLineName":"Retailer_A",
            "brandName":"Retailer_A",
            "brandCode":"",
            "brandLogoImage":"https://content.giftcardmall.com/gcmimages//MANUFACTURER/icon/GOWALLET_METADATA/380V4646.0.PNG",
            "productLineStatus":"ACTIVATED",
            "accountType":"GIFT_CARD",
            "startDate":"2012-09-17T22:54:14.987+0000",
            "endDate":"2023-02-19T22:59:41.280+0000",
            "locale":"en_US"
         },
         "details":{
            "creatorId":"088AJZT9Y91NB8147AVKZ9QJP4",
            "updaterId":"088AJZT9Y91NB8147AVKZ9QJP4",
            "createdTimestamp":"2013-06-13T17:21:03.912+0000",
            "updatedTimestamp":"2013-06-13T17:21:03.912+0000",
            "additionalAttributes":[
            ],
            "productLineDescription":"A generic retailer",
            "defaultProductId":"088AJZT9Y91NB8147AVKZ9QJP4",
            "bankIdentificationNumbers":[
            ],
            "supportedFeatures":[
               "UNIVERSAL_BALANCE_INQUIRY"
            ],
            "activationType":"ONE_STEP",
            "productAffiliations":[
            ],
            "defaultProductImages":[
               {
                  "id":"VSGJ8Y6R5S15Q7X6XPWHY11R64",
                  "frontImage":"https://content.giftcardmall.com/gcmimages//MANUFACTURER/medium/GOWALLET_METADATA/380V4646.0.PNG"
               }
            ],
            "termsAndConditions":[
               {
                  "id":"B5CY1GPCX5C79VN9B02GZ03870",
                  "termsAndConditions":"Terms and conditions text",
                  "termsAndConditionsType":"PHYSICAL"
               }
            ],
            "defaultRedemptionCharacteristics":{
               "redemptionText":{
                  "text":"Online and Retailer_A Shop Redemption only",
                  "redemptionTextType":"REDEMPTION_INFORMATION"
               },
               "redemptionTexts":[
               ],
               "redemptionOptions":[
                  "ON_LINE",
                  "IN_STORE"
               ],
               "barCodeCharacteristics":[
               ],
               "magneticStripeCharacteristics":{
                  "redemptionTracks":[
                  ]
               }
            },
            "defaultProductFees":[
            ],
            "defaultFulfillmentCharacteristics":[
            ],
            "defaultCurrency":"CAD",
            "balanceCharacteristics":{
               "balanceInquirySystem":"BLAST",
               "balanceLockTimeframe":0
            }
         }
      },
      {
         "entityId":"https://api.blackhawknetwork.com/productManagement/v1/productLine/NJ8ZXBVPDAKG5H378JFG8QLLY8",
         "summary":{
            "entityId":"https://api.blackhawknetwork.com/productManagement/v1/productLine/NJ8ZXBVPDAKG5H378JFG8QLLY8",
            "productLineName":"Retailer_B",
            "brandName":"Retailer_B",
            "productLineStatus":"ACTIVATED",
            "accountType":"GIFT_CARD",
            "startDate":"2008-09-17T20:16:53.793+0000",
            "endDate":"2023-03-12T01:59:00.000+0000",
            "locale":"en_US"
         },
         "details":{
            "creatorId":"088AJZT9Y91NB8147AVKZ9QJP4",
            "updaterId":"088AJZT9Y91NB8147AVKZ9QJP4",
            "createdTimestamp":"2013-06-14T05:04:17.882+0000",
            "updatedTimestamp":"2013-06-14T05:04:17.882+0000",
            "additionalAttributes":[
            ],
            "productLineDescription":"A clothing retailer",
            "bankIdentificationNumbers":[
            ],
            "supportedFeatures":[
            ],
            "activationType":"ONE_STEP",
            "productAffiliations":[
            ],
            "defaultProductImages":[
               {
                  "id":"MBZL5PH4PSJPKJY9YPGX4491ZR",
                  "frontImage":"https://content.giftcardmall.com/gcmimages/manufacturer/large/88.jpg"
               }
            ],
            "termsAndConditions":[
               {
                  "id":"VZC36ZVGF8MS9ZP9RH45CDFYL8",
                  "termsAndConditions":"Gift Card Terms & Conditions",
                  "termsAndConditionsType":"PHYSICAL"
               }
            ],
            "defaultRedemptionCharacteristics":{
               "redemptionText":{
                  "text":"Retail stores located nationwide.",
                  "redemptionTextType":"REDEMPTION_INFORMATION"
               },
               "redemptionTexts":[
               ],
               "redemptionOptions":[
                  "ON_LINE",
                  "IN_STORE"
               ],
               "barCodeCharacteristics":[
               ],
               "magneticStripeCharacteristics":{
                  "redemptionTracks":[
                  ]
               }
            },
            "defaultProductFees":[
            ],
            "defaultFulfillmentCharacteristics":[
            ],
            "defaultCurrency":"CAD",
            "balanceCharacteristics":{
               "balanceInquirySystem":"BLAST"
            }
         }
      }
   ],
   "total":2,
   "parameters":{
      "first":0,
      "maximum":10,
      "sortKey":"summary.brandName",
      "ascending":true
   }
}

Introduction

Request Header Attributes

Request Elements

Response Elements

Product Line

Product Line Summary

Product Line Status

Account Type

Payment Network Type

Product Line Details

Terms and Conditions

Terms And Conditions Type

Supported Features

PIN Characteristics

PIN Location

PIN Type

Redemption Characteristics

Redemption Mode

Barcode Characteristics

Barcode Type

Barcode Sub Type

Redemption Text

Redemption Text Type

Redemption Options

Magnetic Stripe Characteristics

Reload Characteristics

Product Affiliation

Affiliation Type

Product Fees

Fee Type

Product Images

Image Size

Image Type

Fulfillment Characteristics

Printing Type

Provisioning Type

Fulfillment Method

Balance Characteristics

Lost Stolen Characteristics

Sample Request and Response

Developer Central Agreement