Purchasable Offer Tutorial

Purchasable Offer Tutorial

Learn how to allow members to exchange their points in exchange for vouchers via a Purchasable Offer in Hatch.

Intro

Points are the primary currency for incentivizing members to engage with a loyalty program in Hatch, and allow members control over what material benefits they would like to receive in exchange for the points that they earn. A purchasable Offer enables these exchanges, while also allowing further customization and member-targeting via Audiences and Limits. A member interacts with a purchasable Offer by spending points on an Offer Purchase.

An Offer Purchase is conceptually similar to the creation of a Redemption for a Reward, but allows the purchasable Offer to make use of the Audience and Limit components in order to further target the members that may execute a purchase. In the Vochered Offer Tutorial, a vouchered Offer was created to provide a half-off discount on cold-brew coffee. Such vouchers may be granted as the award for a behavior (see the Vouchered Award Tutorial), but may also be purchased as mentioned above.

This tutorial makes use of the cold-brew coffee vouchered Offer, and describes how a purchasable Offer may be configured in order to allow members to buy a limited number of half-off cold-brew coffee vouchers in exchange for points. 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. Add Limits to financial exposure
  5. Write and upload marketing copy
  6. Purchasing vouchers
    1. Displaying purchasable offers
    2. Allowing a member to purchase vouchers

Steps

Step 1: Describe the Marketing Initiative

A purchasable Offer represents a marketing initiative that focuses on providing a material benefit that members may want in exchange for the points that they earn by engaging with a loyalty program. It's also an opportunity to drive customers toward products that they might not normally purchase, or to advertise new products.

We're launching our new cold-brew coffee line this summer and would like to give members the chance to try it at a discount. Offering half-off cold-brew vouchers in exchange for points is a good way to get members to both engage with us in-store, and use up some of the points they've been saving -- but we want to make sure they're converting to full-price customers if they like the product, so we'll limit the purchase to two per member.

We could further target this promotion to certain members via an Audience, but instead we'll let it run without specific targeting at first and see how members engage.

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 "Purchase half-off cold-brew". Memberships do not see this title; it's only used by our systems.
  • We'll categorize this Offer by setting the category to "points-purchase"; 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 "half-off-cold-brew-purchase".
  • We'll set the Offer's engagement_type to purchasable.

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": "Purchase half-off cold-brew",
      "publish_at": "20xx-06-01",
      "expire_at": "20xx-06-30",
      "category": "points-purchase",
      "external_id": "half-off-cold-brew-purchase",
      "engagement_type": "purchasable"
    },
    "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": "half-off-cold-brew-purchase",
      "name": "Purchase half-off cold-brew",
      "description": "",
      "category": "points-purchase",
      "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": "purchasable",
      "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 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 Point Spend, whose description reads:

Point Spend

Point Spend supports purchasable Offers which allow a member to exchange points for vouchers tied to a vouchered Offer.

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

{
    "point_cost": 50 // Indicates the number of points that a member must spend in order to purchase this offer
}

For our case, Memberships should spend 100 points in exchange for 1 half-off cold-brew voucher.

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 1 voucher; we won't expire the vouchers directly (although they will still expire when the cold-brew vouchered Offer expires.) 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": "point_spend",
      "configuration": {
        "point_cost": 100
      },
      "award": {
        "award_type": "vouchers",
        "configuration": {
          "voucher_count": 1,
          "voucher_expiration_days": null,
          "vouchered_offer_id": "2b591c20-0f25-4e47-bf02-d82d784d983c"
        }
      }
    },
    "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 (code 201), but we don't need any of the rest of the Earning Mechanism data in order to continue.

Step 4: Add Limits to financial exposure

In order to convert members to full-cost purchases of the cold-brew, we'll limit the number of voucher purchases to two per member. Since each purchase only results in one voucher, that means that the per-member limit will be 2. In this case, we don't necessarily want to limit the total number of members who may purchase this offer, so we'll choose not to configure a global limit.

Even though this is a purchasable Offer, Hatch still considers the voucher grant to be an award for the Point Spend earning mechanism. In glancing through the available Limits, we find the following:

Membership Award Count

Used to Limit the number of times that an Earning Mechanism's award may be given to a given membership; often called the "fulfillment" of the offer. This limiter may work in conjunction with either point- or voucher-based awards.

This should work for our offer, and can be created by POSTing to the create limit api:

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",
      "configuration": {
        "limit": 2
      }
    },
    "relationships": {
      "offer": {
        "data": {
          "id": "443f3bdf-627f-40c5-beb9-718c09f5dcbb",
          "type": "offers"
        }
      }
    }
  }
}'

The status of available fulfillments is reflected by the visible_status attribute of the Offer. Current fulfillment count can be seen in the fulfillment_count attribute. 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 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": "Spend 100 points and receive half-off cold-brew coffee.",
      "image_url": "https://our-program.com/assets/cold-brew-coffee.png",
      "short_description": "Try our new cold-brew coffee, half-off!",
      "long_description": "Spend 100 points and receive a voucher for half-off our new summer favorite: cold-brew coffee. Limit 2 per member.",
      "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": "443f3bdf-627f-40c5-beb9-718c09f5dcbb",
          "type": "offers"
        }
      }
    }
  }
}'

Step 6: Purchasing vouchers

Enabling a member to purchase vouchers for a vouchered Offer requires two steps: a mobile application or website that displays purchasable Offer's that are available to a member; and the creation of an Offer Purchase when a member has selected the offer they'd like to spend their points on.

Step 6.1: Displaying purchasable offers

In order to retrieve a member's available purchasable Offers, the client application can query Hatch with the visible_status and engagement_type filters. This will return only the offers that are both still available to a member, and that represent purchases that they might make. Additionally, the Marketing Contents may be side-loaded in order to facilitate the display of marketing copy to the member.

Purchasable Membership-Offers Retrieval - Example Request

curl -X GET \
  https://api.hatchloyalty.com/api/v2/memberships/354067ec-ff43-487b-91ed-9134ac79954d/offers? \
  &filter[visible_status]=visible&filter[engagement_type]=purchasable \
  &include=marketing_contents \
  -H 'accept: application/vnd.api+json' \
  -H 'authorization: Bearer 066a7466'

Purchasable Membership-Offers Retrieval - Example Response

{
  "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": "half-off-cold-brew-purchase",
        "name": "Purchase half-off cold-brew",
        "description": "",
        "category": "points-purchase",
        "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": "purchasable",
        "custom_data": {},
        "discontinued": false,
        "fulfillment_count": 0
      },
      "relationships": {
        "marketing_contents": {
          "links": {
            "self": "https://api.hatchloyalty.com/api/v2/offers/443f3bdf-627f-40c5-beb9-718c09f5dcbb/relationships/marketing_contents",
            "related": "https://api.hatchloyalty.com/api/v2/offers/443f3bdf-627f-40c5-beb9-718c09f5dcbb/marketing_contents"
          },
          "data": [
            {
              "type": "marketing_contents",
              "id": "5205bed5-1a4b-425c-90cc-0cea82d0bbaa"
            }
          ]
        }
      }
    },
    // Some additional offers
  ],
  "included": [
    {
      "id": "5205bed5-1a4b-425c-90cc-0cea82d0bbaa",
      "type": "marketing_contents",
      "links": {
        "self": "https://api.hatchloyalty.com/api/v2/marketing_contents/5205bed5-1a4b-425c-90cc-0cea82d0bbaa"
      },
      "attributes": {
        "created_at": "2019-04-02T17:55:29.514Z",
        "locale": "en_US",
        "title": "Spend 100 points and receive half-off cold-brew coffee.",
        "image_url": "https://our-program.com/assets/cold-brew-coffee.png",
        "short_description": "Try our new cold-brew coffee, half-off!",
        "long_description": "Spend 100 points and receive a voucher for half-off our new summer favorite: cold-brew coffee. Limit 2 per member.",
        "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": {
          "links": {
            "self": "https://api.hatchloyalty.com/api/v2/marketing_contents/5205bed5-1a4b-425c-90cc-0cea82d0bbaa/relationships/subject",
            "related": "https://api.hatchloyalty.com/api/v2/marketing_contents/5205bed5-1a4b-425c-90cc-0cea82d0bbaa/subject"
          }
        }
      }
    },
  ],
  "meta": {
    "record_count": 12
  },
  "links": {
    "first": "https://api.hatchloyalty.com/api/v2/memberships/354067ec-ff43-487b-91ed-9134ac79954d/offers?page%5Bcursor%5D=1&page%5Bsize%5D=20",
    "next": "https://api.hatchloyalty.com/api/v2/memberships/354067ec-ff43-487b-91ed-9134ac79954d/offers?page%5Bcursor%5D=1556140382.000000&page%5Bsize%5D=20"
  }
}

By matching the offer's marketing content (from the offer's relationships field) to the included marketing contents by id, the client application can display locale-specific marketing copy, disclaimers, and images to the member.

Step 6.2: Allowing a member to purchase vouchers

Once a member has selected which offer they'd like to purchase, a POST request to the Offer Purchase endpoint may be made with the member and offer ids, as well as as the purchase_count they would like to buy.

curl -X POST \
  https://api.hatchloyalty.com/api/v2/memberships/354067ec-ff43-487b-91ed-9134ac79954d/offers/443f3bdf-627f-40c5-beb9-718c09f5dcbb/offer_purchases \
  -H 'accept: application/vnd.api+json' \
  -H 'authorization: Bearer 066a7466' \
  -H 'content-type: application/vnd.api+json' \
  -d '{
  "data": {
    "type": "offer_purchases",
    "attributes": {
      "purchase_count": 1
    }
  }
}'

This will return a response that indicates the successfully executed purchases:

{
  "data": [
    {
      "links": {
        "self": "https://api.hatchloyalty.com/api/v2/memberships/354067ec-ff43-487b-91ed-9134ac79954d/offers/443f3bdf-627f-40c5-beb9-718c09f5dcbb"
      },
      "attributes": {
        "created_at": "2019-06-18T15:50:13.507Z",
        "discontinued": false,
        "point_cost": 100,
        "returnable": true,
        "purchasable_offer_id": "354067ec-ff43-487b-91ed-9134ac79954d",
        "vouchered_offer_id": "2b591c20-0f25-4e47-bf02-d82d784d983c"
      },
      "relationships": {
        "purchased_with": {
          "links": {
            "self": "https://api.hatchloyalty.com/api/v2/offer_purchases/354067ec-ff43-487b-91ed-9134ac79954d/relationships/purchased_with",
            "related": "https://api.hatchloyalty.com/api/v2/offer_purchases/354067ec-ff43-487b-91ed-9134ac79954d/purchased_with"
          }
        },
        "voucher_grant_for": {
          "links": {
            "self": "https://api.hatchloyalty.com/api/v2/offer_purchases/354067ec-ff43-487b-91ed-9134ac79954d/relationships/voucher_grant_for",
            "related": "https://api.hatchloyalty.com/api/v2/offer_purchases/354067ec-ff43-487b-91ed-9134ac79954d/voucher_grant_for"
          }
        }
      }
    }
  ],
  "meta": {
    "record_count": 1
  }
}

Once the purchase has been made successfully, further calls to the Membership Offers api will indicate the new number of available vouchers for the vouchered Offer in its voucher_count.

Conclusion

Through this tutorial we've developed a purchasable Offer that allows a member to spend points in order to purchase vouchers for half-off cold-brew. This offer will appear in calls to the Membership Offers api. We've also learned the steps required to display these offers, as well as the method used to execute a purchase.

To see how Hatch supports Offers that allow vouchers earned by engaging with another type of offer, read the Voucher Award 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.