Brand specific loyalty program tracking

[JTPets]

I am making a request to have the ability to track "frequent buyer" programs on my pos as part of square loyalty.

Many of my brands offer buy 12 get the 13th free and I have track them locally on paper cards. There are third party programs like Astro Loyalty and EtailPet that have this functionality to digitize this process but they are not compatible with square currently.

I would love to have the ability to integrate with this programs or have something on the square loyalty system that would let me mark specific items to track on a frequent buyer program.

The program would allow for tracking of multiple Products, I would expect them to work similar to discounts where I define the items that work, how many they have to buy and what the reward is at the end of it.

I would like to do this ALONG side my points program as these are seperatly funded by the vendor. I also need the ability to export quickly the transaction records of the items purchased to earn the reward.

This is an ability that is needed for many using Square Retail & Square Loyalty

[JTPets]

@kristen here is how I am attempting to bridge this gap currently with my own app if this helps drive some innovation internally 🙂

Frequent Buyer Program - Technical Flow

1. CUSTOMER IDENTIFICATION

Order comes in via webhook (order.payment.completed)
    ↓
Get customer ID (priority order):
    1. order.customer_id (most reliable - POS identified customer)
    2. tender.customer_id (fallback - customer on payment)
    3. Square Loyalty API lookup by order_id (last resort)
    ↓
Store: square_customer_id (UUID) - never fuzzy/timestamp matching

2. ITEM MATCHING

For each line_item in order:
    ↓
Query: Does variation_id exist in loyalty_qualifying_variations?
    ↓
YES → Get associated offer (e.g., "Buy 12 Astro 12oz, Get 1 Free")
NO  → Skip (not a qualifying item)

Key: Explicit variation IDs only - no brand/category inference

3. QUANTITY TRACKING

Record purchase in loyalty_purchase_events:
    - square_customer_id
    - variation_id  
    - quantity
    - window_end_date (purchase_date + 12 months)
    ↓
Calculate progress:
    SELECT SUM(quantity) FROM loyalty_purchase_events
    WHERE square_customer_id = X
      AND offer_id = Y
      AND window_end_date >= TODAY  -- Rolling window
      AND reward_id IS NULL         -- Not yet locked to a reward
    ↓
If SUM >= required_quantity (e.g., 12):
    → Create reward with status = 'earned'
    → Lock those purchase events to this reward_id

4. REWARD ISSUANCE (Square Objects)

When reward earned, create 3 Square objects:

1. CUSTOMER GROUP (one member only)
   POST /v2/customers/groups
   → Add only this customer to the group
   
2. CATALOG DISCOUNT  
   - 100% off
   - maximum_amount_money = highest qualifying item price
   
3. PRICING RULE (ties it together)
   - discount_id = the discount above
   - match_products_id = qualifying variation IDs
   - customer_group_ids_any = [the group above]  ← ONLY THIS CUSTOMER

5. HOW IT AUTO-APPLIES AT POS

Customer checks out at Square POS
    ↓
Square checks: Is customer in any groups?
    ↓
YES → Check pricing rules for those groups
    ↓
Pricing rule matches:
    - Customer in group? ✓
    - Item in product set? ✓
    ↓
100% discount auto-applies (capped at max item price)

6. REDEMPTION DETECTION

Webhook: order.completed with discounts
    ↓
For each discount in order:
    Does catalog_object_id match our square_discount_id?
    ↓
YES → Mark reward as 'redeemed'
    → Cleanup: Remove customer from group, delete discount objects

---

Square API Objects Created Per Reward

Customer Group:     "FBP Reward #123: Astro 12oz"
                    └─ Members: [1 customer only]

Catalog Discount:   "zz_Loyalty: FREE Astro 12oz"  
                    └─ 100%, max $X.XX

Pricing Rule:       Links discount + products + customer group
                    └─ Auto-applies when all 3 match

[fourleggers]

I'm adding to this request. I've been looking at other point of sales, ONLY for the sole reason that Square doesn't integrate with Astro. Please strongly consider adding this feature!

[JTPets]

@fourleggers if you are technically inclined, i have a prototype I am testing for this in my github that creates and tracks this for me now and connects to square for auto redemption on login, i host it on a pi

[fourleggers]

@JTPets  I’m fairly tech savvy, I’d like to think I could probably figure it out! 🤞