Complex Limits Offer Tutorial

Complex Limits Offer Tutorial

Learn how to translate a marketing initiative with a combination of complex limits in to an Offer in Hatch.

Intro

Whether a marketing initiative is generated internally, e.g., to promote a new feature of your store, or externally via a partnership with a brand, it may be necessary to set a cap on the number of fulfillments allowed. This cap indicates the available inventory, or maximum liability, that is available to fund the offer. To prevent overflowing the available inventory, Hatch provides various Limits which can be configured on the Offer, either individually or in combination.

This tutorial will focus on a brand partnership with the fictional brand Super Soda who wishes to promote their new soda flavors. They have a limited fund to provide for the initiative, meaning there will be limited inventory. We want to prevent overflowing the total available inventory, and also want to prevent depletion of the inventory from occurring ahead of the offer expiration. To accomplish this, we'll configure an Offer with a combination of different Limits. This tutorial will go through the following steps:

  1. Describe the Marketing Initiative
  2. Create the Offer
  3. Add Limits to the Offer
    1. Create a Global Award Count Limit
    2. Create a Global Award Count In Time Limit
    3. Create a Membership Award Count In Time Limit

Steps

Step 1: Describe the Marketing Initiative

A marketing initiative is a complex system with many factors that will need to be translated to Hatch. It is best to start by describing the initiative, the behavior, limits, and other factors that will need to be put in place, before beginning. We've done so here:

The brand Super Soda would like to partner with you to promote their new flavors Chiller Cherry and Lazy Lime within your loyalty program. They would like to fund an initiative where members will receive a $0.50 discount on one of the new flavors when purchased with a can of their original flavor Crazy Cola.

Super Soda is willing to fund $65,000 worth of awards, which we've calculated to be 130,000 discounted cans of Chiller Cherry and Lazy Lime for the initiative. To ensure your supply lasts for the full lifetime of the offer, you would like to award no more than 10,000 cans per week. Further, you'd like to prevent a single membership from monopolizing the promotion, so no more than one can per member, per week will be awarded.

Now that we've described the marketing initiative in its entirety, we may begin configuring it in Hatch.

Step 2: Create the Offer

To support your marketing initiative, we'll create an Offer which represents the discount of a Chiller Cherry or Lazy Lime Super Soda when purchased with a Crazy Cola Super Soda.

Offer Setup

Hatch represents a marketing initiative via the Offer. The Offer serves as a central connection upon which its various components are built. From your initial program set-up, we know that your 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 your loyalty program. We'll configure a few more attributes of the Offer as well:

  • Offer to be published on May 1st, and will end on July 31st. We do this by setting publish_at to "20xx-05-01" and expire_at to "20xx-07-31".
  • The Offer will be referenced internally by setting the name to "Discounted Super Soda". Memberships do not see this title; it's intended for internal-facing usage only.
  • We'll categorize this Offer by setting the category to "in-store-purchase"; this helps your digital signage to display the Offer in the proper locations.
  • If your point of sale system needs a reference to the offer, we'll provide a readable one by setting the external_id to "discounted-super-soda".
  • We'll set the Offer's engagement_type to externally_fulfillable.

Create 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 Super Soda",
      "publish_at": "20xx-05-01",
      "expire_at": "20xx-07-31",
      "category": "in-store-purchase",
      "external_id": "discounted-super-soda",
      "engagement_type": "externally_fulfillable"
    },
    "relationships": {
      "chain": {
        "data": {
          "id": "e6cee754-faf8-46a4-99fd-47ba6c3201bc",
          "type": "chains"
        }
      }
    }
  }
}'

Upon success, this will return a response like this:

{
  "data": {
    "id": "f8d6ebc8-e67e-4d7e-bba5-541d3067fd3f",
    "type": "offers",
    "links": {
      "self": "https://api.hatchloyalty.com/api/v2/offers/f8d6ebc8-e67e-4d7e-bba5-541d3067fd3f"
    },
    "attributes": {
      "chain_id": "e6cee754-faf8-46a4-99fd-47ba6c3201bc",
      "external_id": "discounted-super-soda",
      "name": "Discounted Super Soda",
      "description": "",
      "category": "in-store-purchase",
      "must_activate": false,
      "created_at": "20xx-03-01T00:00:00.000Z",
      "publish_at": "20xx-05-01T00:00:00.000Z",
      "expire_at": "20xx-07-31T00:00:00.000Z",
      "engagement_type": "externally_fulfillable",
      "custom_data": {},
      "discontinued": false,
      "fulfillment_count": 0
    }
  }
}

We'll want to make note that the Offer's id is f8d6ebc8-e67e-4d7e-bba5-541d3067fd3f.

Create the Earning Mechanism

The POS will be responsible for recognizing when both a Crazy Cola and either a Chiller Cherry or Lazy Lime Super Soda are purchased within the same transaction, as well as for applying the discount to the Chiller Cherry or Lazy Lime soda. As such, we will configure this offer with an External Fulfillment Earning Mechanism and Null Award (see the Earning Mechanisms guide for more details).

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": "f8d6ebc8-e67e-4d7e-bba5-541d3067fd3f",
          "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.

Create the Marketing Content

The Marketing Contents 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": "$0.50 off Super Soda!",
      "image_url": "https://our-program.com/assets/crazy-cola.png",
      "short_description": "Buy one Crazy Cola, get $0.50 off a Chiller Cherry or Lazy Lime Super Soda!",
      "long_description": "Buy one Crazy Cola and one Chiller Cherry or Lazy Lime Super Soda together and get $0.50 off!",
      "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": "f8d6ebc8-e67e-4d7e-bba5-541d3067fd3f",
          "type": "offers"
        }
      }
    }
  }
}'

Step 3: Add Limits to the Offer

We will need to add 3 separate Limits to the offer to ensure we don't overflow the available inventory, to ensure the dispersement is spread out over the lifetime of the offer, and to prevent a single member from monopolizing the promotion. We will configure a Global Award Count Limit to account for the total supply of 130,000 cans of Chiller Cherry and Lazy Lime which are available for discounting. We will also configure a Global Award Count In Time Limit to constrain global fulfillment to no more than 10,000 per week, and a Membership Award Count In Time Limit to restrict individual members from receiving more than 1 free can per week.

Step 3.1: Create a Global Award Count Limit

The Global Award Count Limit limits the number of times that the offer can be fulfilled and thus a discount provided on a Cherry Chiller or Lazy Lime soda to all memberships over the lifetime of the offer. To create the limit, we will POST to the create limit api endpoint with the following information:

curl -X POST \
  https://api.hatchloyalty.com/api/v2/limits \
  -H 'accept: application/vnd.api+json' \
  -H 'authorization: Bearer 066a7466' \
  -H 'content-type: application/vnd.api+json' \
  -d '{
  "data": {
    "type": "limits",
    "attributes": {
      "limit_type": "global_award_count",
      "configuration": {
        "limit": 130000
      }
    },
    "relationships": {
      "offer": {
        "data": {
          "id": "f8d6ebc8-e67e-4d7e-bba5-541d3067fd3f",
          "type": "offers"
        }
      }
    }
  }
}'

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

Step 3.2: Create a Global Award Count In Time Limit

The Global Award Count In Time Limit limits the number of times that the offer can be fulfilled and thus a discount provided on a Cherry Chiller or Lazy Lime soda to all memberships per configured time-period over the lifetime of the offer. To support our initiative, we will configure the Limit's time_period with the "week" option, to limit the number of fulfillments to 10,000 per week while the offer is active. To create the limit, we will POST to the create limit api endpoint with the following information:

curl -X POST \
  https://api.hatchloyalty.com/api/v2/limits \
  -H 'accept: application/vnd.api+json' \
  -H 'authorization: Bearer 066a7466' \
  -H 'content-type: application/vnd.api+json' \
  -d '{
  "data": {
    "type": "limits",
    "attributes": {
      "limit_type": "global_award_count_in_time",
      "configuration": {
        "limit": 10000,
        "time_period": "week"
      }
    },
    "relationships": {
      "offer": {
        "data": {
          "id": "f8d6ebc8-e67e-4d7e-bba5-541d3067fd3f",
          "type": "offers"
        }
      }
    }
  }
}'

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

Step 3.3: Create a Membership Award Count In Time Limit

The Membership Award Count In Time Limit limits the number of times that the offer can be fulfilled and thus a discount provided on a Cherry Chiller or Lazy Lime soda for a specific membership per configured time-period over the lifetime of the offer. To support our initiative, we will configure the Limit's time_period with the "week" option, to limit the number of fulfillments to 1 per week per membership while the offer is active. To create the limit, we will POST to the create limit api endpoint with the following information:

curl -X POST \
  https://api.hatchloyalty.com/api/v2/limits \
  -H 'accept: application/vnd.api+json' \
  -H 'authorization: Bearer 066a7466' \
  -H 'content-type: application/vnd.api+json' \
  -d '{
  "data": {
    "type": "limits",
    "attributes": {
      "limit_type": "membership_award_count_in_time",
      "configuration": {
        "limit": 1,
        "time_period": "week"
      }
    },
    "relationships": {
      "offer": {
        "data": {
          "id": "f8d6ebc8-e67e-4d7e-bba5-541d3067fd3f",
          "type": "offers"
        }
      }
    }
  }
}'

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

Conclusion

Through this tutorial we've learned how we can support a marketing initiative with various complex limits to financial exposure. We've created an offer which will award at most 130,000 discounted cans of soda over its lifetime, granting no more than 10,000 per week to all members and no more than 1 per week per member.

Hatch also supports many other types of marketing initiatives; for more information check out our other tutorials as well as our guide to Offers, particularly the list of supported consumer behaviors in the guide to Earning Mechanisms.