Frequently Asked Questions
What is a Client Program Number, a Quote ID or a Product ID?
This is the program identification number automatically assigned when a quote is created. It is an eight digit long number.
Note: Client Program Number, Quote ID and Product ID are different names for the same number.
How can I get my Client Program Number
Your account manager will provide details for your product setup and Client Program Number.
Is there a website that can be used to check orders and product details?
Yes, the Hawk Marketplace portal can be used to check order status and product details. Your account manager will be able to share the details with you on how to access the portal.
How many products can I add under one Client Program Number?
For open loop reward, gift or disbursement programs only one product can be added to a client program number. If more than one product is required, a separate client program number will be provided for each product.
For closed loop merchant digital and physical gift products multiple products can be added to a single client program number. When ordering the content provider code is used to specify which product you would like to order within the client program.
How can I connect to the Hawk Marketplace pre-production and production environment?
Please work with your project manager to obtain a signed client certificate. Certificates are different for both pre-production and production environments.
What is the base URL for pre-production environment?
What is the base URL for production environment?
What SSL/TLS versions are supported for digital certificates?
TLSv1.2 and above.
Are digital certificates required for ordering via APIs?
Digital certificates are required in both pre-production and production environments and must be sent with every request.
Hawk Marketplace Portal
How can I get access to the Hawk Marketplace portal?
Your account manager will provide the credentials and URLs for the Hawk Marketplace portal.
What type of details can be checked on the Hawk Marketplace portal?
The Hawk Marketplace portal is useful for placing orders manually, checking the status of orders, seeing the product details, fees, merchants and discounts.
What is a Merchant ID?
The Merchant ID (MID) is a string identifier, provided by your account manager that varies based on the product type you are ordering.
What is a Request ID?
The Request ID is a globally unique string identifier specified by your client application. Every request must have a unique Request ID.
What is the purpose of MillisecondsToWait?
The MillisecondsToWait HTTP header value indicates that how long your application is willing to wait for a response. A value of 0 milliseconds means that the transaction type will be processed asynchronously. The maximum value is 30000 (30 seconds). Different products and program types have different recommended best practice values for the millisecondsToWait parameter. Please consult with your implementation project manager to ensure you use the value recommended for your program and implementation type.
What is the purpose of SYNCHRONOUS_ONLY?
The SYNCHRONOUS_ONLY HTTP header only applies to real-time eGift and Virtual card orders. The purpose of this parameter is to specify if the behavior of the POST call will be asynchronous or synchronous.
If the value is
true and order processing is not completed within the millisecondsToWait time specified in the request header, then the order request will be cancelled.
Does Blackhawk Network perform any maintenance to the API?
Blackhawk Network has a daily platform maintenance window from 11:00 PM - 3:00 AM Central Time. In most cases there will be little to no impact on the APIs during that period. However, your implementation should be built with enough resilience to handle potential downtime or additional latency.
Which API method is used for retrieving eGift card details?
GET - /eGiftBulkCodeRetrievalInfo/byKeys is the method for retrieving eGift card information by passing orderNumber or requestId and clientProgramNumber.
Is there an API for cancelling an order request?
Cancelling an order cannot be performed through the API. To cancel an order request, please notify your Account Manager and provide them with the order number.
Is there any method for checking order shipping status?
GET - /queryShippingInfo is the method used to get the shipping information by passing orderNumber, cardholderFirstName, cardholderLastName.
Which API method is used for retrieving virtual codes?
GET - /virtualCodeRetrievalInfo/byKeys is the method for retrieving virtual code information by passing orderNumber or requestId and clientProgramNumber.
Which API method is used to check my order status after submission?
GET - /orderInfo/byKeys is the method used to get the order information by passing orderNumber or requestId and clientProgramNumber
Do these API methods support an Asynchronous Service Model?
The ordering APIs are a hybrid synchronous-asynchronous model, where the response behavior may be either synchronous or asynchronous depending on current processing load, request complexity, and input from your client application. The MillisecondsToWait parameter is used to indicate how long the client application is willing to wait for a response.
A response object or error object (if the operation was unsuccessful) will be returned within that time frame. If the request is still in process after the time specified in the MillisecondsToWait parameter has been exceeded, the interaction becomes asynchronous, and a transactionId value is provided. All GET requests within Rewards Order Processing API are synchronous.
What types of HTTP response codes API will return?
The following response codes may be returned from these APIs.
- 200: Operation complete - Your request completed successfully, no further action is needed.
- 201: Operation complete - Your request completed successfully, no further action is needed.
- 202: Operation is in process - Your request is still in process.
- 400: Invalid Request - There was an error in the request. Check your request payload and retry with a new request id.
- 409: Conflict - Usually this means you used a duplicate request id. Retry the request with a new request id.
- 5XX: Gateway or service error - There is a temporary issue with the service or gateway. Please try again later.
Which characters are allowed for placing orders via API?
Allowed characters vary by field. Please refer to the appropriate order guide and specific field for more information.
Is it required to send email content using the API if we configure the content within Hawk Marketplace directly?
No, it is not required to send email content through the API. However, email content sent using the API will override what is configured within Hawk Marketplace.
Updated about 1 month ago