Store Location Restricted Offer Tutorial

Store Location Restricted Offer Tutorial

Learn how to restrict offers to specified store locations, allowing them to be fulfilled only at those locations.

Intro

Many businesses see variability in performance across store locations. For example, one store location may see a significantly higher volume of fuel sales than another location. Hatch has developed a suite of tools to help marketers deliver targeted incentives that help drive traffic to desired locations.

Offers represent the marketing incentives that exist within your loyalty program. In this tutorial we'll configure an Offer for a fuel promotion designed to drive additional business to locations which have been identified by the business team as "low fuel sales" locations. The offer will be configured to provide customers with an additional 2 points per gallon on fuel purchases, but should only be available at specific store locations (i.e. those "low fuel sales" locations).

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

  1. Create the Offer
  2. Choose a Behavior and an Award
  3. Add a Store Location Constraint

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 Additional 2 Pts Per Gallon At Select Locations". Memberships do not see this title. It's only used by our systems.
  • We'll categorize this Offer by setting the category to "addl-fuel-pts". 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 "addl-fuel-pts-selected-locs".
  • 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 Additional 2 Pts Per Gallon At Select Locations",
      "publish_at": "20xx-06-01",
      "expire_at": "20xx-06-30",
      "category": "addl-fuel-pts",
      "external_id": "addl-fuel-pts-selected-locs",
      "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": "addl-fuel-pts-selected-locs",
      "name": "Earn Additional 2 Pts Per Gallon At Select Locations",
      "description": null,
      "category": "addl-fuel-pts",
      "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: 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 Total Eligible Purchase, whose description reads:

Total Eligible Purchase

Sometimes called a "Base Earn", Total Eligible Purchase supports offers that help keep a loyalty program top-of-mind for memberships by ensuring that they earn some amount of points each time they transact.

This seems to fit with our desire to award 2 points per gallon on fuel purchases, 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": "down" // Must be `half_up`, `raw`, or `down`
}

For our case, Memberships should receive points for every gallon of gas purchased, so count_products_by will be quantity. Memberships should only receive points for each FULL gallon purchased, so round_counted_products will be down. We've previously run promotions on fuel and know that a Product Group exists to identify fuel line items with the id b4cafccc-a523-4c84-bbec-d187b14faafa.

Creating the Earning Mechanism

We know that we want to award 2 points for every gallon, which aligns with the Points Per Award type. Putting this information together, we'll POST 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": ["b4cafccc-a523-4c84-bbec-d187b14faafa"],
        "round_counted_products": "down"
      },
      "award": {
        "award_type": "points_per",
        "configuration": {
          "points": 2,
          "rounding": "down"
        }
      }
    },
    "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 3: Add a Store Location Constraint

In its current state, if we were to publish the offer it would result in 2 points per gallon on all fuel purchases, regardless of the store location at which that transaction originated. In order to restrict the offer to only be applied to transactions originating from the "low fuel sales" stores, we need to add a constraint to the offer to enforce this restriction.

In looking through the Constraints available, we find one titled Store Location which looks like a good fit for our purposes, and its configuration values are the following:

{
  // An array of previously-created Locations
  "location_ids": ["8ae472a6-455f-464d-8755-e254ac3393eb", "e294a972-cb31-4cd3-92bd-19a627b842f0"],
  // Method by which the configured location(s) should be evaluated
  // Must be either `include` or `exclude`
  "evaluation_method": "include"
}

For our case, this constraint should limit the offer to transactions ONLY at our "low fuel sales" stores, so we will use the evaluation_method of include. Our business team has identified the "low fuel sales" store locations as being those with the IDs 8ae472a6-455f-464d-8755-e254ac3393eb and e294a972-cb31-4cd3-92bd-19a627b842f0, so we will include these IDs in the location_ids array. Note that these IDs must correspond to previously-created Location records.

Creating the Store Location Constraint

This information is POSTed to the create constraint 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": "constraints",
    "attributes": {
      "constraint_type": "store_location",
      "constraint_type": {
        "location_ids": ["8ae472a6-455f-464d-8755-e254ac3393eb", "e294a972-cb31-4cd3-92bd-19a627b842f0"],
        "evaluation_method": "include"
      }
    },
    "relationships": {
      "offer": {
        "data": {
          "id": "443f3bdf-627f-40c5-beb9-718c09f5dcbb",
          "type": "offers"
        }
      }
    }
  }
}'

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

A Note on Transactions

In order for this constraint to be satisfied and thus the offer be fulfilled for an incoming transaction, the transaction must include an appropriate location_id. If no location_id is set on the transaction, the condition will never be satisfied (even when configured to exclude only specified locations) and thus the offer cannot be fulfilled.

Conclusion

We now have an offer configured that will award 2 points per gallon on fuel purchases at our specified "low fuel sales" store locations. The constraint employed in this offer can be used to restrict offer fulfillment either inclusively to or exclusive of specified store locations and in doing so drive targeted customer behavior at specific locations.

Hatch supports many other types of marketing initiatives. Take a look at our guide to Offers, and particularly the list of supported Constraints that can be used to tailor and target their impact.