Attach Loyalty Reward

attachLoyaltyReward is used to attach a loyalty reward to the cart.

Usage

attachLoyaltyReward takes in the following object:

interface AttachLoyaltyRewardRequest {
    loyaltyAccountId: string;
    loyaltyRewardTierId: string;
    loyaltyRewardName: string;
    discountType: DiscountTypeEnum;
    discountScope: DiscountScopeTypeEnum;
    discountValue: number;
    maxDiscount?: number;
    itemIds?: string[];
    orderId?: string;
}

• loyaltyAccountId is the ID of the loyalty account.
• itemId is the id on your item resource.
• loyaltyRewardTierId is the ID of the loyalty reward (also called the reward tier).
• loyaltyRewardName is the name of the loyalty reward.
• discountType is the type of discount to apply.

  const DiscountTypeEnum = {
      FIXED_AMOUNT: 'FIXED_AMOUNT',
      FIXED_PERCENTAGE: 'FIXED_PERCENTAGE'
      VARIABLE_amount: 'VARIABLE_amount'
      VARIABLE_PERCENTAGE: 'VARIABLE_PERCENTAGE'
  };
  

• discountScope indicates whether the discount applies to specific items or to the whole purchase.

  const DiscountScopeTypeEnum = {
      LINE_ITEM: 'LINE_ITEM',
      WHOLE_PURCHASE: 'WHOLE_PURCHASE'
  };
  

  • discountValue is the discount value in amount money or percentage.
  • maxDiscount is the maximum discount value in amount money, or null if no maximum discount is set.
  • itemIds is an array of square item IDs that the discount can be applied to, if it applies to specific items.
  • orderId is the ID of the order to attach the reward to (same as cart ID). Uses the current order if not supplied.

Examples

// With a reward that applies to the whole purchase
const attachLoyaltyRewardRequest = {
    loyaltyAccountId: "5bcdb22f-0b57-4feb-af5a-d7f8ae33eb9f",
    loyaltyRewardTierId: "0534d095-9a58-427d-8e7a-0d28e5897b37",
    loyaltyRewardName: "15% off entire purchase (up to $10)",
    discountType: "FIXED_PERCENTAGE",
    discountScope: "WHOLE_PURCHASE",
    discountValue: 15,
    maxDiscount: 1000,
    orderId: "11ef1d135548d3a88c6b089e019fd17a"
}

// With a reward that applies to a specific item
const attachLoyaltyRewardRequest = {
    loyaltyAccountId: "5bcdb22f-0b57-4feb-af5a-d7f8ae33eb9f",
    loyaltyRewardTierId: "0534d095-9a58-427d-8e7a-0d28e5897b37",
    loyaltyRewardName: "$2.00 off one breakfast sandwich",
    discountType: "FIXED_AMOUNT",
    discountScope: "LINE_ITEM",
    discountValue: 200,
    itemIds: [
        "YGXQM2QSBTXHBNBCT4GTTIPD"
    ],
    orderId: "11ef1d135548d3a88c6b089e019fd17a"
};

// With a reward for a free item
const attachLoyaltyRewardRequest = {
    loyaltyAccountId: "5bcdb22f-0b57-4feb-af5a-d7f8ae33eb9f",
    loyaltyRewardTierId: "0534d095-9a58-427d-8e7a-0d28e5897b37",
    loyaltyRewardName: "Free coffee",
    discountType: "FIXED_PERCENTAGE",
    discountScope: "LINE_ITEM",
    discountValue: 100,
    itemIds: [
        "RG2LCHG3CJNEGMSSGJIBB4LE",
        "5GRBWL3BXLEIWB6U64JBEYK7",
        "FVNWVMAS5IT73OWNWGAQY4HV"
    ],
    orderId: "11ef1d135548d3a88c6b089e019fd17a"
};

// Using the 'attachLoyaltyReward' function
try {
    const response = await sdk.cart.attachLoyaltyReward(attachLoyaltyRewardRequest);
} catch (error) {
    // Handle errors
}

Return Value and Error Handling

attachLoyaltyReward has the same return value and error handling that is documented for addItem.