Offers

API Reference

Offers are exposed via an API resource called Offers.

What is an Offer?

An Offer is the primary way in which a program works to influence consumer behavior.

An Offer, when fully assembled, represents the beneficial consumer behavior that a client would like their members to engage with, as well as the way those members are incentivized to do so. An Offer also includes any additional Constraints that must be met prior to fulfillment, the Audience that an Offer is meant to be visible to, any Limits on fulfillment or activation of the Offer, and the Marketing Content used to display an Offer to a member.

How are Offers configured?

Offers are configured with important meta-data that manage the initiative as a whole: a category and external_id so that they may be properly recognized by a client system; the publish_at and expire_at fields that dictate when Offers are active in the marketing program. Offers without further configuration do not represent an active part of a loyalty program. Offers are, rather, a resource that must be created first in order for other offer components to be configured which describe the marketing initiative.

An Offer's Components

The marketing initiative that an Offer represents is described by five components:

  • Earning Mechanism: The behavior that the marketing initiative promotes, as well as the incentive (award) given to a member for engaging with it, e.g., the purchase of a specific product in exchange for points.
  • Constraints: Any pre-fulfillment actions or conditions that must be met in order for a member to engage an Offer, e.g., "activation".
  • Audiences: Any factors that dictate the subset of members that should be targeted by an Offer, e.g., that a member is in a required custom segment.
  • Limits: Any limits, either global or per-member, that fulfillment or engagement with an Offer must abide by, e.g., a limit of 4000 fulfillments total.
  • Marketing Contents: The locale-specific marketing copy that is shown to a member in a mobile application or digital signage, e.g., the title and an image.

Which members may engage with an offer?

A successful marketing program may consist of offers with a wide variety of configurations; some are meant to engender general engagement with the program and are available to all members, while others may be targeted to a specific group of members based on their behavioral or demographic characteristics. Offers may also require certain actions, like Activation, or be constrained by fulfillment limits.

An effective marketing program will only show relevant offers to a particular member, and will indicate any prerequisite actions that the member must take. This section describes the fields of an offer that display this information. For more on using these fields when requesting offers for a specific member, see the Retrieve Membership-Offers Tutorial.

The ability for a member to engage with an offer is dictated by that offer's constraints, audiences, and limits. These three offer components influence whether the offer should be visible to a member (e.g., whether it should be displayed to them in a mobile application or other targeted signage) and, if so, whether the member is eligible for the offer due to prerequisites such as activation that the member must complete.

The following sections describe Visibility, Eligibility, and Activation, both in the context of an Offers request as well as offers related to a specific member via Membership-Offers.

Visibility

Hatch uses the term Visibility to describe whether a particular offer should be presented to a member. Visibility considers factors that are outside of the direct control of a member, such as their age, custom segment, or other limitations on the offer. Visibility is primarily governed by Audiences and Limits, and the output of the visibility calculation is available in the visible_status field of an Offer or Membership-Offer. A visible_status of visible indicates that the offer should be shown, whereas any other status indicates a reason as to why it should be hidden. An offer whose visible_status is not visible will not be considered when examining behaviors determined by the offer's Earning Mechanism, and will not generate awards even when they would otherwise fulfill the offer's requirements.

There are some statuses that apply to all member equally ("global" statuses), and some that are based on a particular member's behavior or demographics ("per-member" statuses). A global status will always take precedence over a per-member status, and will be returned when calling either the Offers or Membership-Offers api. A per-member status will only be returned when calling the Membership-Offers api and indicates the visible_status for that member, for that offer.

The list below describes each of the possible values, as well as the context (global, and/or per-member) in which each value may be returned.

Possible Values:

  • visible (global, per-member)
    • When returned via the Offers api (without a member id), this indicates that the offer is active and not currently subject to any global Limits. The offer may be displayed on digital signage or in print material. Note that there may be reasons that the offer should be hidden from a specific member, e.g., a per-member fulfillment limit.
    • When returned via the Membership-Offers api, this indicates that the offer has no global restrictions on its display, and that the member satisfies any Audiences or Limits that have been configured for the offer, e.g., an age-restriction, or per-member activation limit.
  • discontinued (global, per-member)
    • The offer has been discontinued and is no longer an active part of the marketing program.
  • unpublished (global, per-member)
    • The offer has a publish_at in the future and is not yet available for members to engage with.
  • expired (global, per-member)
    • The offer has an expire_at in the past and is no longer available for members to engage with.
  • global_limit (global, per-member)
    • The offer has reached a global Limit and is no longer available for any member to fulfill.
  • member_limit (per-member)
    • The given member has reached a per-member Limit and the offer is no longer available for this member to fulfill.
  • age_restricted (per-member)
    • The given member does not fall within an age-based Audience that has been configured for this offer.
  • missing_required_segments (per-member)
    • The given member does not belong to a custom segment that has been configured for this offer.

Eligibility

Hatch uses the term Eligibility to describe whether a member is currently eligible to engage with a particular offer; when a member is not eligible, they will not receive an award even if they engage in the offer's expected behavior (both described by the offer's Earning Mechanism). With the exception of Visibility, Eligibility considers factors that are within the direct control of a member, such as the requirement to first activate an offer before engaging with it. Eligibility is primarily governed by Constraints, and the output of the eligibility calculation is available in the eligible field of a Membership-Offer. An eligible value true indicates that the member has met any required prerequisites of the offer and may engage with it.

Since an offer whose visible_status is not visible should not be displayed to a member, this will also cause eligible to be false even when other prerequisite conditions are fulfilled. Because Eligibility is calculated on a per-member basis, the eligible field will only be returned when calling the Membership-Offers api and is excluded from calls to the Offers api.

The list below describes the conditions that result in eligible being false. The absence of any of these conditions will result in eligible being true.

The eligible field is false when:

  • The offer's visible_status is anything other than visible.
  • The offer requires activation and has not been activated.

Note: because an offer may be ineligible due either to Visibility or a prerequisite action the the member must take, it may not be useful to filter out ineligible offers from view without further consideration. Instead, the visible_status (above) or activation_status (below) should be considered for ineligible offers.

Activation

Hatch uses the term Activation to describe a specific type of prerequisite action that a member must take before engaging with an offer; namely that the member must display specific intent to engage with the offer (by activating it) before they may fulfill its behavior and receive its award. As described above, Activation is used in calculating Eligibility, and is governed by the Requires Activation Constraint. The calculation for whether an offer requires activation and is activated is available in the activation_status field of an Offer or Membership-Offer.

The activation_status of requires_activation and does_not_require_activation apply to all members equally and may be returned when calling the Offers api; an activation_status of activated is only available in the context of a Membership-Offer and will only be returned when calling the Membership-Offers api.

The list below describes each of the possible values, as well as the context (global, and/or per-member) in which each value may be returned.

Possible Values:

  • does_not_require_activation (global, per-member)
    • The offer has not been configured to require activation and is not required to be activated before a member may engage with it.
  • requires_activation (global, per-member)
    • The offer has been configured to require activation before a member may engage with it. An offer may be activated for a member via the Activate Membership-Offer api.
  • activated (per-member)
    • The offer requires activation and the member has already activated it, allowing them to engage with the offer.

Other attributes

While visible_status, eligible and activation_status are the primary attributes used to understand the relationship between Memberships and Offers, both the Offer and Membership-Offer provide additional information that may be used when displaying an offer to a member.

Fulfillment Count

Possible Values: 0, or any positive integer

The Membership-Offer's fulfillment_count attribute returns the number of times that a member has previously successfully engaged with the offer, and has earned the award configured along with its earning mechanism. For offers that award a variable number of points, the fulfillment count will not indicate the total of points awarded, but will instead indicate the number of distinct times that the member has received points.

Must Activate (deprecated, see Activation)

Possible Values: true, false

The Membership-Offer's must_activate attribute indicates whether an offer requires activation prior to becoming eligible for a member to engage with. An offer will return must_activate: true when a requires activation constraint has been configured for the offer. This indicates that the offer must be activated via a call to the Membership-Offer activation api.

Activated (deprecated, see Activation)

Possible Values: true, false, null

The Membership-Offer's activated attribute indicates whether the offer has previously been activated for the member via a call to the Membership-Offer activation api. A value of null indicates that this offer does not require activation.