Offer Reservation Tutorial

Offer Reservation Tutorial

Learn how to protect voucher-backed, externally fulfilled offers from multiple use, over-fulfillment, and use after return.

Multiple use, over-fulfillment, and use after return represent erroneous fulfillment cases that may arise either unintentionally or from intentional fraud. Multiple use may occur if a member is identified at multiple point of sale systems simultaneously, then both systems attempt to fulfill the same offer. Over-fulfillment may occur if a point of sale requests available offers while a previous fulfillment is being processed by Hatch. Use after return may occur when a member returns a previously purchased offer while in the middle of a transaction that would fulfill that same offer.

Intro

Hatch supports many types of marketing initiatives that can be created, validated, and fulfilled entirely within the platform, such as when a member has purchased certain products or engaged in key behaviors. However, initiatives that involve the disbursement of a material benefit, e.g., a product discount or physical entry in to an event, require verification from an external system (a point of sale, or mobile application).

Hatch can not control the fulfillment of these types of offers, although it may still inform Audience targeting and fulfillment Limitation via an offer's Visible Status. Hatch requires the cooperation of the fulfilling system to indicate that a given member has demonstrated the behavior, received the benefit, and has fulfilled the offer.

Even with perfect cooperation between Hatch and the fulfilling system, there are cases where unintended over-fulfillment, multiple use, or use after return may occur. This misuse window exists from the time that an external system requests a member's offers until the fulfillment of those offers has been recorded in Hatch. Such a window does not exist for offers that are fulfilled entirely within the platform because Hatch maintains internal safety-mechanisms to prevent misuse.

In order to prevent over-fulfillment, multiple use, use after return, and any other types of misuse related to external fulfillment, Hatch provides the ability to reserve fulfillment for externally-fulfilled, vouchered offers. This tutorial demonstrates reservation with the following steps:

  1. Create an externally fulfilled offer
  2. Retrieve relevant membership-offers
  3. Calculate pre-fulfillment
  4. Reserve fulfillment
    1. Reservation request
    2. Reservation response
    3. Point of Sale discounting
  5. Record fulfillment
  6. Understand when reservation is required

Steps

Step 1: Create an externally fulfilled offer

Only offers that require an external system to verify the member's behavior, and to disburse a material benefit, might require their fulfillment to be reserved in order to protect against misuse. This tutorial assumes that an offer has been configured to require a voucher, and that it is externally fulfilled via an externally fulfillable, or loyalty event earning mechanism whose primary benefit is disbursed outside of Hatch.

More detail on creating such an offer may be found in the Vouchered Offer Tutorial.

Step 2: Retrieve relevant membership-offers

In order to prevent the misuse of an externally fulfilled offer it must be vouchered. The offer must also be visible, and the member must have one or more vouchers available for use before an external system considers whether to fulfill the offer. For example, a point of sale decides whether to award a 50¢ discount on softdrink products only if the member has received such a voucher.

The Vouchered Offer Tutorial describes how to construct an api request to list such membership-offers.

Step 3: Calculate pre-fulfillment

Prior to requesting the reservation of a number of fulfillments, the external system should pre-calculate which offers might be externally fulfilled. This prevents mass over-reservation and prevents the external system from displaying a discount that must be rolled back if the later reservation fails.

The external system is ready to reserve a number of fulfillments for certain offers once it has calculated those that should be fulfilled, that is: where the offer is visible to the member; the member has available vouchers; and the member has demonstrated the necessary behavior such as the purchase of a specified product, or arrival at a special members-only event.

Step 4: Reserve fulfillment

Once the external system is prepared to fulfill one or more externally fulfilled offers, it should make a reservation request via the Offer Reservation API. In this scenario, we assume th at a point of sale has previously requested all visible offers for a member identified by the id c0c5b7d9-f909-48e0-a5d2-deaf3c6c4023.

The member has three vouchered offers with vouchers available for fulfillment:

  • a 50¢ discount on coffee
    • offer id: 9966bb12-a835-4c8d-a6ec-a0608a7fa3d5
    • vouchers available: 2
  • a buy-one-get-one discount on a certain brand of candy bars
    • offer id: 019cb6dd-98a2-468c-a2b8-c239319754fb
    • vouchers available: 1
  • a free newspaper
    • offer id: 559976b4-b804-432e-90b0-4d6a4ff0320c
    • vouchers available: 1

In the transaction, the point of sale has identified 2 coffees, 2 candy bars, and 1 newspaper, and is prepared to fulfill the coffee offer twice, the candy bar offer once, and the newspaper offer once for a total discount of $1 plus the cost of the free candy bar and the newspaper. This step describes the reservation request for the proposed fulfillments, the response indicating partially successful grants, and the discounts that the point of sale should apply. In this example, the reservation request will succeed for one fulfillment of the coffee offer and the fulfillment of the newspaper offer. The request will fail to grant reservations for one of the coffee offer fulfillments, as well as the candy bar offer fulfillment. Reservations may fail if there is a simultaneous reservation for the same fulfillment from a different point of sale, or if a purchase of vouchers for the fulfillment have been returned.

Step 4.1: Reservation request

Prior to displaying this discount, the point of sale makes a reservation call as follows:

curl -X POST \
  https://api.hatchloyalty.com/api/v2/memberships/c0c5b7d9-f909-48e0-a5d2-deaf3c6c4023/offer_reservations \
  -H 'accept: application/vnd.api+json' \
  -H 'authorization: Bearer 066a7466' \
  -H 'content-type: application/vnd.api+json' \
  -d '{
  "data": [{
    "type": "offer_reservations",
    "attributes": {
      "offer_id": "9966bb12-a835-4c8d-a6ec-a0608a7fa3d5",
      "requested_reservation_count": 2
    }
  }, {
    "type": "offer_reservations",
    "attributes": {
      "offer_id": "019cb6dd-98a2-468c-a2b8-c239319754fb",
      "requested_reservation_count": 1
    }
  }, {
    "type": "offer_reservations",
    "attributes": {
      "offer_id": "559976b4-b804-432e-90b0-4d6a4ff0320c",
      "requested_reservation_count": 1
    }
  }]
}'

Step 4.2: Reservation response

In response, the API returns the following payload:

{
  "data": [{
    "type": "offer_reservations",
    "attributes": {
      "offer_id": "9966bb12-a835-4c8d-a6ec-a0608a7fa3d5",
      "requested_reservation_count": 2,
      "granted_reservation_count": 1,
      "reserved_until": "20xx-xx-xxT14:xx:xxZ" // The reservation is valid from its initial request and expires after an interval configured for the loyalty program.
    }
  }, {
    "type": "offer_reservations",
    "attributes": {
      "offer_id": "019cb6dd-98a2-468c-a2b8-c239319754fb",
      "requested_reservation_count": 1,
      "granted_reservation_count": 0,
      "reserved_until": "20xx-xx-xxT14:xx:xxZ" // The reservation is valid from its initial request and expires after an interval configured for the loyalty program.
    }
  }, {
    "type": "offer_reservations",
    "attributes": {
      "offer_id": "559976b4-b804-432e-90b0-4d6a4ff0320c",
      "requested_reservation_count": 1,
      "granted_reservation_count": 1,
      "reserved_until": "20xx-xx-xxT14:xx:xxZ" // The reservation is valid from its initial request and expires after an interval configured for the loyalty program.
    }
  }]
}

Step 4.3: Point of Sale discounting

This response indicates that the coffee offer has a partially successful reservation (1/2), that the candy bar offer has no successful reservations, and that the newspaper offer has been successfully reserved. The point of sale is responsible for examining the difference between requested and granted reservations, and providing the appropriate discounts (in this case: one 50¢ discount on coffee, and a discount for the cost of the newspaper).

The point of sale should not provide discounts for requested reservations that were not granted. In the above example, no discount should be applied for the second coffee, or for the buy-one-get-one candy bar. Reservations that are not granted may be due either to a separate reservation that has not yet been released, or because the purchase that originally granted vouchers for the fulfillment have since been returned.

Offer reservations expire within a short window of time (configurable for the loyalty program as a whole), and do not currently have the capacity to be explicitly released.

Step 5: Record fulfillment

Once the point of sale has secured fulfillment of the externally fulfilled offers and disbursed the offers' benefits, it should indicate to Hatch that the offer has been fulfilled. Hatch will then record fulfillment against configured limits and mark any related vouchers as fulfilled. Depending on the type of earning mechanism that has been configured for the offer, fulfillment might be signaled by the creation of a loyalty event, or the recording of those fulfilled_offer_ids in the transaction payload.

Step 6: Understand when reservation is required

There are two important points to consider when using externally fulfilled offers in a loyalty program: only externally fulfilled offers that require vouchers may be reserved, and a reservation is required to guarantee protection from misuse.

Offers that use the external fulfillment or loyalty event earning mechanisms may be configured without the requires voucher constraint. In either case, when Hatch is responsible for disbursing the benefit (e.g., points, or vouchers for another offer) reservation is not required at all. Such an offer might require a member to engage in an in-person survey and be awarded points. The survey system might send a Loyalty Event indicating that the member has fulfilled the offer by filling out the survey, but Hatch is responsible for enforcing the member's eligibility and the offers fulfillment limits because it is responsible for disbursing the benefit.

In cases where the offer is fulfilled externally and the benefit is also disbursed outside of Hatch, misuse may only be prevented with the requirement of vouchers.

Finally, in cases where the external system is responsible for calculating fulfillment and disbursing benefits, Hatch has no direct ability to restrict such fulfillments. If an external system loses internet connectivity between requesting a member's offers and attempting a reservation request, Hatch has no mechanism to interject in the transaction. This means that Hatch does not prevent an external system from continuing with its transaction. It also means that the external system may be configured to fulfill offers and disburse benefits while unable to request reservations. Hatch will record this fulfillment even if it otherwise should not have occurred once internet connectivity has been reestablished.

Conclusion

This tutorial has described how to externally fulfill an offer and to disburse a material benefit outside of Hatch. It has also described a few vectors for misusing such a offer, and has explored a strategy to prevent misuse through offer reservation.

Hatch 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 information.