Individual eGift Orders

Introduction

Individual ordering allows you to order one or many eGifts at the same time that are associated to an individual. In this case Blackhawk Network will deliver the eGift to the individual via email.

In this guide we will be placing an order for three $25 Best Buy® eGifts.

Note: Blackhawk Network recommends a maximum of 5,000 order line items per order request. If you have more than 1,000 line items you will need to break your order into multiple order requests of 1,000 records each.

📘

Want to skip the details? Jump right to the full order JSON

Placing the eGift Order

To place an individual order we will be using submitEgiftIndividual.

Method

Service

API

Type

POST

rewardsOrderProcessing

submitEgiftIndividual → Explore

Hybrid synchronous/asynchronous based on millisecondToWait parameter

URI: https://apipp.blackhawknetwork.com/rewardsOrderProcessing/v1/submitEgiftIndividual

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 recommended value is 15000 (15 seconds).

Integer

No

2000

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

Content-Type: application/json
merchantId: 60300003779
requestId: 2019-06-12T15:35:28-0500
millisecondsToWait: 30000

In 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
WIRE_TRANSFER
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.

orderDetails

The products and quantities you wish to order.

Object

Yes

emailContent

Content for the email delivered to the eGift individual

Object

Yes

poNumber

PO numbers must be 50 characters or less.

String

No

Digits 0-9, alpha (a-z, A-Z), space, period and hyphen.

Providing the Order Details

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

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.

email

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.

Since we want to place three orders, each for a $25 BestBuy® eGift, to three different recipients our JSON will look like this:

"orderDetails": [{
    "recipient": {
        "firstName": "Daffy",
        "lastName": "Duck",
        "email": "[email protected]"
    },
    "amount": "25",
    "contentProvider": "BestBuy_eGift",
    "description": "This is a reward for Daffy Duck"        
},{
    "recipient": {
        "firstName": "Mickey",
        "lastName": "Mouse",
        "email": "[email protected]"
    },
    "amount": "25",
    "contentProvider": "BestBuy_eGift",
    "description": "This is a reward for Mickey Mouse"      
},{
    "recipient": {
        "firstName": "Abraham",
        "lastName": "Lincoln",
        "email": "[email protected]"
    },
    "amount": "25",
    "contentProvider": "BestBuy_eGift",
    "description": "This is a reward for the President"     
},
}]

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 1024 characters.

The following tokens can be included and will be dynamically replaced in the recipient email:

  • {first name}
  • {last name}
  • {amount}
  • {email address}

String

No

emailClosingName

The name used to sign off at the bottom of the email. This cannot exceed 200 characters.

String

No

isDefaultTemplate

This can be used to save these values as the default for future use.

Boolean

No

unsubscribeData

Information required to inform recipients on how to unsubscribe from emails.

Object

Yes

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, 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 in the following format:

  • UNITED STATES
  • CANADA
  • UNITED KINGDOM
  • AUSTRALIA

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

For our example we will populate the following information:

"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]"
}

We need to take that JSON and add it to the JSON for our email content. Here is the sample JSON:

"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.",
    "emailClosingName": "Jane Doe",
    "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://apipp.blackhawknetwork.com/rewardsOrderProcessing/v1/submitEgiftIndividual, sending the header parameters as we outlined above, with the following combined JSON in the body of the request.

{
    "clientProgramNumber": "43251004",
    "returnCardNumberAndPIN" : "false",
    "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.",
        "emailClosingName": "Jane Doe",
        "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": {
            "firstName": "Daffy",
            "lastName": "Duck",
            "email": "[email protected]"
        },
        "amount": "25",
        "contentProvider": "BestBuy_eGift",
        "description": "This is a reward for Daffy Duck"
    },{
        "recipient": {
            "firstName": "Mickey",
            "lastName": "Mouse",
            "email": "[email protected]"
        },
        "amount": "25",
        "contentProvider": "BestBuy_eGift",
        "description": "This is a reward for Mickey Mouse"
    },{
        "recipient": {
            "firstName": "Abraham",
            "lastName": "Lincoln",
            "email": "[email protected]"
        },
        "amount": "25",
        "contentProvider": "BestBuy_eGift",
        "description": "This is a reward for the President"
    }]
}

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

If isCompleted is not equal to "true" and percentComplete is not 100 the order has not completed.

202

Operation is in Process

If isCompleted is not equal to "true" and percentComplete is not 100 the order has not completed.

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

Blackhawk Network encountered an internal error trying to process your order. Reach out to your Account Manager for more information.

What to do if the order is still processing

This happens if the order is still processing and we have exceeded the millisecondsToWait value (or the maximum timeout of 30 seconds). In that case the JSON in the response returned will indicate that the order has not yet completed and the current percent complete. For example we may see a response like this:

{
   "transactionId": "435LYTF8GAS6NCB3R9TLCXWY30",
   "isCompleted": false,
   "percentComplete": 66,
   "success": false
}

When this happens the transaction becomes asynchronous. We need to wait some time and then make an HTTP GET request to orderInfo to see if the order has completed processing.

Next steps when the 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 emails will now be automatically placed into a queue for delivery.


Did this page help you?