Purchase Gated Offer Tutorial

Purchase Gated Offer Tutorial

Learn how to restrict an offer to only members who have purchased a particular quantity of a target product or set of products.

Intro

The Offers configured within your loyalty program are a valuable tool that can be used to drive the behavior of your members. To do this effectively, an offer must target the right members, at the right time, with the right incentive. When this combination is achieved the results can be staggering.

In many cases these first two conditions, the right members and the right time, are defined in terms of the past purchase behavior of a given member. For example, when a customer reaches the point of purchasing 4 cups of coffee over the course of a week, they are starting to establish a daily routine that involves coming into your store and purchasing a cup of coffee. This is the perfect time to incentivize them to fully cement that pattern of behavior into their daily routine and a high value offer can do just that.

A purchase gated offer allows you to define these types of boundaries for the offers in your program. It is configured with a set of Audiences that allow you to define a narrow window of opportunity, hiding this offer from members who do not present a high value opportunity for your business.

The Scenario

In this tutorial we'll consider the case in which a business identifies an inflection point in customers that purchase over 40 gallons of gas each month at their stations. These customers tend to fill up exclusively at their locations and over time discover other in store products that they begin purchasing regularly.

In light of this, they would like to setup an offer to incentivize customers who are purchasing at least 20 gallons of gasoline per month to reach this 40 gallon threshold. They are not interested in customers who purchase less than 20 gallons per month, since they likely won't reach the 40 gallon target. Similarly, they don't want to incentivize customers after they reach 40 gallons since there are significantly diminishing returns beyond that point.

This tutorial will walk through the following steps to configure this offer:

  1. Create the Offer
  2. Create the Product Groups
  3. Choose a Behavior and an Award
  4. Add a Minimum Purchase Audience
  5. Add a Maximum Purchase Audience
  6. Wait for the Offer to be Published

Steps

Step 1: 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:

  • The Offer will 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 "Earn 2x Bonus Points per Gallon of Gas". Memberships do not see this title; it's only used by our systems.
  • We'll categorize this Offer by setting the category to "bonus-points"; 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 "2x-gas-bonus".
  • 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": "Earn 2x Bonus Points per Gallon of Gas",
      "publish_at": "20xx-06-01",
      "expire_at": "20xx-06-30",
      "category": "bonus-points",
      "external_id": "2x-gas-bonus",
      "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": "443f3bdf-627f-40c5-beb9-718c09f5dcbb",
    "type": "offers",
    "links": {
      "self": "https://api.hatchloyalty.com/api/v2/offers/443f3bdf-627f-40c5-beb9-718c09f5dcbb"
    },
    "attributes": {
      "chain_id": "e6cee754-faf8-46a4-99fd-47ba6c3201bc",
      "external_id": "2x-gas-bonus",
      "name": "Earn 2x Bonus Points per Gallon of Gas",
      "description": null,
      "category": "bonus-points",
      "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 443f3bdf-627f-40c5-beb9-718c09f5dcbb.

Step 2: Create the Product Groups

Product Groups are used across the Hatch API to define a group of products that you sell and categorize the line items contained in each transaction according to these groups. Each product group is defined based on a set of SKUs, UPCs, or groups, making it much easier to manage updates to these groups in a consistent manner as your product catalog changes.

In our current scenario, we will use product groups in the following three places:

  • Earning Mechanism: The earning mechanism for our offer needs to only award points based on the number of gallons of gas purchased, ignoring all other line items in the transaction.
  • Minimum Purchase Audience: We will have an audience preventing members who have not yet purchased at least 20 gallons of gas from seeing the offer.
  • Maximum Purchase Audience: We will have an audience preventing members who have already purchased more than 40 gallons of gas from seeing the offer.

Fortunately all three of these cases reference the same set of products (i.e. all types of gas), so we only need to create one product group record and can reference it in each of these configurations.

For this scenario, we'll assume that our pump or POS is assigning a group value of "fuel" to the line items for all types of gas but we could define this product group based on a set of UPCs or SKUs in the same manner.

Creating the Product Group

This information is POSTed to the create product group API endpoint:

curl -X POST \
  https://api.hatchloyalty.com/api/v2/product_groups \
  -H 'accept: application/vnd.api+json' \
  -H 'authorization: Bearer 066a7466' \
  -H 'content-type: application/vnd.api+json' \
  -d $'{
  "data": {
    "type": "product_groups",
    "attributes": {
      "key": "group",
      "name": "fuels",
      "values": [
        "fuel"
      ]
    },
    "relationships": {
      "chain": {
        "data": {
          "type": "chains",
          "id": "e6cee754-faf8-46a4-99fd-47ba6c3201bc"
        }
      }
    }
  }
}'

Upon success, this will return a response like this:

{
  "data": {
    "id": "017c4f8f-7ec0-4d0b-888b-7c3b0deb0638",
    "type": "product_groups",
    "links": {
      "self": "https://api.hatchloyalty.com/api/v2/product_groups/017c4f8f-7ec0-4d0b-888b-7c3b0deb0638"
    },
    "attributes": {
      "key": "group",
      "name": "fuels",
      "values": [
        "fuel"
      ]
    }
  }
}

We'll want to make note that the product group's id is 017c4f8f-7ec0-4d0b-888b-7c3b0deb0638.

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 Transactional, whose description reads:

Transactional

Enable a loyalty program to target transaction-based behaviors that a marketing initiative may wish to engender in their members.

This seems to fit our situation perfectly, so we first examine the information that must be configured for the Total Eligible 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
  "round_counted_products": "half_up" // Must be "raw", "half_up", or "down"
}

Next we'll review the information that must be configured for the Points Per Award:

{
  "points": 2, // An integer representing the number of points that should be granted per counted unit.
  "rounding": "half_up" // Must be "half_up", or "down".
}

For our case, Memberships should receive 2 additional points for every gallon of gas purchased, rounding the resulting points up or down to the nearest whole number.

Creating the Earning Mechanism

This information is POSTed to the create earning mechanism API endpoint:

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": "total_eligible_purchase",
      "configuration": {
        "count_products_by": "quantity",
        "eligible_product_groups": ["017c4f8f-7ec0-4d0b-888b-7c3b0deb0638"],
        "round_counted_products": "raw"
      },
      "award": {
        "award_type": "points_per",
        "configuration": {
          "points": 2,
          "rounding": "half_up"
        }
      }
    },
    "relationships": {
      "offer": {
        "data": {
          "id": "443f3bdf-627f-40c5-beb9-718c09f5dcbb",
          "type": "offers"
        }
      }
    }
  }
}'

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

Step 4: Add a Minimum Purchase Audience

We now have an offer configured that will award 2 additional points per gallon of gas purchased, but in its current state, it will be available to all members starting immediately from when the offer is published. Instead we want to limit this offer to ensure it is not available to any members until they reach a minimum of 20 gallon of gas purchased in the month.

In looking through the Audiences available, we find one titled Purchased At Least which looks like a good fit for our purposes, and its configuration values are the following:

{
  // A list of one or more product group IDs
  "product_groups": ["8177c103-6619-43ae-a982-b0a946be281d", "4b67329b-d15e-4559-b32d-f28f3ea1856d"],
  "threshold": 7.5,
  "exclude_threshold": true
}

For our case, the audience should only include Memberships whose purchases in the fuels product group are at least 20 gallons, including members who have purchased exactly 20.00 gallons of gas.

Creating the Minimum Purchase Audience

This information is POSTed to the create audience API endpoint:

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": "purchased_at_least",
      "configuration": {
        "product_groups": ["017c4f8f-7ec0-4d0b-888b-7c3b0deb0638"],
        "threshold": 20,
        "exclude_threshold": false
      }
    },
    "relationships": {
      "offer": {
        "data": {
          "id": "443f3bdf-627f-40c5-beb9-718c09f5dcbb",
          "type": "offers"
        }
      }
    }
  }
}'

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

Step 5: Add a Maximum Purchase Audience

In the exact same way also want to limit this offer to ensure it is not available to any members that exceed the 40 gallon of gas maximum across their purchases in the month.

Again reviewing the Audiences available, we find one titled Purchased At Most which looks like a good fit for our purposes, and its configuration values are the following:

{
  // A list of one or more product group IDs
  "product_groups": ["8177c103-6619-43ae-a982-b0a946be281d", "4b67329b-d15e-4559-b32d-f28f3ea1856d"],
  "threshold": 15.5,
  "exclude_threshold": true
}

For our case, the audience should only include Memberships whose purchases in the fuels product group are at most 40 gallons, excluding members who have purchased exactly 40.00 gallons of gas.

Creating the Minimum Purchase Audience

This information is POSTed to the create audience API endpoint:

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": "purchased_at_most",
      "configuration": {
        "product_groups": ["017c4f8f-7ec0-4d0b-888b-7c3b0deb0638"],
        "threshold": 40,
        "exclude_threshold": true
      }
    },
    "relationships": {
      "offer": {
        "data": {
          "id": "443f3bdf-627f-40c5-beb9-718c09f5dcbb",
          "type": "offers"
        }
      }
    }
  }
}'

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 6: Wait for the Offer to be Published

Back in step 1 when we setup the offer, we configured it with a publication date of June 1st. As a result, on this date when the offer becomes published it will automatically start tracking the fuel purchases for all memberships in your loyalty program. It's important to note that the audiences we configured for the offer define it's Visibility on a per-membership basis and that all memberships start with an initial quantity of 0, only receiving credit for purchases made after the offers publication.

As a result of the minimum purchase audience we configured, the offer will initially not be visible to any memberships. It's only once a membership has purchased the 20 gallon minimum that they will see the offer and be able to apply it to their transactions. Similarly, once the membership exceeds the 40 gallon threshold for the maximum purchase audience, the offer will again disappear and no longer be applied to their transactions.

Conclusion

Through this tutorial we've developed a purchase gated Offer that provides a 2x point bonus on all gasoline purchases only to members who have purchased at least 20 gallons of gas and no more than 40 gallons of gas this month. This offer will appear in calls to the Membership Offers API with the visible_status attribute controlled by the two audiences configured for the offer.

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.