Return Offer Purchase Tutorial

Return Offer Purchase Tutorial

Learn how to present a member's returnable offer purchases and how to execute a return in order to refund a member's points.

Intro

A loyalty program may use Hatch's purchasable offers to provide a targeted, limitable engagement mechanism that encourages a member to spend their points in exchange for a material benefit that is redeemable within your store.

A loyalty program's points are a valuable currency for members, and members may spend points confidently knowing that a return mechanism exists which allows them to refund their points if an offer is no longer useful to them. A loyalty program benefits from returns as well; only engaging offers entice a member to visit your store. An offer that a member is excited to use both encourages them to interact with the loyalty program, and also ultimately lowers the financial burden of large outstanding point balances within your loyalty program. The ability for a member to return an unused offer purchase for one they find more beneficial continues to engage that member with the loyalty program.

This tutorial describes how a member is made aware of those past purchases that are available for return, the circumstances that allow a purchase to be returnable, and the process for executing a return, in the following steps:

  1. Retrieve returnable purchases
  2. Understand when an offer purchase is returnable
  3. Execute a return

Steps

Step 1: Retrieve returnable purchases

A member's offer purchases are related to their offers via a relationship called returnable_purchases. A purchase itself is used to grant vouchers for a vouchered offer, and returning an offer purchase is the act of returning those vouchers in exchange for a refund of the points originally spent on the purchase. When displaying a member's available "inventory" of usable vouchers, an external system, such as a mobile application, makes the following call to the membership offers api.

Visible Membership-Offers with Returnable Purchases Retrieval - Example Request

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

Visible Membership-Offers with Returnable Purchases Retrieval - Example Response

{
  "data": [
    {
      "id": "bc9fcc89-6a99-4bc4-852b-f9bd52b0f195",
      "type": "offers",
      "links": {
        "self": "https://api.hatchloyalty.com/api/v2/memberships/354067ec-ff43-487b-91ed-9134ac79954d/offers"
      },
      "attributes": {
        "chain_id": "9b7575cb-a1ff-405f-9390-4ea826666c5f",
        "external_id": null,
        "name": "2 oranges for 100 points. Requires activation.",
        "description": "Orange producer would like members to show intent; this offer requires activation.",
        "category": "transactional",
        "must_activate": true,
        "created_at": "2017-07-19T14:42:42.165Z",
        "publish_at": "2050-08-15T07:00:00.000Z",
        "expire_at": "2052-08-29T22:00:00.000Z",
        "custom_data": {},
        "discontinued": false,
        "activated": false,
        "eligible": false,
        "fulfillment_count": 0,
        "activation_status": "requires_activation",
        "visible_status": "visible",
        "rule_id": "579807c5-de8f-4aca-a49a-1b3c4909179f"
      },
      "relationships": {
        "returnable_purchases": {
          "links": {
            "self": "https://api.hatchloyalty.com/api/v2/offers/50f07c49-2b6a-4cf7-bdf4-770b3d41f221/relationships/offer_purchase",
            "related": "https://api.hatchloyalty.com/api/v2/offers/50f07c49-2b6a-4cf7-bdf4-770b3d41f221/offer_purchase"
          },
          "data": [
            {
              "type": "offer_purchase",
              "id": "dfb4cc45-ba6b-403c-9203-19b9c0723d22"
            }
          ]
        }
      }
    },
    // Some additional offers
  ],
  "included": [
    {
      "id": "dfb4cc45-ba6b-403c-9203-19b9c0723d22",
      "type": "offer_purchases",
      "attributes": {
        "created_at": "2019-09-16T19:03:40.941Z",
        "discontinued": false,
        "point_cost": 50,
        "reserved_until": null,
        "returnable": true,
        "purchasable_offer_id": "bc9fcc89-6a99-4bc4-852b-f9bd52b0f195",
        "vouchered_offer_id": "92cb2908-c836-49a6-9274-4900b16762c2"
      },
      "links": {
        "self": "http://www.example.com/api/v2/offer_purchases/dfb4cc45-ba6b-403c-9203-19b9c0723d22"
      },
      "relationships": {
        "purchased_with": {
          "links": {
            "self": "http://www.example.com/api/v2/offer_purchases/dfb4cc45-ba6b-403c-9203-19b9c0723d22/relationships/purchased_with",
            "related": "http://www.example.com/api/v2/offer_purchases/dfb4cc45-ba6b-403c-9203-19b9c0723d22/purchased_with"}
          },
        "voucher_grant_for": {
          "links": {
          "self": "http://www.example.com/api/v2/offer_purchases/dfb4cc45-ba6b-403c-9203-19b9c0723d22/relationships/voucher_grant_for",
          "related": "http://www.example.com/api/v2/offer_purchases/dfb4cc45-ba6b-403c-9203-19b9c0723d22/voucher_grant_for"}
        }
      }
    }
  ]
}

By matching the offer's returnable_purchases (from the offer's relationships field) to the included offer_purchases by id, the client application can annotate those vouchered offers that have purchases available for return. The point_cost field in each offer_purchase indicates the number of points a member should expect to receive in refund.

Step 2: Understand when an offer purchase is returnable

An offer purchase is returnable as long as none of the vouchers granted by the purchase have been used or have expired. An offer purchase is marked as returnable false automatically in each of these cases; it's also marked returnable false if the purchase itself has been successfully returned.

When performing an offer reservation, any related offer purchases are also reserved. The offer reservation itself will indicate its reservation time via the reserved_until attribute, and such purchases will not be returned when the returnable_offers relationship is loaded.

In either case, the returnable_offers relationship only displays offer purchases that are eligible for return. A return of an offer purchase may still fail, however, if it becomes non-returnable between requesting returnable_offers and executing the return because of expiration, reservation, or use.

Step 3: Execute a return

Once a member has chosen to return an offer purchase in order to receive a refund of their points, an external system makes a PATCH call to return the relevant purchase via the return offer purchase api. Here, we return a purchase with the id dfb4cc45-ba6b-403c-9203-19b9c0723d22.

Return Offer Purchase - Example Request

curl -X PATCH \
  https://api.hatchloyalty.com/api/v2/offer_purchases/dfb4cc45-ba6b-403c-9203-19b9c0723d22/return \
  -H 'accept: application/vnd.api+json' \
  -H 'authorization: Bearer 066a7466'

Return Offer Purchase - Example Response

{
  "data": {
    "id": "dfb4cc45-ba6b-403c-9203-19b9c0723d22",
    "type": "offer_purchases",
    "links": {
      "self": "http://www.example.com/api/v2/offer_purchases/dfb4cc45-ba6b-403c-9203-19b9c0723d22"
    },
    "attributes": {
      "created_at": "2019-09-16T19:45:13.630Z",
      "discontinued": false,
      "point_cost": 50,
      "reserved_until": null,
      "returnable": false,
      "purchasable_offer_id": "bc9fcc89-6a99-4bc4-852b-f9bd52b0f195",
      "vouchered_offer_id": "92cb2908-c836-49a6-9274-4900b16762c2"
    },
    "relationships": {
      "purchased_with": {
        "links": {
          "self": "http://www.example.com/api/v2/offer_purchases/dfb4cc45-ba6b-403c-9203-19b9c0723d22/relationships/purchased_with",
          "related": "http://www.example.com/api/v2/offer_purchases/dfb4cc45-ba6b-403c-9203-19b9c0723d22/purchased_with"
        }
      },
      "voucher_grant_for": {
        "links": {
          "self": "http://www.example.com/api/v2/offer_purchases/dfb4cc45-ba6b-403c-9203-19b9c0723d22/relationships/voucher_grant_for",
          "related": "http://www.example.com/api/v2/offer_purchases/dfb4cc45-ba6b-403c-9203-19b9c0723d22/voucher_grant_for"
        }
      }
    }
  }
}

A successful response indicates that the purchase has been returned. Any response with a 4xx response code will indicate some reason that the purchase is not eligible for return. The return of an offer purchase will:

  • Refund the point_cost of the purchase to the member
  • Transition all vouchers related to the purchase to abandoned
  • Remove one fulfillment from the purchasable offer that was used to execute the original purchase
  • Return an available limit count to any fulfillment limits that are configured for the purchasable offer

Conclusion

This tutorial has described how to indicate offer purchases that are available for return, as well as the circumstances that dictate whether an offer purchase is eligible to be returned. It has also described the specific api call required to execute such a return on behalf of a member.

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.