Skip to content

Latest commit

 

History

History
63 lines (53 loc) · 4.72 KB

loyalty-promotion.md

File metadata and controls

63 lines (53 loc) · 4.72 KB
Raw

Loyalty Promotion

Represents a promotion for a loyalty program. Loyalty promotions enable buyers to earn extra points on top of those earned from the base program.

A loyalty program can have a maximum of 10 loyalty promotions with an ACTIVE or SCHEDULED status.

Structure

Loyalty Promotion

Fields

Name Type Tags Description
id String Optional The Square-assigned ID of the promotion.
Constraints: Minimum Length: 1, Maximum Length: 255
name String Required The name of the promotion.
Constraints: Minimum Length: 1, Maximum Length: 70
incentive Loyalty Promotion Incentive Hash Required Represents how points for a loyalty promotion are calculated,
either by multiplying the points earned from the base program or by adding a specified number
of points to the points earned from the base program.
available_time Loyalty Promotion Available Time Data Hash Required Represents scheduling information that determines when purchases can qualify to earn points
from a loyalty promotion.
trigger_limit Loyalty Promotion Trigger Limit Hash Optional Represents the number of times a buyer can earn points during a loyalty promotion.
If this field is not set, buyers can trigger the promotion an unlimited number of times to earn points during
the time that the promotion is available.

A purchase that is disqualified from earning points because of this limit might qualify for another active promotion.
status String (Loyalty Promotion Status) Optional Indicates the status of a loyalty promotion.
created_at String Optional The timestamp of when the promotion was created, in RFC 3339 format.
canceled_at String Optional The timestamp of when the promotion was canceled, in RFC 3339 format.
updated_at String Optional The timestamp when the promotion was last updated, in RFC 3339 format.
loyalty_program_id String Optional The ID of the loyalty program associated with the promotion.
minimum_spend_amount_money Money Hash Optional Represents an amount of money. Money fields can be signed or unsigned.
Fields that do not explicitly define whether they are signed or unsigned are
considered unsigned and can only hold positive amounts. For signed fields, the
sign of the value indicates the purpose of the money transfer. See
Working with Monetary Amounts
for more information.
qualifying_item_variation_ids Array<String> Optional The IDs of any qualifying ITEM_VARIATION catalog objects. If specified,
the purchase must include at least one of these items to qualify for the promotion.

This option is valid only if the base loyalty program uses a VISIT or SPEND accrual rule.
With SPEND accrual rules, make sure that qualifying promotional items are not excluded.

You can specify qualifying_item_variation_ids or qualifying_category_ids for a given promotion, but not both.
qualifying_category_ids Array<String> Optional The IDs of any qualifying CATEGORY catalog objects. If specified,
the purchase must include at least one item from one of these categories to qualify for the promotion.

This option is valid only if the base loyalty program uses a VISIT or SPEND accrual rule.
With SPEND accrual rules, make sure that qualifying promotional items are not excluded.

You can specify qualifying_category_ids or qualifying_item_variation_ids for a promotion, but not both.

Example (as JSON)

{
  "id": "id4",
  "name": "name4",
  "incentive": {
    "type": "POINTS_MULTIPLIER",
    "points_multiplier_data": {
      "points_multiplier": 134,
      "multiplier": "multiplier4"
    },
    "points_addition_data": {
      "points_addition": 218
    }
  },
  "available_time": {
    "start_date": "start_date4",
    "end_date": "end_date8",
    "time_periods": [
      "time_periods9"
    ]
  },
  "trigger_limit": {
    "times": 26,
    "interval": "ALL_TIME"
  },
  "status": "ACTIVE",
  "created_at": "created_at8",
  "canceled_at": "canceled_at0"
}