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
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 |
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 |
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 |
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 |
PIN Type
Enum Value | Description |
---|---|
SCRATCH_OFF | Scratch off |
PRINTED | Printed |
SEPARATE | Separate |
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 |
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 | Max. Length | 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 |
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 |
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) |
Image Type
Enum Value | Description |
---|---|
LEGAL_DISCLAIMER | Legal disclaimer image |
TERMS_CONDITIONS | Terms and conditions image |
PRINT_ON_DEMAND_IMAGE | Print on demand image |
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 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 | Max. Length | 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
}
}
Updated 7 months ago