Gift Purchases

Last modified May 15, 2019

This article applies to Contextual Commerce. (Looking for Classic Commerce documentation?)


About Gift Purchases

Gift purchases allow customers to place an order on behalf of someone else and make payment for a product that will be fulfilled to the gift recipient.

For gift purchases, there are two separate types of contacts associated with each transaction:

  • The purchaser is the customer who places a gift order via your Storefront and pays for the order. The purchaser supplies the information for both contacts and does not receive any fulfillment information.
  • The recipient is the person for whom the gift is being purchased. The recipient does not pay anything or participate in placing the order, but will receive all applicable fulfillments for all items in the gift order. Just as a customer account is created for every unique purchaser, a separate customer account with its own account ID will be created for the recipient of a gift purchase. This also means that recipients will be able to view their fulfillment information via their account management pages.

Important Notes About Gift Purchases

  • Currently, gift purchases are not available for subscriptions; only for standalone / perpetual license products. If a subscription product is selected, the Gift Purchase check box is automatically removed from the form, along with the associated Recipient Information fields.
  • When making a gift purchase, customers must pay using an instant payment method such as a credit or debit card, PayPal, or Amazon Pay. Delayed payment methods such as wire transfers and purchase orders are not accepted for gift purchases.
  • If an order that is processed as a gift purchase includes more than one product, all products in the order are considered gifts to the specified recipient. It is not currently possible to combine gifts and non-gifts in a single purchase.
  • Gift purchases are not intended for use when purchasing a gift for a recipient located in another country. Gift purchases should only be used to purchase gifts for recipients who are in the same country as the purchaser.
  • The purchaser and recipient email addresses must be different. If a customer attempts to place an order with the same email address for both purchaser and recipient, the Storefront will display an error message explaining this.


Customer Experience

When gift purchases are enabled for a Web Storefront or a Popup Storefront, purchasers have the option to designate a transaction as a gift purchase by selecting the Gift Purchase check box in the payment form.

A Web Storefront with gift purchases enabled 


A Popup Storefront with gift purchases enabled

When the Gift Purchase check box is selected, the form automatically expands to include additional fields. The purchaser must enter the gift recipient's details for product fulfillment in addition to his or her own details and payment information. The purchaser may optionally enter a gift message (maximum 400 characters) to be delivered to the recipient along with the fulfillment(s).

A Popup Storefront with the Gift Purchase check box selected and the Recipient Information section highlighted


Sales Tax Note

For orders in the United States, the purchaser must enter the recipient's ZIP code because the calculation of sales tax will be based on the recipient's location. Gift orders should only be placed when the purchaser and recipient are located in the same country.

Email Address Note

The recipient's email address must be different than the purchaser's email address entered below.

When the transaction is complete, the purchaser will be presented with a completion page showing the order reference and details of the transaction, including amounts, but no fulfillment information will be displayed to the purchaser. Instead, the fulfillment details will be emailed automatically to the gift recipient's email address. The gift recipient's fulfillment email message will not contain price information or charge details.

The completion page of a Popup Storefront order as a gift purchase

Tip

For Popup Storefronts, you can control the color of the gift icon shown at the top of the completion page via the Popup Storefront's SETTINGS → Colors and Styling → Completion Page - Checkmark Color.


Example of the fulfillment message sent to a gift recipient


Conversely, the purchaser's receipt email message will contain details of the price and payment method, but will not include fulfillment details.

Example of the receipt email message sent to a purchaser who made a gift purchase


When visiting the Account Management page and viewing a gift purchase, the recipient will not see any payment or price details; only the fulfillment details.

Example of the account management page as seen by a gift recipient

Conversely, a purchaser will see payment and transaction details for a gift order, but no fulfillment details will be shown.

Example of the account management page as seen by a gift purchaser



Enabling Gift Purchases

You can turn on the Gift Purchases feature for each individual Storefront where you want to allow gift purchases.  On Storefronts where the feature has not been enabled, customers will not see the Gift Purchase check box at all.

To enable gift purchases:

  1. In the Dashboard, select the Storefronts menu, and select the Web Storefronts or Popup Storefronts tab, depending on the type of Storefront where you want to enable gift purchases.

    Example of the menu with the Storefronts menu selected
    The Web Storefronts tab

  2. Click the SETTINGS command for the Storefront where you want to enable gift purchases.

    Example of the card for a Web Storefront, with the SETTINGS command highlighted

  3. Click the Gift Purchases link on the left-hand side of the page.

    The Gift Purchases page of the Web Storefront's SETTINGS

  4. Select the Yes check box under Enable Gift Purchases, and then click SAVE.
  5. Repeat this process for any other Storefronts where you want to enable gift purchases.


Gift Purchases in the Dashboard

When you view the Events tab or the Orders tab of the Dashboard's Activity menu, you will be able to identify gift purchases by the special blue Gift badge that appears next to them.

Example of the Events tab with a gift purchase transaction appearing at the top of the list


When you drill into the details of an order that was processed as a gift purchase, the Customer section of the detail page will have separate sections for the purchaser's information and the recipient's information.

Example of the Customer section of the order detail page for a gift purchase transaction

You will also notice that in place of the usual EDIT CUSTOMER DETAILS and EDIT ADDRESS commands, EDIT RECEIVER DETAILS and EDIT RECEIVER ADDRESS will appear instead.



Email Templates Used for Gift Purchases

When a customer makes a gift purchase, the Default Order Receipt template is not used to generate the purchaser's receipt email message.  Instead, the Default Gift Purchaser Receipt is used. By default, this message is very similar in look, feel, and content to the Default Order Receipt, but it specifically mentions that the purchase. It includes the recipient's name and explains that all applicable fulfillment details are being provided to the recipient directly. No fulfillment details are displayed in the message by default.

In addition, the recipient will receive an email message with fulfillment details for the purchased products, generated using the Default Gift Recipient Fulfillment template. By default, this message is also similar in look, feel, and content to the Default Order Receipt, but it does not include any price or payment details; only the list of purchased products the applicable fulfillment details.

For illustrated examples of both messages, please see the Customer Experience section of this article, above.

For more information about customer-facing email messages, please see:

Gift Purchases and Store Builder Library

Using Store Builder Library (SBL), there are three methods by which you can pre-populate the recipient information, which will trigger the order to be processed as a gift purchase. If you use the recognizeRecipients() method or the session object, the gift recipient info will be pre-filled in the purchase form, but the purchaser will have the opportunity to overwrite or change it. If you use a secure payload to authenticate the recipient info, it will be stored as part of the order record but not displayed in the purchase form at all.

Store Builder Library Version Note

Important: To pass gift purchase data via the Store Builder Library, you must be using the latest version of SBL--at least version 0.7.7. New versions of SBL are backward compatible, so in order to update, you only need to update the URL targeting the library (e.g. https://d1f8f9xcsvx3ha.cloudfront.net/sbl/0.8.0/fastspring-builder.min.js) in your pages that use SBL.

fastspring.builder.recognizeRecipients()

Takes a JSON "recipient" object consisting of optional recipient info fields as in the following example:


Example of fastspring.builder.recognizeRecipient()
{
	"email": "recipient@fastspring.com",
	"firstName": "firstName",
	"lastName": "lastName",
	"address": {
		"addressLine1": "Address Line 1",
		"city": "City",
		"region": "California",
		"postalCode": "93101",
		"country": "US"
	},
	"memo": "Happy Birthday!"
}


The Session Object

The optional recipient object, illustrated below, can be included in your Store Builder Library session object and then your session can be pushed using fastspring.builder.push(<session>).


Example of the recipient object to be included in an SBL session object
{
	"recipient": {
		"email": "recipient@fastspring.com",
		"firstName": "firstName",
		"lastName": "lastName",
		"address": {
			"addressLine1": "Address Line 1",
			"city": "City",
			"region": "California",
			"postalCode": "93101",
			"country": "US"
		},
		"memo": "Happy Anniversary!"
	}
}


Secure Payloads

If you use server-side encryption to encrypt your Store Builder Library payload, you can pass the optional recipient object as part of the payload. This will authenticate the recipient information, meaning that the recipient information fields will be pre-populated and not shown in the resulting purchase form.


Example of the recipient object in a secure payload
{
	"recipient": {
		"email": "recipient@fastspring.com",
		"firstName": "firstName",
		"lastName": "lastName",
		"address": {
			"addressLine1": "Address Line 1",
			"city": "City",
			"region": "California",
			"postalCode": "93101",
			"country": "US"
		},
		"memo": "Happy Birthday!"
	}
}


Possible Error Responses

The following error messages may be returned when attempting to push the recipient object or calling recognizeRecipients().

Possible Error Responses
400 recipient-and-purchaser-country-must-match                                   // the purchaser's country must match the recipient's country; multiple countries are not supported
400 memo-exceeded-limit                                                          // the optional "memo" field value must not exceed 400 characters

Email Address Note

Although the purchaser and recipient email addresses must differ, this is not validated upon pushing the recipient object or calling recognizeRecipients(). Instead, if you push the same email address for both, customers will see a user-friendly error message in the Storefront explaining the issue, and will be required to change one of the addresses.


Gift Purchases in Webhooks and API Responses

With the release of gift purchases, a new array named recipients has been added to the payload of order-related webhook events such as order.completed, and to API responses when calling GET /orders. This new array is always present, for both gift and non-gift purchases.  In the event that the order in question is a gift purchase, the party identified in the recipient object (inside the recipients array) will be different than the contents of the customer object.

Identifying Gift Purchases

If you need to distinguish between gift and non-gift purchases, consider the following:

Since the gift purchase feature requires that the purchaser's email address must be different than the recipient's, you can compare customer.email with recipients[0].recipient.email. If the two are different, the order is a gift purchase. If they are the same, the order is not a gift purchase.

Example of the recipients array in webhook events and API responses
   "recipients":[  
      {  
         "recipient":{  
            "first":"Leeroy",
            "last":"Jenkins",
            "email":"ne1@all.com",
            "company":null,
            "phone":null,
            "memo":"Merry Christmas, Leeroy!",
            "account":"pY_wvH1IRYm8dnET4FRHxQ",
            "address":{  
               "city":"Lincoln",
               "regionCode":"NE",
               "regionDisplay":"Nebraska",
               "region":"Nebraska",
               "postalCode":"68508",
               "country":"US",
               "display":"Lincoln, Nebraska, 68508, US"
            }
         }
      }
   ]

Webhook Expansion Note

If webhook expansion is enabled, events that include the order object will have the entire account object inside the recipients array, rather than just the recipient's account ID.