Real-time eGift Email and SMS Orders
Introduction
Real-time ordering allows you to place single orders for eGifts quickly. You are limited to placing a single order at a time but the eGift is delivered more quickly and skips our internal order batching process.
Want to skip the details? Jump right to the full order JSON
Individual Delivery
Real-time individual ordering allows you to order one eGift to be sent by BHN to a specific recipient via email.
In this guide we will be placing an order for one $25 Best BuyÂŽ eGift.
When using the real-time endpoint you can only order one item at a time for a single recipient.
Placing the Order for Individual Delivery
To place the order we will be using submitRealTimeEgiftIndividual.
| Method | API Service | Endpoint | Type |
|---|---|---|---|
| POST | rewardsOrderProcessing | submitRealTimeEgiftIndividual â Explore | Hybrid synchronous/asynchronous based on millisecondToWait parameter. |
URI:https://api.certification.blackhawknetwork.com/rewardsOrderProcessing/v1/submitRealTimeEgiftIndividual
From our application we need to send the following parameters in the HTTP header:
| Parameter | Description | Type | Required | Default Value |
|---|---|---|---|---|
| merchantId | The Merchant ID (MID) is a string identifier, provided to you by your account manager that varies based on the product type you are ordering. | String | Yes | None |
| requestId | A unique identifier for each order provided by you (the caller). This identifier will be used during reconciliation. The requestId must be unique with a maximum of 50 characters. | String | Yes | None |
| millisecondsToWait | Provide a value between 0 - 30000 to indicate how long your application or service will wait for a response. Once this time is exceeded the request will become asynchronous.The required value is 15000 (15 seconds) or greater. | Integer | No | 2000 |
| SYNCHRONOUS_ONLY | If the value provided is true and the order processing is not completed within the initial order request's millisecondsToWait time, then the order will be cancelled and an HTTP 504 status code returned. | Boolean | No | false |
Real-time API millisecondsToWait RequirementFor our real-time APIs we require you to send a value between 15000 and 30000 in the millisecondsToWait header. The API will respond more quickly if the request completes before the specified time.
In our example we will be sending the following values in the header:
Content-Type: application/json
merchantId: 20200009887
requestId: 23453445433
millisecondsToWait: 30000
SYNCHRONOUS_ONLY: trueIn the body of the POST request we need to send all the information needed to complete the order.
| Parameter | Description | Type | Required | Allowed Values |
|---|---|---|---|---|
| clientProgramNumber | The client program number supplied by your Account Manager for the program you are placing your order under. | Integer | Yes | Must be a valid client program number / quote number assigned to you. |
| paymentType | This value in this attribute specifies the payment method to be used for the order.Note: The payment type value provided must match one of the payment types setup on the client program you are placing an order in or your order request will be rejected. | String | No | ACH_DEBIT DRAW_DOWN |
| financialAccountId | The financial account ID (FAID) specifies the financial account associated with your sub-organization to be used for the order.When a value is provided for the financialAccountId the paymentType attribute is required. A value for financialAccountId only needs to be provided when there are multiple financial accounts setup for a sub-organization. Your Implementation Project Manager or Account Manager will direct when you need to provide a value in this field. | String | No | The value provided must match a valid financial account ID configured for your sub-organization. |
| poNumber | PO numbers must be 50 characters or less. | String | No | Digits 0-9, alpha (a-z, A-Z), space, period and hyphen. |
| smsContent | SMS Content Information | String | No | |
| rewardDeliveryMethod | Reward delivery method can be either Email or SMS | String | Yes | |
| emailContent | Content for the email delivered to the eGift individual | Object | Yes | |
| orderDetails | The product you wish to order. | Object | Yes |
Providing the Order Details for Individual Delivery
We will pass the details for the order in the orderDetails object:
| Parameter | Description | Type | Required | Allowed Values |
|---|---|---|---|---|
| clientRefId | Unique client reference to identify duplicates. Must be 30 characters or less. | String | No | Digits 0-9, alpha (a-z, A-Z), space, period, comma, hyphen, forward slash (/) and apostrophe. |
| recipient | Information about the recipient for this eGift. | Object | Yes | Valid Recipient Object |
| amount | Specify the value of the eGift. Note: Allowed values vary based on the merchant and eGift. For more information consult with your Account Manager. | Number | Yes | Digits 0-9 and period.May not contain symbols and may have up to two digits after the decimal separator.Example: 25.00 |
| description | Must be 40 characters or less. | String | No | Digits 0-9, alpha (a-z, A-Z), space and period. |
| contentProvider | This identifier specifies which product you are ordering. | String | Yes | A valid content provider code as provided by your account manager or returned by the Catalog API. |
Providing the Recipient Information
We need to provide information about each recipient we are delivering an eGift to.
| Parameter | Description | Type | Required | Allowed Values |
|---|---|---|---|---|
| id | Unique identifier, must be 30 characters or less. | String | No | Digits 0-9, Alpha (a-z, A-Z) and period. |
| firstName | First name of the recipient, this must be 50 characters or less. | String | Yes | Digits 0-9, alpha (a-z, A-Z), space, period, comma and hyphen. |
| lastName | Last name of the recipient, this must be 50 characters or less. | String | Yes | Digits 0-9, alpha (a-z, A-Z), space, period, comma and hyphen. |
| The email address of the individual recipient. | String | Yes | Digits 0-9, alpha (a-z, A-Z), period and hyphen. Format: Must have an @ symbol and at least one period. | |
| phone number | If reward delivery type is SMS, field should contain +1 followed by the recipients 10 digit phone number with no spaces or additional symbols | String | No | Digits 0-9 |
Providing SMS Content
SMS Content becomes required if the rewardDeliveryMethod is set to SMS. Since these orders will be delivered via SMS, we need to provide some details for the order template that will be used in the SMS messages that get sent to the end recipients.
| Parameter | Description | Type | Required |
|---|---|---|---|
| smsMessage | SMS message cannot exceed 140 characters | String | No |
| companyName | Company Name must be 50 characters or less | String | Yes |
Providing Email Content
Since these orders will be delivered via email we need to provide some details for the order template that will be used in the emails that get sent to the end recipients.
Parameter | Description | Type | Required |
|---|---|---|---|
senderName | This is the name of the sender as shown on the email. This cannot exceed 50 characters. | String | No |
senderEmail | The sender email address as shown on the email. This cannot exceed 90 characters. | String | No |
subject | The email subject line. This cannot exceed 200 characters. | String | No |
emailMessage | The message to the recipient of the email. See the example template image below. This cannot exceed 10,000 characters. The following tokens can be included and will be dynamically replaced in the recipient email:
| String | No |
| isDefaultTemplate | This can be used to save these values as the default for future use. The default value is "false". | Boolean | No |
| unsubscribeData | Information required to inform recipients on how to unsubscribe from emails. | Object | Yes |
| emailTemplateID | Email Template ID from the client program | String | No |
Providing Unsubscribe Data
As you can see from the table above we also need to supply information about how the recipient can unsubscribe.
| Parameter | Description | Type | Required |
|---|---|---|---|
| companyName | Cannot exceed 50 characters. | String | Yes |
| addressLine1 | Cannot exceed 200 characters. | String | Yes |
| addressCity | Cannot exceed 100 characters. | String | Yes |
| addressState | Address state must be a valid 2-character uppercase abbreviation for a U.S. state or a Canadian province or contain an international region less than 36 characters. | String | Yes |
| addressZip | AddressZip must be a valid 5-digit U.S. zip code or a valid international postal code less than 11 characters. | String | Yes |
| addressCountry | Address country is required and must be either UNITED STATES or CANADA. | String | Yes |
| methodType | Must be one of: EMAIL, WEBSITE, NONE. | String | Yes |
| value | This is the detail for the unsubscribe method. Typically an email address or website URL. Cannot exceed 255 characters. | String | Yes |
Let's take a moment and put all the JSON for the email together.
"emailContent": {
"senderName": "Blackhawk Network",
"senderEmail": "[email protected]",
"subject": "Your eGift Reward Has Arrived!",
"emailMessage": "Dear {first name}, Thank you for participating in our program! Please enjoy your eGift as a token of our appreciation.",
"unsubscribeData" : {
"companyName" : "Blackhawk Network",
"addressLine1" : "700 State Highway 121 Bypass Ste. 200",
"addressCity" : "Lewisville",
"addressState" : "TX",
"addressZip" : "75067",
"addressCountry" : "USA",
"methodType" : "EMAIL",
"value" : "[email protected]"
}
}Below we can see how all of this information maps to the email that gets sent to the recipient. Note that unsubscribe information is at the very bottom of the image.
In order for the first and last name to show in the recipient email you must include the tokens {first name} and/or {last name} in the emailMessage attribute (dependent on your requirements).
Submitting the Order
Now it is time for us to combine all the information we have put together and actually place the egift order.
To do that we will make an HTTP POST request to https://api.certification.blackhawknetwork.com/rewardsOrderProcessing/v1/submitRealTimeEgiftIndividual, sending the header parameters as we outlined above, with the following combined JSON in the body of the request.
{
"clientProgramNumber": "43251004",
"poNumber": "2345",
"emailContent": {
"senderName": "Blackhawk Network",
"senderEmail": "[email protected]",
"subject": "Your eGift Reward Has Arrived!",
"emailMessage": "Dear {first name}, Thank you for participating in our program! Please enjoy your eGift as a token of our appreciation.",
"unsubscribeData" : {
"companyName" : "Blackhawk Network",
"addressLine1" : "700 State Highway 121 Bypass Ste. 200",
"addressCity" : "Lewisville",
"addressState" : "TX",
"addressZip" : "75067",
"addressCountry" : "USA",
"methodType" : "EMAIL",
"value" : "[email protected]"
}
},
"orderDetails": [{
"recipient": {
"id": "",
"firstName": "Daffy",
"lastName": "Duck",
"email": "[email protected]"
},
"amount": "25",
"contentProvider": "BestBuy_eGift",
"description": "This is a reward for Daffy Duck"
}]
}The API will return a response containing an HTTP status code in the header and a JSON object in the body. This response will tell us if the order was successful and if it has been completed or not.
The following HTTP status codes may be returned in the response header.
| HTTP Status Code | Meaning | Notes |
|---|---|---|
| 201 | Operation Complete | The order was created successfully. |
| 202 | Operation is in Process | If For real-time orders with SYNCHRONOUS_ONLY set as true you will not receive a 202 response if the order has not completed within the |
| 4XX | Invalid Request | Check the JSON error response provided. In most cases you will find the request had missing information or was formatted improperly. If you have any questions reach out to your Account Manager. |
| 5XX | System Error | There was an internal error trying to process your order. Try again later, if the error persists please reach out to your Account Manager. |
| 504 | Timeout | For real-time orders with SYNCHRONOUS_ONLY set as true you will not receive a 202 response if the order has not completed within the millisecondsToWait time. Instead the order will be canceled and you will receive a 504 status code. |
Order has Completed Processing
Assuming our order was placed successfully we receive the following JSON in the response:
{
"transactionId": "435LYTF8GAS6NCB3R9TLCXWY30",
"isCompleted": true,
"percentComplete": 100,
"success": true,
"orderNumber": "401087290"
}This indicates we have successfully placed an order. The recipient eGift email will now be automatically placed into a queue for delivery.
Updated 2 months ago