Sweepstakes/Lottery Offer Tutorial

Sweepstakes/Lottery Offer Tutorial

Learn how to setup a complex Sweepstakes/Lottery marketing initiative in Hatch.

Intro

Hatch provides powerful tools to strengthen personal relationships with a loyalty program's membership base. At times it may be desirable to incentivize members' engagement with the loyalty program by running a sweepstakes or lottery promotion (hereafter simply referred to as a sweepstakes), whereby a members' engagement is rewarded with an entry for a chance to win some material benefit. Such a marketing initiative is accomplished in Hatch by utilizing the vouchered offer, representing the sweepstakes' prize, and a separate voucher-awarding offer (see the voucher-award tutorial), with which members will engage in order to gain entry into the sweepstakes. The voucher-awarding offer can utilize further customization and member-targeting via Audiences and Limits.

In this tutorial, we will consider a sweepstakes marketing initiative whereby members can gain entry to win a prize by purchasing a specified amount of a product. Thus, we will configure a vouchered offer, which will represent the sweepstakes prize, and a transactional offer, which will award vouchers for the vouchered offer, with each voucher representing a single entry into the sweepstakes.

  1. Describe the Marketing Initiative
  2. The Vouchered Offer
    1. Create the Vouchered Offer
    2. Create the Vouchered Offer Earning Mechanism
    3. Create the Vouchered Offer Marketing Contents
    4. Create the Vouchered Offer Constraint
    5. Display the Vouchered Offer to Entrants
  3. The Transactional Offer
    1. Create the Transactional Offer
    2. Create the Transactional Offer Earning Mechanism
    3. Create the Transactional Offer Marketing Contents
    4. Create the Transactional Offer Per-Membership Limit
  4. Checking Progress and Selecting the Sweepstakes Winner
    1. Status Checks During the Sweepstakes
    2. Retrieve the Pool of Entrants
    3. Fulfill the Vouchered Offer for the Sweepstakes Winner

Steps

Step 1: Describe the Marketing Initiative

A marketing initiative may be generated internally, e.g., to promote a new feature of your store, or externally via a partnership with a Brand. This tutorial will focus on such a partnership with the fictional brand Fisherman Joe's™ Fish Sticks. Fisherman Joe's™ would like to promote their newest flavors of Joe's Original Beer Battered Fish Sticks by offering high-volume purchasers of these products a chance to win the annual Fishing Excursion with the real Fisherman Joe.

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

Fisherman Joe's™ would like to promote their newest flavors of Joe's Original Beer Battered Fish Sticks within your loyalty program - Cajun (identified by UPC 000011112222), Buffalo (identified by UPC 000033334444), and BBQ (identified by UPC 000055556666). To incentivize members to purchase the new flavors, the loyalty program will run a sweepstakes and send one lucky winner on the annual Fishing Excursion with the real Fisherman Joe. Members can gain entry into the sweepstakes by spending at least $30 on the new fish sticks flavors in a single transaction.

We'll set up two new Offers within your loyalty program to accomplish this initiative: a transactional Offer and a vouchered Offer. The vouchered Offer will represent the prize, e.g., the Fishing Excursion with the real Fisherman Joe, and will be tied to vouchers awarded by your transactional Offer. The transactional Offer will award 1 voucher for your vouchered Offer when a member buys $30 of Cajun, Buffalo or BBQ Joe's Original Beer Battered Fish Sticks in one transaction. Each voucher awarded by the transactional Offer will represent one entry into the Fishing Excursion with the real Fisherman Joe sweepstakes.

Fisherman Joe's™ would like to ensure that no single member monopolizes the promotion, so that every entrant has a fair chance at winning. We'll allow each member up to 2 entries into the sweepstakes by adding a Membership Award Count Limit of 2 on the transactional Offer.

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

Step 2: The Vouchered Offer

The vouchered Offer will represent the prize granted to the selected winner of the sweepstakes, e.g., the Fishing Excursion with the real Fisherman Joe. We will need to create the Offer, as well as it's Earning Mechanism, Marketing Contents, and Constraint. Even though this offer will only be fulfilled by one member, e.g., the selected winner of the sweepstakes, we would like to display the offer in your application to all members who have gained entry into the sweepstakes. Further, we'd like to indicate to these members the number of entries they've gained.

Step 2.1: Create the Vouchered Offer

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 April 1st, the starting day of the sweepstakes, and and expired on June 2nd, the day after the sweepstakes ends. We do this by setting publish_at to "20xx-06-01" and expire_at to "20xx-06-02". Note that we expire the vouchered Offer the day following the expiration of the transactional Offer (e.g., the last day for sweepstakes entries), as we must fulfill the vouchered Offer for the winner before the vouchered Offer expires and after the sweepstakes entry period has ended. You may choose to push the expire date of the vouchered Offer further out if you expect to take longer than a day in selecting the winner.
  • The Offer will be referenced internally by setting the name to "Fishing Excursion with the real Fisherman Joe". Members do not see this title; it's intended for internal-facing usage only.
  • We'll categorize this Offer by setting the category to "sweepstakes"; this helps your digital signage to display the Offer in the proper locations.
  • If your mobile application needs a reference to the Offer, we'll provide a readable one by setting the external_id to "fishing-excursion-fisherman-joes".
  • We'll set the Offer's engagement_type to vouchered.

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": "Fishing Excursion with the real Fisherman Joe",
      "publish_at": "20xx-04-01",
      "expire_at": "20xx-06-02",
      "category": "sweepstakes",
      "external_id": "fishing-excursion-fisherman-joes",
      "engagement_type": "vouchered"
    },
    "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": "fishing-excursion-fisherman-joes",
      "name": "Fishing Excursion with the real Fisherman Joe",
      "description": "",
      "category": "sweepstakes",
      "must_activate": false,
      "created_at": "20xx-03-01T00:00:00.000Z",
      "publish_at": "20xx-04-01T00:00:00.000Z",
      "expire_at": "20xx-06-02T00:00:00.000Z",
      "engagement_type": "vouchered",
      "custom_data": {},
      "discontinued": false,
      "fulfillment_count": 0,
      "voucher_count": 0
    }
  }
}

We'll want to make note that the Offer's id is 443f3bdf-627f-40c5-beb9-718c09f5dcbb.

Step 2.2: Create the Vouchered Offer Earning Mechanism

Given that the vouchered Offer in this sweepstakes promotion represents an external prize which will be granted to the winner of the sweepstakes, e.g., the Fishing Excursion with the real Fisherman Joe, and does not award anything within Hatch, the vouchered Offer should be configured with a Loyalty Event Earning Mechanism and a Null Award (see the Earning Mechanisms guide for more details). Once the promotion has ended and we've selected the winner of the sweepstakes, we will fulfill the vouchered Offer for the winning member by sending a Loyalty Event with the matching event_type.

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": "loyalty_event",
      "configuration": {
        "event_type": "fisherman-joes-excursion-winner"
      },
      "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 (code 201), but we don't need any of the rest of the Earning Mechanism data in order to continue.

Step 2.3: Create the Vouchered Offer Marketing Contents

The Marketing Contents will display consumer-facing copy to the member. As we've chosen to display this Offer to all entrants of the sweepstakes as a confirmation of their having been entered, we will tailor the message accordingly. We'll want to be clear in the messaging that this Offer is displayed to them as a result of them having been entered into the sweepstakes, and that it's visibility represents a notice of such entry, not an indication of having won the sweepstakes.

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": "You have been entered to win a Fishing Excursion with the real Fisherman Joe!",
      "image_url": "https://our-program.com/assets/fishing-excursion-with-joe.png",
      "short_description": "You have been entered to win the fishing excursion!",
      "long_description": "Thank you for trying our new flavors of Joes Original Beer Battered Fish Sticks. You have been entered for a chance to win a Fishing Excursion with the real Fisherman Joe!",
      "terms_url": "https://our-program.com/assets/terms-and-conditions.pdf",
      "disclaimer": "This trip will be awarded to one winner only. Should the selected winner decline, a new winner will be selected.",
      "disclaimer_url": "https://our-program.com/assets/general-disclaimer.pdf",
    },
    "relationships": {
      "subject": {
        "data": {
          "id": "443f3bdf-627f-40c5-beb9-718c09f5dcbb",
          "type": "offers"
        }
      }
    }
  }
}'

Step 2.4: Create the Vouchered Offer Constraint

In order for Hatch to correctly process a vouchered Offer, we must configure the Offer with a Requires Voucher Constraint. This indicates to the system that this Offer cannot be fulfilled by a member unless the member has sufficient vouchers for the Offer. We can create the Constraint via the api:

curl -X POST \
  https://api.hatchloyalty.com/api/v2/constraints \
  -H 'accept: application/vnd.api+json' \
  -H 'authorization: Bearer 066a7466' \
  -H 'content-type: application/vnd.api+json' \
  -d '{
  "data": {
    "type": "constraints",
    "attributes": {
      "constraint_type": "requires_voucher",
      "configuration": {}
    },
    "relationships": {
      "offer": {
        "data": {
          "type": "offers",
          "id": "443f3bdf-627f-40c5-beb9-718c09f5dcbb"
        }
      }
    }
  }
}'

Step 2.5: Display the Vouchered Offer to Entrants

In order to display this Offer to members within your application, we will need to call the Membership Offers api for the member in question and the vouchered Offer, side-loading the Marketing Contents for the Offer. We'll need to inspect the voucher_count in the response and, if the member has vouchers, we'll display the Offer to them within your application and indicate how many entries they've gained into the sweepstakes (e.g., the value of the voucher_count).

Vouchered Membership-Offer Retrieval - Example Request

curl -X GET \
  https://api.hatchloyalty.com/api/v2/memberships/354067ec-ff43-487b-91ed-9134ac79954d/offers/443f3bdf-627f-40c5-beb9-718c09f5dcbb?include=marketing_contents \
  -H 'accept: application/vnd.api+json' \
  -H 'authorization: Bearer 066a7466'

Vouchered Membership-Offer 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": "fishing-excursion-fisherman-joes",
      "name": "Fishing Excursion with the real Fisherman Joe",
      "description": "",
      "category": "sweepstakes",
      "must_activate": false,
      "created_at": "20xx-03-01T21:58:19.087Z",
      "publish_at": "20xx-04-01T20:46:59.000Z",
      "expire_at": "20xx-06-02T21:40:00.000Z",
      "engagement_type": "vouchered",
      "custom_data": {},
      "discontinued": false,
      "voucher_count": 2
    },
    "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": "cf93b4a2-a23c-4857-97e3-341790a81b79"
          }
        ]
      }
    }
  },
  "included": [
    {
      "id": "cf93b4a2-a23c-4857-97e3-341790a81b79",
      "type": "marketing_contents",
      "links": {
        "self": "https://api.hatchloyalty.com/api/v2/marketing_contents/cf93b4a2-a23c-4857-97e3-341790a81b79"
      },
      "attributes": {
        "locale": "en_US",
        "title": "You have been entered to win a Fishing Excursion with the real Fisherman Joe!",
        "image_url": "https://our-program.com/assets/fishing-excursion-with-joe.png",
        "short_description": "You have been entered to win the fishing excursion!",
        "long_description": "Thank you for trying our new flavors of Joes Original Beer Battered Fish Sticks. You have been entered for a chance to win a Fishing Excursion with the real Fisherman Joe!",
        "terms_url": "https://our-program.com/assets/terms-and-conditions.pdf",
        "disclaimer": "This trip will be awarded to one winner only. Should the selected winner decline, a new winner will be selected.",
        "disclaimer_url": "https://our-program.com/assets/general-disclaimer.pdf",
      },
      "relationships": {
        "subject": {
          "links": {
            "self": "https://api.hatchloyalty.com/api/v2/marketing_contents/cf93b4a2-a23c-4857-97e3-341790a81b79/relationships/subject",
            "related": "https://api.hatchloyalty.com/api/v2/marketing_contents/cf93b4a2-a23c-4857-97e3-341790a81b79/subject"
          }
        }
      }
    }
  ]
}

We can inspect the response, particularly the voucher_count attribute of the Offer payload, and see that this member has the maximum of 2 entries in the sweepstakes.

Step 3: The Transactional Offer

Members will engage with the transactional Offer in order to gain entry into the sweepstakes. For your marketing initiative, this translates to an Offer configured to award vouchers to members upon purchase of at least $30 of Cajun, Buffalo, or BBQ Joe's Original Beer Battered Fish Sticks, with a limit of 2 vouchers awarded per member. We will need to create the Offer, as well as it's Earning Mechanism, Marketing Contents, and Limits.

Step 3.1: Create the Transactional Offer

We'll configure the Offer with the following attributes:

  • The chain_id, as we can recall from creating the vouchered offer, is e6cee754-faf8-46a4-99fd-47ba6c3201bc.
  • The Offer is to be published April 1st and and expired on May 31st, a day ahead of winner selection. We do this by setting publish_at to "20xx-04-01" and expire_at to "20xx-05-31".
  • The Offer will be referenced internally by setting the name to "Buy Joes Original Beer Battered Fish Sticks to Win". Members do not see this title; it's intended for internal-facing usage only.
  • We'll categorize this Offer by setting the category to "transactional"; this helps your digital signage to display the Offer in the proper locations.
  • If your mobile application needs a reference to the Offer, we'll provide a readable one by setting the external_id to "fishing-excursion-fisherman-joes".
  • We'll set the Offer's engagement_type to transactional.

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": "Buy Joes Original Beer Battered Fish Sticks to win",
      "publish_at": "20xx-04-01",
      "expire_at": "20xx-05-31",
      "category": "transactional",
      "external_id": "buy-fish-stix-for-trip",
      "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": "23420214-b692-47f6-8967-89340ee195a4",
    "type": "offers",
    "links": {
      "self": "https://api.hatchloyalty.com/api/v2/offers/23420214-b692-47f6-8967-89340ee195a4"
    },
    "attributes": {
      "chain_id": "e6cee754-faf8-46a4-99fd-47ba6c3201bc",
      "external_id": "buy-fish-stix-for-trip",
      "name": "Buy Joes Original Beer Battered Fish Sticks to win",
      "description": "",
      "category": "transactional",
      "must_activate": false,
      "created_at": "20xx-03-01T00:00:00.000Z",
      "publish_at": "20xx-04-01T00:00:00.000Z",
      "expire_at": "20xx-05-31T00: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 23420214-b692-47f6-8967-89340ee195a4.

Step 3.2: Create the Transactional Offer Earning Mechanism

Given that the transactional Offer in this sweepstakes should apply to the purchase of specific products and award vouchers for that purchase, we will configure the Offer with the Product Purchase Earning Mechanism and a Voucher award (see the Earning Mechanisms guide for more details). The Product Purchase Earning Mechanism requires either the creation or use of an existing Product Group so that the eligible products for the Offer can be identified in a Transaction.

Configuring a Product Group

Before we can create the Earning Mechanism, we'll need to create a Product Group with the UPC's for the new fish sticks flavors, by calling the create product group api:

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": {
      "name": "New Fish Stick Flavors",
      "key": "upc",
      "values": ["000011112222", "000033334444", "000055556666"]
    },
    "relationships": {
      "chain": {
        "data": {
          "id": "e6cee754-faf8-46a4-99fd-47ba6c3201bc",
          "type": "chains"
        }
      }
    }
  }
}'

Upon the success of this call, we'll find that the new Product Group has been created with the id 3d6b1a4a-54ac-4691-8496-2de0e062cdfe.

Creating the Earning Mechanism

To create the Earning Mechanism for the transactional Offer, 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": "product_purchase",
      "configuration": {
        "count_products_by": "money_amount",
        "eligible_product_groups": ["3d6b1a4a-54ac-4691-8496-2de0e062cdfe"],
        "purchase_threshold": 30
      },
      "award": {
        "award_type": "vouchers",
        "configuration": {
          "voucher_count": 1,
          "voucher_expiration_days": null,
          "vouchered_offer_id": "443f3bdf-627f-40c5-beb9-718c09f5dcbb"
        }
      }
    },
    "relationships": {
      "offer": {
        "data": {
          "id": "23420214-b692-47f6-8967-89340ee195a4",
          "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 3.3: Create the Transactional Offer Marketing Contents

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": "Try new Joes Original Beer Battered Fish Sticks flavors for a chance to win a fishing excursion!",
      "image_url": "https://our-program.com/assets/new-fish-sticks-flavors.png",
      "short_description": "Try new flavors of Fish Sticks for a chance to win!",
      "long_description": "Try Joes Original Beer Battered Fish Sticks new Cajun, Buffalo, or BBQ flavors for a chance to win a Fishing Excursion with the real Fisherman Joe!",
      "terms_url": "https://our-program.com/assets/terms-and-conditions.pdf",
      "disclaimer": "Each purchase of $30 will equal one entry into the sweepstakes. Limit 2 entries per person.",
      "disclaimer_url": "https://our-program.com/assets/general-disclaimer.pdf",
    },
    "relationships": {
      "subject": {
        "data": {
          "id": "23420214-b692-47f6-8967-89340ee195a4",
          "type": "offers"
        }
      }
    }
  }
}'

Step 3.4: Create the Transactional Offer Per-Membership Limit

To allow each of your valued consumers a fair chance to win the Fishing Excursion with the real Fisherman Joe, we want to limit entries into the sweepstakes to two per person. We can accomplish this by creating a Membership Award Count Limit on the Offer. This limit 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": "23420214-b692-47f6-8967-89340ee195a4",
          "type": "offers"
        }
      }
    }
  }
}'

Step 4: Checking Progress and Selecting the Sweepstakes Winner

It's important for Fisherman Joe's™ to be able to track the progress of their sweepstakes on a weekly basis. It's also important that Fisherman Joe's™ gets the pool of entrants (e.g., all vouchers for the vouchered offer) at the end of the sweepstakes, so that they may select the winner. Hatch will provide an extract of all vouchers, so that the customer may select the winner from the pool. Note: Customers control the winning mechanism for sweepstakes promotions run through Hatch. Once Fisherman Joe's™ has selected their winner, they can record this in Hatch by fulfilling the vouchered Offer for that member.

Step 4.1: Status Checks During the Sweepstakes

We can query the Offer Show endpoint for the vouchered Offer to get the total voucher_count at any time. This enables us to perform weekly status checks and gage members' interest in the promotion.

Vouchered Offer Retrieval - Example Request

curl -X GET \
  https://api.hatchloyalty.com/api/v2/offers/443f3bdf-627f-40c5-beb9-718c09f5dcbb \
  -H 'accept: application/vnd.api+json' \
  -H 'authorization: Bearer 066a7466'

Vouchered Offer 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": "fishing-excursion-fisherman-joes",
      "name": "Fishing Excursion with the real Fisherman Joe",
      "description": "",
      "category": "sweepstakes",
      "must_activate": false,
      "created_at": "20xx-03-01T21:58:19.087Z",
      "publish_at": "20xx-04-01T20:46:59.000Z",
      "expire_at": "20xx-06-02T21:40:00.000Z",
      "engagement_type": "vouchered",
      "custom_data": {},
      "discontinued": false,
      "voucher_count": 5000
    },
    "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": "cf93b4a2-a23c-4857-97e3-341790a81b79"
          }
        ]
      }
    }
  }
}

Based on the above response, we can see that there are 5000 entries in your sweepstakes thus far!

Step 4.2: Retrieve the Pool of Entrants

Once the sweepstakes has concluded and the transactional Offer has expired, e.g., members can no longer gain entries (via award of vouchers), Fisherman Joe's™ will need to somehow retrieve the pool of vouchers so that they can select their winner for the Fishing Excursion with the real Fisherman Joe. Luckily, we are already set up to receive a daily extract of the Membership Offers table, which contains all voucher records and includes the following attributes of interest for each voucher record: id, membership_id, offer_id. Note: In the case that you do not receive a daily extract, you can request that Hatch provide you with a CSV of the voucher pool for your sweepstakes.

We can filter out the records associated with the vouchered Offer based on the values in the offer_id field and then select the winner from that batch of records. Once the winning record has been selected, we will want to note the membership_id for that record, as we will need it for fulfillment.

Step 4.3: Fulfill the Vouchered Offer for the Sweepstakes Winner

Once a winner has been selected for the sweepstakes, we will need to fulfill the vouchered Offer for that member, as this is how Hatch knows about the winner. As the vouchered Offer was configured with a Loyalty Event Earning Mechanism, it can be fulfilled by creating a Loyalty Event record for the member with the matching event_type from the vouchered Offer's earning mechanism. We can recall that we configured the Offer with an event_type of fisherman-joes-excursion-winner. We will create the Loyalty Event record by POSTing to the create Loyalty Event api endpoint:

curl -X POST \
  https://api.hatchloyalty.com/api/v2/loyalty_events \
  -H 'accept: application/vnd.api+json' \
  -H 'authorization: Bearer 066a7466'
  -d '{
  "data": {
    "type": "loyalty_events",
    "attributes": {
      "event_type": "fisherman-joes-excursion-winner",
      "event_data": {
        "membership_id": "354067ec-ff43-487b-91ed-9134ac79954d"
      }
    },
    "relationships": {
      "chain": {
        "data": {
          "id": "e6cee754-faf8-46a4-99fd-47ba6c3201bc",
          "type": "chains"
        }
      }
    }
  }
}'

What happens to Vouchers after the Sweepstakes?

Now that the sweepstakes has ended and Fisherman Joe's™ has sent the winner on the Fishing Excursion with the real Fisherman Joe, they are wondering, what happens to all the other entry records (e.g., vouchers)? Do they disappear? Are they just sitting on your books forever as a financial liability?

Not to worry, once the vouchered Offer has expired, any unfulfilled vouchers for that Offer are also expired and not valid for use within Hatch. When a voucher is expired, it is NOT deleted, the status is simply transitions to expired. We've configured the vouchered Offer to expire the day following the selection of the winner, so all remaining vouchers for the Offer will expire then as well. Note we will just want to be sure we've sent the fulfillment in for the winner ahead of this expiration, as it is not possible to transition a voucher from expired to fulfilled.

Conclusion

Through this tutorial all necessary components have been created within Hatch to support a complex lottery or sweepstakes marketing initiative. A vouchered Offer has been developed, representing the prize granted to the winner of the sweepstakes, as well as a transactional Offer, which awards vouchers (e.g., entries) for the sweepstakes. We've learned how to use the Membership Offer endpoint to determine if a member is entered into the sweepstakes, so the details of the sweepstakes prize can be displayed to entrants within your application. The process for mid-sweepstakes status checks has been explained, as well as the process for filtering out the relevant vouchers (e.g., entries) from the data extract records. We've learned how to fulfill the vouchered Offer for the winning member and have discovered what happens to remaining vouchers once the promotion has concluded.

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.