Voucher Award Offer Tutorial

Voucher Award Offer Tutorial

Learn how to translate a purchase-based marketing initiative that awards vouchers in to an Offer in Hatch.

Intro

Hatch provides powerful tools to strengthen personal relationships with a loyalty program's Membership base. These relationships lead to a beneficial change in consumer behavior: a Membership is engaged with offerings that they are personally interested in, and a brand has the opportunity to market new or specifically useful products. The foundation of the relationship is influenced by what a Membership chooses to purchase, and many types of marketing initiatives are based on the Transactions that a consumer makes.

Many initiatives award points as a base-line incentive for members to engage with a loyalty program (for example, see the Transactional Offer Tutorial or the Behavioral Offer Tutorial), but some members respond positively to other types of incentives, such as a the award of a material benefit like a discount on products.

This tutorial describes how to use Offers in Hatch to award a material benefit in the form of vouchers for a vouchered offer. Specifically, it will award vouchers for the cold-brew coffee vouchered offer as created in the Vouchered Offer Tutorial. This tutorial will walk through the following steps:

  1. Describe the Marketing Initiative
  2. Create the Offer
  3. Choose a Behavior and an Award
  4. Describe the target Audience
    1. Create a Custom Segment
    2. Apply Custom Segments to Memberships
    3. Apply Custom Segment Audiences
  5. Write and upload marketing copy

Steps

Step 1: Describe the Marketing Initiative

One type of marketing initiative may focus on incentivizing a change to a member's habitual behavior. This tutorial will focus on members of a gas station/convenience store that normally only purchase fuel -- only rarely visiting the store to purchase merchandise or grocery items.

We know that our cold-brew coffee is very popular with members who frequent our store, but there is a sizable set of members who only purchase fuel and rarely enter the store. We've tried incentivizing those members with extra points on in-store purchases in the past, but that hasn't been enough to entice them to come inside.

Instead, we plan to offer a direct benefit that's immediately usable: the next time they fill up their tank, we'll give them two vouchers for half-off cold-brew coffee. We believe this tangible benefit should encourage them to visit in-store, where we then have the opportunity to up-sell with the rest of our great products and services.

We don't necessarily want to give coffee away to members that are already engaged with our merchandise, so we'll identify a custom segment of members that we want to target.

Now that we've described the marketing initiative in its entirety, 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 June 1st, and will end on June 30th. We do this by setting publish_at to "20xx-06-01" and expire_at to "20xx-06-30".
  • The Offer will be referenced internally by setting the name to "Fuel to In-Store: Coffee". Memberships do not see this title; it's only used by our systems.
  • We'll categorize this Offer by setting the category to "fuel-conversion"; this helps our digital signage to display the Offer in the proper locations.
  • If our point of sale system needs a reference to the offer, we'll provide a readable one by setting the external_id to "fuel-to-in-store-coffee".
  • We'll set the Offer's engagement_type to transactional.

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": "Fuel to In-Store: Coffee",
      "publish_at": "20xx-06-01",
      "expire_at": "20xx-06-30",
      "category": "fuel-conversion",
      "external_id": "fuel-to-in-store-coffee",
      "engagement_type": "transactional"
    },
    "relationships": {
      "chain": {
        "data": {
          "id": "e6cee754-faf8-46a4-99fd-47ba6c3201bc",
          "type": "chains"
        }
      }
    }
  }
}'

Upon success, this will return a response like this:

{
  "data": {
    "id": "b1feb6c1-b754-43c3-9f8f-f1d0c6c9e2e7",
    "type": "offers",
    "links": {
      "self": "https://api.hatchloyalty.com/api/v2/offers/b1feb6c1-b754-43c3-9f8f-f1d0c6c9e2e7"
    },
    "attributes": {
      "chain_id": "e6cee754-faf8-46a4-99fd-47ba6c3201bc",
      "external_id": "fuel-to-in-store-coffee",
      "name": "Fuel to In-Store: Coffee",
      "description": "",
      "category": "fuel-conversion",
      "must_activate": false,
      "created_at": "20xx-03-01T00:00:00.000Z",
      "publish_at": "20xx-06-01T00:00:00.000Z",
      "expire_at": "20xx-06-30T00:00:00.000Z",
      "engagement_type": "transactional",
      "custom_data": {},
      "discontinued": false,
      "fulfillment_count": 0
    }
  }
}

We'll want to make note that the Offer's id is b1feb6c1-b754-43c3-9f8f-f1d0c6c9e2e7.

Step 3: Choose a Behavior and an Award

In Hatch, the behavior that a marketing initiative promotes and the award that a Membership receives are collectively called the Earning Mechanism. In perusing the list of available Earning Mechanisms, we find one titled Product Purchase, whose description reads:

Product Purchase

Product Purchase supports Offers that influence a consumer to buy a particular product, often due to a brand partnership that the marketing program has entered in to.

This seems to fit our situation perfectly, so we first examine the information that must be configured for the Product Purchase Earning Mechanism:

{
    "count_products_by": "quantity", // Must be `quantity` or `money_amount`
    "eligible_product_groups": ["b4cafccc-a523-4c84-bbec-d187b14faafa"], // An array of previously-created [Product Groups](/guides/product-groups)
    "purchase_threshold": 1 // Indicates the unit quantity or dollar-spend required to trigger the award
}

For our case, Memberships should purchase 5 of gallons of gas, so count_products_by will be quantity and purchase_threshold will be 5. We've previously run promotions on fuel and know that a Product Group exists to identify fuel line items with the id 6510f844-80c8-46c1-bf08-6bcaa01565c1.

Creating the Earning Mechanism

We've previously configured a vouchered offer to represent the discount on cold-brew coffee (see the Vouchered Offer Tutorial for more), and know that it exists in our system with the id 2b591c20-0f25-4e47-bf02-d82d784d983c. We know that we want to award 2 vouchers, and want to create an immediate incentive for the member to use them -- so they'll be set to expire 7 days after they're awarded. Putting this information together, 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": "product_purchase",
      "configuration": {
        "count_products_by": "quantity",
        "eligible_product_groups": ["6510f844-80c8-46c1-bf08-6bcaa01565c1"],
        "purchase_threshold": 5
      },
      "award": {
        "award_type": "vouchers",
        "configuration": {
          "voucher_count": 2,
          "voucher_expiration_days": 7,
          "vouchered_offer_id": "2b591c20-0f25-4e47-bf02-d82d784d983c"
        }
      }
    },
    "relationships": {
      "offer": {
        "data": {
          "id": "b1feb6c1-b754-43c3-9f8f-f1d0c6c9e2e7",
          "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: Describe the target Audience

This Offer should be shown to members that don't often visit in-store, but do buy fuel. It looks like Hatch does not directly support our targeting requirements, but it does support the ability to create Custom Segments which allow our own business intelligence systems to arbitrarily segment Memberships. If we have a segment only-fuel, we should be able to make use of the following Audience to support our targeting goals:

In All Segments

Used to ensure that the Membership belongs to all of the specified segments.

Step 4.1: Create a Custom Segment

Before continuing with the Offer setup, we'll need to make sure that our segment is represented in Hatch. We can do so by calling the create segments api.

We'll send a POST request to create the fuel-only segment:

curl -X POST \
  https://api.hatchloyalty.com/api/v2/segments \
  -H 'accept: application/vnd.api+json' \
  -H 'authorization: Bearer 066a7466' \
  -H 'content-type: application/vnd.api+json' \
  -d '{
  "data": {
    "type": "segments",
    "attributes": {
      "short_code": "fuel-only",
      "name": "Fuel Only",
      "description": "Memberships often only purchase fuel.",
    },
    "relationships": {
      "chain": {
        "data": {
          "id": "e6cee754-faf8-46a4-99fd-47ba6c3201bc",
          "type": "chains"
        }
      }
    }
  }
}'

The API will respond with

{
  "data": {
    "id": "2620926e-f042-44cf-a5fc-5613d38c9295",
    "type": "segments",
    "links": {
      "self": "https://api.hatchloyalty.com/api/v2/segments/2620926e-f042-44cf-a5fc-5613d38c9295"
    },
    "attributes": {
      "short_code": "fuel-only",
      "name": "Fuel Only",
      "description": "Memberships often only purchase fuel.",
     },
    "relationships": {
      "chain": {
        "links": {
          "self": "https://api.hatchloyalty.com/api/v2/segments/2620926e-f042-44cf-a5fc-5613d38c9295/relationships/chain",
          "related": "https://api.hatchloyalty.com/api/v2/segments/2620926e-f042-44cf-a5fc-5613d38c9295/chain"
        }
      },
    }
  }
}

Parsing the response will yield a Segment id of 2620926e-f042-44cf-a5fc-5613d38c9295 for "fuel-only". We'll need this id when applying the segment to members, as well as the audience for our offer.

Step 4.2: Apply Custom Segments to Memberships

We have three Memberships that we'll use to initially test this offer; their ids are bf54a204-3463-4c1a-beba-5c9caa1251d2, ed42c133-f6eb-4f02-85c2-0925bbab5df3, and 6ba763c4-8c8f-4b8b-a512-be72c82e6e06. We'll place all three in to the segment and ensure that each of them are able to engage with this offer.

We'll add the Memberships to the fuel-only segment via the add members to a segment api as follows.

curl -X POST \
  https://api.hatchloyalty.com/api/v2/segments/2620926e-f042-44cf-a5fc-5613d38c9295/relationships/memberships \
  -H 'accept: application/vnd.api+json' \
  -H 'authorization: Bearer 066a7466' \
  -H 'content-type: application/vnd.api+json' \
  -d '{
  "data": [
    { "id": "bf54a204-3463-4c1a-beba-5c9caa1251d2", type: "memberships" },
    { "id": "ed42c133-f6eb-4f02-85c2-0925bbab5df3", type: "memberships" },
    { "id": "6ba763c4-8c8f-4b8b-a512-be72c82e6e06", type: "memberships" },
  }]
}'

Step 4.3: Apply Custom Segment Audiences

Now that the Custom Segment exists and has been applied to a few Memberships, we can continue setting up the Offer. We want to display the Offer only to those Memberships in the fuel-only segment, so we'll use the "In All Segments" Audience to enforce the targeting. This Audience can be configured by POSTing to the create audience api, associating it to our gas offer by the id b1feb6c1-b754-43c3-9f8f-f1d0c6c9e2e7.

curl -X POST \
  https://api.hatchloyalty.com/api/v2/audiences \
  -H 'accept: application/vnd.api+json' \
  -H 'authorization: Bearer 066a7466' \
  -H 'content-type: application/vnd.api+json' \
  -d '{
  "data": {
    "type": "audiences",
    "attributes": {
      "audience_type": "in_all_segments",
      "configuration": {
        "segments": ["2620926e-f042-44cf-a5fc-5613d38c9295"]
      }
    },
    "relationships": {
      "offer": {
        "data": {
          "id": "b1feb6c1-b754-43c3-9f8f-f1d0c6c9e2e7",
          "type": "offers"
        }
      }
    }
  }
}'

The enforcement of this Audience is reflected in the Offer's visible status attribute. We can inspect the response code to ensure that the Audience was created successfully (code 201), but we don't need any of the rest of the Audience data in order to continue.

Step 5: Write and upload marketing copy

Finally, we configure 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 cold-brew coffee with fuel purchase.",
      "image_url": "https://our-program.com/assets/cold-brew-coffee.png",
      "short_description": "Fill up with at least 5 gallons of gas and earn 2 vouchers for half-off cold-brew.",
      "long_description": "When the weather is hot outside, refresh in our store after filling up your vehicle with half-off of our delicious cold-brew coffee. Hurry on in, the discount expires 7 days after your fuel purchase.",
      "terms_url": "https://our-program.com/assets/terms-and-conditions.pdf",
      "disclaimer": "Valid while supplies last. Void where prohibited.",
      "disclaimer_url": "https://our-program.com/assets/general-disclaimer.pdf",
    },
    "relationships": {
      "subject": {
        "data": {
          "id": "b1feb6c1-b754-43c3-9f8f-f1d0c6c9e2e7",
          "type": "offers"
        }
      }
    }
  }
}'

Conclusion

Through this tutorial we've developed an alternative incentive based on a material benefit in order to incentivize certain members to visit our in-store locations more often. This offer will appear in calls to the Membership Offers api. In order to fulfill the Offer, the Membership's Transactions must be forwarded to Hatch. See more in the Transaction Processing Tutorial.

To see how Hatch supports Offers that allow vouchers to be purchased in exchange for points, read the Purchasable Offer Tutorial; to see how a vouchered offer may be configured to provide a material benefit, read the Vouchered Offer 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.