Vouchered Offer Tutorial

Vouchered Offer Tutorial

Learn how to translate a consumable incentive based on a vouchered-offer in Hatch.

Intro

In addition to the ability to earn points, Hatch provides vouchers as another tool to incentivize a member to engage with marketing initiatives in a loyalty program. A voucher represents access to a material benefit such as a discount on product, an entry in a sweepstakes (see the tutorial on sweepstakes or lottery offers, or admittance to a personalized experience. Vouchers may be purchased in exchange for points (see the purchasable offer tutorial), or earned as the award for engaging with other types of offers (see the voucher-award tutorial).

Regardless of the method used to earn a voucher, a membership may use their vouchers by engaging with a vouchered offer. This tutorial describes how to create such an offer in Hatch, as well as how a point-of-sale may recognize when vouchers are available and indicate to Hatch that one or more have been used. This tutorial will walk through the following steps:

  1. Describe the material benefit
  2. Create the Offer
  3. Choose a method to record use
  4. Write and upload marketing copy
  5. Allow a member to use their vouchers
    1. Query for available vouchers at the point-of-sale
    2. Apply the discount
    3. Record used vouchers

Steps

Step 1: Describe the material benefit

A material benefit may take many forms: an entry in a sweepstakes, or admittance to a personalized event (e.g., a "thank you" outing for highly-engaged members). In this case, the benefit will be a discount on a product purchase.

Members love the coffee at our locations, and its high-margin allows us to provide a large discount in order to encourage members to visit our physical stores. This is a great opportunity for us to up-sell with other products or services when they come in this summer. We'll give members the ability to earn 50% off of cold-brew drinks by engaging with other initiatives in our marketing program.

Elsewhere, we'll set up an offer for coffee-club members to purchase the discount in exchange for points, and we'll also incentivize members that usually only buy gas to come in with a limited number of vouchers.

Now that we've described the material benefit and have an idea for how it will be granted, we may begin configuring it in Hatch.

Step 2: Create the Offer

Hatch represents a marketing initiative via the Offer. The Offer serves as a central connection upon which its various components are built. From our initial program set-up, we know that our loyalty program is identified by the chain_id e6cee754-faf8-46a4-99fd-47ba6c3201bc. We'll use this to make sure that the Offer goes live in our loyalty program. We'll configure a few more attributes of the Offer as well:

  • Offer to be published on May 31st, and will end on September 30th. We do this by setting publish_at to "20xx-05-31" and expire_at to "20xx-09-30".
  • The Offer will be referenced internally by setting the name to "Discounted Coffee". Memberships do not see this title; it's only used by our systems.
  • We'll categorize this Offer by setting the category to "vouchered-incentive"; this helps our digital signage to display the Offer in the proper locations.
  • Since our point of sale will need to reference this offer when it provides the discount, we'll set the external_id to "half-off-coffee".
  • We'll set the Offer's engagement_type to vouchered.

Creating the Offer

This information is POSTed to the create offers api endpoint:

curl -X POST \
  https://api.hatchloyalty.com/api/v2/offers \
  -H 'accept: application/vnd.api+json' \
  -H 'authorization: Bearer 066a7466' \
  -H 'content-type: application/vnd.api+json' \
  -d '{
  "data": {
    "type": "offers",
    "attributes": {
      "name": "Discounted Coffee",
      "publish_at": "20xx-05-31",
      "expire_at": "20xx-09-30",
      "category": "vouchered-incentive",
      "external_id": "half-off-coffee",
      "engagement_type": "vouchered"
    },
    "relationships": {
      "chain": {
        "data": {
          "id": "e6cee754-faf8-46a4-99fd-47ba6c3201bc",
          "type": "chains"
        }
      }
    }
  }
}'

Upon success, this will return a response like this:

{
  "data": {
    "id": "2b591c20-0f25-4e47-bf02-d82d784d983c",
    "type": "offers",
    "links": {
      "self": "https://api.hatchloyalty.com/api/v2/offers/2b591c20-0f25-4e47-bf02-d82d784d983c"
    },
    "attributes": {
      "chain_id": "e6cee754-faf8-46a4-99fd-47ba6c3201bc",
      "external_id": "half-off-coffee",
      "name": "Discounted Coffee",
      "description": "",
      "category": "vouchered-incentive",
      "must_activate": false,
      "created_at": "20xx-03-01T00:00:00.000Z",
      "publish_at": "20xx-05-31T00:00:00.000Z",
      "expire_at": "20xx-09-30T00:00:00.000Z",
      "engagement_type": "vouchered",
      "custom_data": {},
      "discontinued": false,
      "fulfillment_count": 0,
      "voucher_count": 0
    }
  }
}

We'll want to make note that the Offer's id is 2b591c20-0f25-4e47-bf02-d82d784d983c.

Step 3: Choose a method to record use

In Hatch, indicating the use of a voucher by a member is done by "fulfilling" the vouchered offer by engaging with its Earning Mechanism. For sweepstakes entries or event admittance, this might be done by configuring the Loyalty Event Earning Mechanism and sending a special Loyalty Event to indicate when a voucher is used. Since our vouchered offer provides discount at the point of sale, we'll use the External Fulfillment Earning Mechanism.

External Fulfillment

External Fulfillment supports offers for which the program owner (rather than the Hatch platform itself) is responsible for determining whether or not the offer has been fulfilled. This is typically accomplished by a point of sale executing its own basket analysis to determine whether the membership has purchased the appropriate products. An offer configured with External Fulfillment will be considered fulfilled in Hatch when its corresponding id is sent in the fulfilled_offer_ids array attribute of a Transaction.

This seems to fit our situation perfectly, and the External Fulfillment Earning Mechanism requires no additional configuration, except picking the award. Since our point-of-sale is responsible for executing the discount, no further award is necessary and we can make use of the "null" award. In order to create the Earning Mechanism, we'll POST to the create earning mechanism api with the following information:

curl -X POST \
  https://api.hatchloyalty.com/api/v2/earning_mechanisms \
  -H 'accept: application/vnd.api+json' \
  -H 'authorization: Bearer 066a7466' \
  -H 'content-type: application/vnd.api+json' \
  -d '{
  "data": {
    "type": "earning_mechanisms",
    "attributes": {
      "earning_mechanism_type": "external_fulfillment",
      "configuration": {},
      "award": {
        "award_type": "null",
        "configuration": {}
      }
    },
    "relationships": {
      "offer": {
        "data": {
          "id": "2b591c20-0f25-4e47-bf02-d82d784d983c",
          "type": "offers"
        }
      }
    }
  }
}'

We can inspect the response code to ensure that the Earning Mechanism was created successfully (code 201), but we don't need any of the rest of the Earning Mechanism data in order to continue.

Step 4: Write and upload marketing copy

Since member targeting (via Audiences and limitation (via Limits) are configured on the offers that grant vouchers, the last component to create for the vouchered offer is the Marketing Contents that will display consumer-facing copy to the member. Marketing contents are created via the create marketing contents api endpoint, and might consist of the following:

curl -X POST \
  https://api.hatchloyalty.com/api/v2/marketing_contents \
  -H 'accept: application/vnd.api+json' \
  -H 'authorization: Bearer 066a7466' \
  -H 'content-type: application/vnd.api+json' \
  -d '{
  "data": {
    "type": "marketing_contents",
    "attributes": {
      "locale": "en_US",
      "title": "Half-off coffee!",
      "image_url": "https://our-program.com/assets/cold-brew-coffee.png",
      "short_description": "Receive half-off a cold-brew coffee.",
      "long_description": "Stop by for a quick summer refresh with half-off our cold-brew.",
      "terms": "Valid only at participating stores.",
      "terms_url": "https://our-program.com/assets/terms-and-conditions.pdf",
      "disclaimer": "Void where prohibited.",
      "disclaimer_url": "https://our-program.com/assets/general-disclaimer.pdf",
    },
    "relationships": {
      "subject": {
        "data": {
          "id": "2b591c20-0f25-4e47-bf02-d82d784d983c",
          "type": "offers"
        }
      }
    }
  }
}'

The marketing contents, along with the member's available voucher_count may be used when displaying a member's "available inventory" of vouchers that they've collected for later use.

Step 5: Allow a member to use their vouchers

The discount on cold-brew provided by this vouchered offer is understood and fulfilled when a member visits in-store, at the point-of-sale. The following steps show a general outline for how the point-of-sale might query for available vouchers, apply relevant discounts, and indicate to Hatch which vouchers have been used.

Step 5.1: Query for available vouchers at the point-of-sale

In order to retrieve a member's available vouchered offers, the point-of-sale can query Hatch with the visible_status and engagement_type filters. This will return only the offers that are both still available to a member, and that represent material benefits that they might use.

Vouchered Membership-Offers Retrieval - Example Request

curl -X GET \
  https://api.hatchloyalty.com/api/v2/memberships/354067ec-ff43-487b-91ed-9134ac79954d/offers?&filter[visible_status]=visible&filter[engagement_type]=vouchered \
  -H 'accept: application/vnd.api+json' \
  -H 'authorization: Bearer 066a7466'

Vouchered Membership-Offers Retrieval - Example Response

{
  "data": [
    {
      "id": "2b591c20-0f25-4e47-bf02-d82d784d983c",
      "type": "offers",
      "links": {
        "self": "https://api.hatchloyalty.com/api/v2/offers/2b591c20-0f25-4e47-bf02-d82d784d983c"
      },
      "attributes": {
        "chain_id": "e6cee754-faf8-46a4-99fd-47ba6c3201bc",
        "external_id": "half-off-coffee",
        "name": "Discounted Coffee",
        "description": "",
        "category": "vouchered-incentive",
        "must_activate": false,
        "created_at": "20xx-03-01T00:00:00.000Z",
        "publish_at": "20xx-05-31T00:00:00.000Z",
        "expire_at": "20xx-09-30T00:00:00.000Z",
        "engagement_type": "vouchered",
        "custom_data": {},
        "discontinued": false,
        "fulfillment_count": 0,
        "voucher_count": 4,
        "visible_status": "visible"
      }
    },
    // Some additional offers
  ],
  "meta": {
    "record_count": 12
  },
  "links": {
    "first": "https://api.hatchloyalty.com/api/v2/memberships/354067ec-ff43-487b-91ed-9134ac79954d/offers?page%5Bcursor%5D=1&page%5Bsize%5D=20",
    "next": "https://api.hatchloyalty.com/api/v2/memberships/354067ec-ff43-487b-91ed-9134ac79954d/offers?page%5Bcursor%5D=1556140382.000000&page%5Bsize%5D=20"
  }
}

This response indicates that there are twelve available vouchered offers that the member might have vouchers for. The point-of-sale should only consider those whose voucher_count is greater than zero when examining the member's purchase for possible discounts.

Step 5.2: Apply the discount

Since the point-of-sale is responsible for applying discounts to a member's purchase, it must have some configuration that allows it to recognize the purchase of the cold-brew coffee; it may also use the offer's external_id to link its discount-configuration to Hatch's understanding of how many vouchers are available for that member.

In this case, the member has 4 available vouchers for half-off cold-brew. In our example, the member purchases 2 cold-brew coffees, and the point-of-sale provides the half-off discount on each.

Step 5.3: Record used vouchers

The member has purchased 2 cold-brew coffees, received 2 discounts, and as such has used 2 of their available vouchers. Because this vouchered offer is configured with the External Fulfillment Earning Mechanism, the point-of-sale will indicate to Hatch that the offer has been fulfilled twice by recording the offer's id (2b591c20-0f25-4e47-bf02-d82d784d983c) in the resultant Transaction's fulfilled_offer_ids field twice.

Record Transaction - Example Request

curl -X POST \
  https://api.hatchloyalty.com/api/v2/transactions \
  -H 'accept: application/vnd.api+json' \
  -H 'authorization: Bearer 066a7466' \
  -H 'content-type: application/vnd.api+json' \
  -d '{
  "data": {
    "type": "transactions",
    "attributes": {
      "request_id": "6e248bf5-cd9e-4453-8a9a-33bfe6fbef5d",
      "transaction_time_at": "2016-08-02T14:36:12.000Z",
      "money_currency_code": "USD",
      "line_items": [ {
        "sku": "",
        "upc": "000011112222",
        "quantity": 2,
        "money_amount": 4.50,
        "group": "coffee"
      } ],
      "membership_id": "354067ec-ff43-487b-91ed-9134ac79954d",
      "fulfilled_offer_ids": ["2b591c20-0f25-4e47-bf02-d82d784d983c", "2b591c20-0f25-4e47-bf02-d82d784d983c"]
    }
  }
}'

Once the transaction has been processed by Hatch, two of the offer's associated vouchers will be marked as "fulfilled", and a future calls to the Membership-Offer will show 2 available vouchers in this offer's voucher_count.

Conclusion

Through this tutorial we've developed and configured a vouchered offer which represents a material benefit. It will appear in calls to the Membership Offers api. We've also walked through an example from the point-of-sale in retrieving vouchered offers with available vouchers, granting discounts, and recording the corresponding use of those vouchers in Hatch.

Hatch supports several methods for granting vouchers to members. To see how vouchers might be purchased in exchange for points, read the Purchasable Offer Tutorial; to see how vouchers might be granted as an award for engaging with another type of offer, read the Voucher Award Tutorial.

Hatch also supports many other types of marketing initiatives; take a look at our guide to Offers, and particularly the list of supported consumer behaviors in the guide to Earning Mechanisms for more.