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.
Your account manager will provide details for your product setup and Client Program Number.
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.
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.
Please work with your project manager to obtain a signed client certificate. Certificates are different for both pre-production and production environments.
TLSv1.2 and above.
Digital certificates are required in both pre-production and production environments and must be sent with every request.
Your account manager will provide the credentials and URLs for 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.
The Merchant ID (MID) is a string identifier, provided by your account manager that varies based on the product type you are ordering.
The Request ID is a globally unique string identifier specified by your client application, to be used during reconciliation. Every request must have a unique Request ID.
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.
The SYNCHRONOUS_ONLY HTTP header only applies to real-time eGift 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 initial order request's millisecondsToWait time, then the order request will be cancelled.
false is provided (or the header is omitted) the order request will continue to process after the millisecondsToWait period has expired and any reward URLs or codes will need to be retrieved separately by calling /eGiftBulkCodeRetrievalInfo/byKeys.
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.
GET - /eGiftBulkCodeRetrievalInfo/byKeys is the method for retrieving eGift card information by passing orderNumber or requestId and clientProgramNumber.
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.
GET - /queryShippingInfo is the method used to get the shipping information by passing orderNumber, cardholderFirstName, cardholderLastName.
GET - /virtualCodeRetrievalInfo/byKeys is the method for retrieving virtual code information by passing orderNumber or requestId and clientProgramNumber.
GET - /orderInfo/byKeys is the method used to get the order information by passing orderNumber or requestId and clientProgramNumber
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.
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. Check back later by making a GET request using the transaction id.
- 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.
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 4 days ago