Daily/Weekly Offer Tutorial

Daily/Weekly Offer Tutorial

Learn how to restrict offers to a recurring schedule, allowing them to be fulfilled only during specific times of the day and/or days of the week.

Intro

Many businesses see an ebb and flow in the behavior of their customers, with certain periods of very high traffic and others of very low traffic. These swings can occur within a single day, across multiple days in a week, or even month-to-month as seasonal changes take effect. Hatch has developed a suite of tools to help marketers respond to these changes and deliver targeted incentives that help drive additional traffic during what would otherwise be a down time for the business.

Offers represent the marketing incentives that exist within your loyalty program. In this tutorial we'll configure an Offer for a "Happy Hour" promotion designed to drive additional business during the early afternoon, when we otherwise see a noticeable drop in customer activity. The offer will be configured to provide customers with 50% off all coffee products, but should only be available between 1 p.m. and 3 p.m. CST/CDT on Tuesdays and Thursdays.

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 Days of Week Constraint
  4. Add a Time of Day 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 "50% Off All Coffee". Memberships do not see this title. It's only used by our systems.
  • We'll categorize this Offer by setting the category to "afternoon-promos". 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 "50-off-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": "50% Off All Coffee",
      "publish_at": "20xx-06-01",
      "expire_at": "20xx-06-30",
      "category": "afternoon-promos",
      "external_id": "50-off-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": "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": "50-off-coffee",
      "name": "50% Off All Coffee",
      "description": null,
      "category": "afternoon-promos",
      "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 Externally Fulfillable, whose description reads:

Externally Fulfillable

Enable a loyalty program to execute marketing initiatives that are fulfilled or verified outside of Hatch.

This seems to fit with our desire to provide a 50% discount on all coffee purchases, and upon proceeding we can see that the External Fulfillment Earning Mechanism does not require any explicit configuration. Next, we'll review the configuration requirements for the Null Award, since the discount will be applied directly by the point of sale, and can see that this too does not require any explicit configuration.

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": "external_fulfillment",
      "configuration": null,
      "award": {
        "award_type": "null",
        "configuration": {}
      }
    },
    "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 Days of Week Constraint

In its current state, if we were to publish the offer it would result in all coffee purchases made at any time on any day, receiving a 50% discount. In order to restrict the offer to only be applied on Tuesdays and Thursdays, we need to add a constraint to the offer to enforce this restriction.

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

{
  // The set of days on which the offer should be available
  // All values must be: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, or `sunday`
  "available_weekly_on_days": ["monday", "wednesday", "friday"],
  // The time zone to be used to determine the start/end of each day
  // Must be a valid TZ Database time zone name
  "start_of_day_timezone": "America/New_York"
}

For our case, this constraint should limit the offer to purchases made on Tuesdays and Thursdays and needs to evaluate the start and end of these days according to the US central time zone, which is listed as America/Chicago in the TZ Database.

Creating the Days of Week 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": {
      "audience_type": "days_of_week",
      "constraint_type": {
        "available_weekly_on_days": ["tuesday", "thursday"],
        "start_of_day_timezone": "America/Chicago"
      }
    },
    "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.

Step 4: Add a Time of Day Constraint

We've now limited the offer to only be fulfilled for purchases made on Tuesdays and Thursdays, but now we must add an additional constraint to further restrict the offer to only be fulfillable during the targeted time range on those days.

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

{
  // The daily time at which the offer will become available, in the format `HH:MM:SS`
  "available_daily_starting_at_time": "14:00:00",
  // The daily time at which the offer will become unavailable, in the format `HH:MM:SS`
  "available_daily_ending_at_time": "16:00:00",
  // The time zone in which the start and end times for this range are specified
  // Must be a valid TZ Database time zone name
  "timezone": "America/New_York"
}

For our case, this constraint should limit the offer to purchases made between 1 p.m. and 3 p.m. according to the US central time zone, which is listed as America/Chicago in the TZ Database.

Creating the Days of Week 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": {
      "audience_type": "time_of_day",
      "constraint_type": {
        "available_daily_starting_at_time": "13:00:00",
        "available_daily_ending_at_time": "15:00:00",
        "timezone": "America/Chicago"
      }
    },
    "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.

Conclusion

We now have an offer configured that will award a 50% discount on any coffee product purchased between the hours of 1 p.m. and 3 p.m. on Tuesdays and Thursdays during the month of June. The constraints employed in this offer can be used in various combinations to focus the scope of a marketing initiative and in doing so drive a targeted customer behavior at a specific time.

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.