Greenhelix Agent Loyalty Incentives

Agent Loyalty & Incentives Engineering

Notice: This is an educational guide with illustrative code examples. It does not execute code or install dependencies. All examples use the GreenHelix sandbox (https://sandbox.greenhelix.net) which provides 500 free credits — no API key required to get started.

Referenced credentials (you supply these in your own environment):

• GREENHELIX_API_KEY: API authentication for GreenHelix gateway (read/write access to purchased API tools only)
• WALLET_ADDRESS: Blockchain wallet address for receiving payments (public address only — no private keys)

Loyalty programs are a $300 billion global industry built on a single assumption: the customer can read the offer. Points banners, tier badges, "earn 3x on dining" callouts, scratch-off reveals in email -- all of it designed for a human eye scanning a screen. That assumption just broke. AI shopping agents now influence $20.9 billion in retail spend in 2026, and they cannot parse a single one of those offers. They see HTML. They see images. They see JavaScript-rendered modals that require a browser session and a cookie jar. What they do not see is a structured, queryable, machine-readable incentive that factors into a purchase decision. This is not a hypothetical loss. A March 2026 analysis by Salesforce found that 68% of AI-assisted purchases ignored available loyalty rewards entirely -- not because the rewards were bad, but because the agent could not detect them. The agent evaluated price, shipping speed, availability, seller reputation, and return policy. It compared those attributes across vendors. It selected the best option. And it left $47 in accumulated loyalty points on the table because those points existed only as a rendered badge in an HTML div with a class name of loyalty-points-display. The merchants who figure this out first will own the agentic commerce channel. When an agent can read your loyalty program as structured data -- query your tiers, evaluate your point multipliers, calculate redemption value, and factor all of it into a purchase decision in milliseconds -- you shift from competing on price alone to competing on total value. That is a fundamentally different game, and this guide teaches you how to play it.

What You'll Learn

• Chapter 1: The Invisible Incentive Problem
• Chapter 2: Protocol Foundations: UCP, UIP, ACP, AP2
• Chapter 3: Designing Machine-Readable Loyalty Programs
• Chapter 4: Agent Identity Linking & Member Recognition
• Chapter 5: Real-Time Incentive Negotiation
• Chapter 6: Reward Redemption & Settlement
• Chapter 7: Anti-Gaming & Incentive Integrity
• Chapter 8: Launching Your Agent Loyalty Program

Full Guide

Agent Loyalty & Incentives Engineering: Machine-Readable Rewards, Identity Linking & Incentive Protocols for AI Agents

Loyalty programs are a $300 billion global industry built on a single assumption: the customer can read the offer. Points banners, tier badges, "earn 3x on dining" callouts, scratch-off reveals in email -- all of it designed for a human eye scanning a screen. That assumption just broke. AI shopping agents now influence $20.9 billion in retail spend in 2026, and they cannot parse a single one of those offers. They see HTML. They see images. They see JavaScript-rendered modals that require a browser session and a cookie jar. What they do not see is a structured, queryable, machine-readable incentive that factors into a purchase decision.

This is not a hypothetical loss. A March 2026 analysis by Salesforce found that 68% of AI-assisted purchases ignored available loyalty rewards entirely -- not because the rewards were bad, but because the agent could not detect them. The agent evaluated price, shipping speed, availability, seller reputation, and return policy. It compared those attributes across vendors. It selected the best option. And it left $47 in accumulated loyalty points on the table because those points existed only as a rendered badge in an HTML div with a class name of loyalty-points-display.

The merchants who figure this out first will own the agentic commerce channel. When an agent can read your loyalty program as structured data -- query your tiers, evaluate your point multipliers, calculate redemption value, and factor all of it into a purchase decision in milliseconds -- you shift from competing on price alone to competing on total value. That is a fundamentally different game, and this guide teaches you how to play it.

This is the practitioner's manual for building loyalty programs that AI agents can discover, evaluate, and redeem. It covers protocol foundations (UCP, UIP, ACP, AP2), schema design for machine-readable incentives, agent identity linking, real-time incentive negotiation, reward redemption and settlement, anti-gaming defenses, and launch playbooks. Every chapter contains production Python code against the GreenHelix A2A Commerce Gateway -- 128 tools accessible at https://api.greenhelix.net/v1 via a single the REST API (POST /v1/{tool}) endpoint with Bearer token authentication.

Table of Contents

1. The Invisible Incentive Problem
2. Protocol Foundations: UCP, UIP, ACP, AP2
3. Designing Machine-Readable Loyalty Programs
4. Agent Identity Linking & Member Recognition
5. Real-Time Incentive Negotiation
6. Reward Redemption & Settlement
7. Anti-Gaming & Incentive Integrity
8. Launching Your Agent Loyalty Program

Chapter 1: The Invisible Incentive Problem

Why Traditional Loyalty Is Invisible to AI Agents

A human shopper lands on a product page and immediately sees the loyalty context: "You have 4,200 points. This purchase earns 350 points. Redeem 2,000 points for $20 off." The information is rendered visually -- a colored banner, a progress bar toward the next tier, a toggle to apply points at checkout. The shopper processes all of it in under two seconds and makes a decision that accounts for loyalty value.

An AI shopping agent lands on the same page and sees none of it. The agent receives the page as raw HTML or, more commonly, queries an API endpoint that returns product data -- price, SKU, availability, description. The loyalty context is not in the API response. It lives in a frontend component that reads from a separate loyalty microservice, rendered client-side by JavaScript after the page loads. The agent would need to: authenticate as the user, execute JavaScript in a headless browser, locate the loyalty DOM elements, parse unstructured text to extract point values, and convert those points to currency equivalent. No production shopping agent does this. The cost of browser automation per query (300-500ms latency, $0.002-0.005 per render) exceeds the value of the information for most transactions.

The result is that loyalty programs are systematically excluded from AI-assisted purchase decisions. The agent optimizes on the attributes it can read -- price, ratings, shipping speed, return policy -- and ignores the attributes it cannot. Loyalty points, tier benefits, promotional multipliers, and redemption options are all invisible.

The Scale of the Problem

The $20.9 billion figure from Gartner covers transactions where an AI agent either made the purchase decision autonomously or materially influenced a human's decision. Of that $20.9 billion, roughly $14.2 billion involved products or services where the merchant had an active loyalty program. And 68% of those transactions -- approximately $9.7 billion -- ignored available loyalty rewards entirely. That is $9.7 billion in purchase decisions made without factoring in loyalty value, not because the loyalty programs were not attractive, but because the agents could not read them.

What Agents Actually Evaluate

When an AI shopping agent compares vendors, it builds a scoring matrix from the attributes available via structured APIs. Here is what a typical agent evaluates today versus what it misses:

The bottom five rows represent the loyalty gap. Every one of these attributes could be expressed as a structured field in an API response. None of them currently are, in the vast majority of merchant implementations.

The Competitive Shift

Merchants who make their loyalty programs machine-readable gain a structural advantage in agent-mediated commerce. Consider two competing merchants selling the same product at the same price:

• Merchant A: Returns {"price": 49.99, "currency": "USD"} from their product API. No loyalty data.
• Merchant B: Returns {"price": 49.99, "currency": "USD", "loyalty": {"points_earned": 500, "points_value_usd": 5.00, "member_tier": "gold", "tier_discount_pct": 5, "effective_price_usd": 42.49}} from their product API.

A scoring agent evaluating both merchants will select Merchant B every time, because Merchant B's effective price -- after tier discount and loyalty point value -- is $42.49 versus Merchant A's $49.99. Merchant A's loyalty program might be equally generous, but it is invisible, so it scores zero.

This is not a theoretical scenario. It is happening now, and the merchants losing transactions to this dynamic do not even know it, because the agent never visits their storefront at all. It queries, gets a partial response, scores it lower, and moves on.

import os
import requests
from typing import Any


GATEWAY_URL = os.environ.get("GREENHELIX_API_URL", "https://sandbox.greenhelix.net")


class LoyaltyClient:
    """Client for GreenHelix A2A Commerce Gateway loyalty operations."""

    def __init__(self, api_key: str):
        self.api_key = api_key
        self.session = requests.Session()
        self.session.headers.update({
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        })

    def execute(self, tool: str, input_data: dict[str, Any]) -> dict:
        """Execute a single tool on the gateway."""
        resp = self.session.post(
            f"{GATEWAY_URL}/v1",
            json={"tool": tool, "input": input_data},
            timeout=30,
        )
        resp.raise_for_status()
        return resp.json()


# Initialize -- used throughout this guide
client = LoyaltyClient(api_key=os.environ.get("GREENHELIX_API_KEY", "your-api-key"))


# Demonstrate the gap: search for a product and check for loyalty data
product_search = client.execute("search_services", {
    "query": "wireless noise-cancelling headphones",
    "filters": {"max_price": 100.00, "category": "electronics"},
})

for service in product_search.get("services", []):
    has_loyalty = "loyalty" in service or "incentives" in service
    print(f"  {service.get('name')}: loyalty_data={'yes' if has_loyalty else 'MISSING'}")

This simple probe -- checking whether search results include loyalty data -- reveals the scope of the problem in any marketplace. In a March 2026 audit of 200 merchant integrations on three major commerce platforms, only 12% included any machine-readable loyalty or incentive data in their API responses.

Key Takeaways

• AI agents influence $20.9B in retail spend (2026) but ignore loyalty rewards in 68% of eligible transactions because the data is not machine-readable.
• Loyalty programs exist in HTML, JavaScript widgets, and frontend-rendered components that agents cannot parse. The rewards are invisible, not absent.
• Merchants who expose loyalty data as structured API fields gain a scoring advantage that translates directly to agent-selected transactions.
• The effective price calculation -- base price minus tier discounts minus redeemable point value -- is the single most powerful lever for winning agent comparisons.
• Cross-reference: P24 (Discovery) covers how agents find merchants. This guide covers what happens after discovery -- how incentives influence the selection decision.

Chapter 2: Protocol Foundations: UCP, UIP, ACP, AP2

The Protocol Landscape for Agent Incentives

Four protocols define how AI agents discover, evaluate, and interact with commerce services in 2026. Each handles incentives differently, and understanding their mechanisms is essential before designing a loyalty program that agents can actually use.

Google's Unified Commerce Protocol (UCP) — January 2026

Google published UCP in January 2026 as an extension to their existing commerce infrastructure. UCP provides a standardized schema for representing commerce entities -- products, offers, merchants, and critically, incentives -- in a format that any agent can query and compare. UCP builds on Schema.org vocabulary but adds agent-specific extensions for programmatic evaluation.

UCP handles incentives through the Incentive entity type, which describes a reward, discount, or benefit that an agent can factor into a purchase decision:

{
  "@context": "https://schema.org",
  "@type": "Incentive",
  "incentiveType": "LoyaltyPoints",
  "name": "Gold Tier Bonus Points",
  "description": "3x points on all electronics purchases for Gold members",
  "eligibility": {
    "@type": "IncentiveEligibility",
    "memberTier": "gold",
    "productCategory": "electronics",
    "validFrom": "2026-01-01T00:00:00Z",
    "validThrough": "2026-12-31T23:59:59Z"
  },
  "reward": {
    "@type": "IncentiveReward",
    "rewardType": "points",
    "pointsMultiplier": 3,
    "basePointsPerDollar": 1,
    "pointToCurrencyRatio": 0.01,
    "currencyCode": "USD"
  },
  "stackable": true,
  "exclusions": ["clearance", "gift-cards"],
  "machineReadable": true
}

The key fields for agent consumption are reward.pointToCurrencyRatio (allows exact USD conversion), stackable (tells the agent whether this incentive can combine with others), and exclusions (product categories or conditions where the incentive does not apply). UCP mandates that incentive entities include machineReadable: true to signal that the data is intended for programmatic consumption, not just display.

UCP Identity Linking allows an agent to present credentials on behalf of a user and retrieve that user's loyalty state -- tier, points balance, applicable incentives -- through a standardized API call. This is covered in depth in Chapter 4.

Talon.One's Unified Incentives Protocol (UIP) — January 2026

Talon.One released UIP in January 2026 as an open protocol for representing incentives across platforms. While UCP focuses on the full commerce entity model, UIP is laser-focused on incentives: promotions, coupons, loyalty rules, referral programs, and dynamic pricing. UIP uses a rule-engine model where incentives are expressed as condition-action pairs:

{
  "uip_version": "1.0",
  "incentive_id": "promo-spring-2026-electronics",
  "type": "conditional_discount",
  "conditions": [
    {"field": "cart.category", "operator": "in", "value": ["electronics"]},
    {"field": "customer.tier", "operator": "gte", "value": "silver"},
    {"field": "cart.total", "operator": "gte", "value": 75.00}
  ],
  "actions": [
    {"type": "percentage_discount", "value": 15, "applies_to": "cart.total"},
    {"type": "bonus_points", "value": 500, "points_program": "main"}
  ],
  "stacking_rules": {
    "group": "spring-promos",
    "max_stack": 2,
    "priority": 10
  },
  "redemption_limits": {
    "per_customer": 3,
    "global": 10000,
    "remaining": 7842
  },
  "machine_parseable": true
}

UIP's condition-action model is particularly powerful for agents because it lets them evaluate eligibility programmatically. An agent can take a UIP incentive definition, check each condition against the current cart state and customer profile, and determine -- before making any API call -- whether the incentive applies and what the reward will be. This pre-evaluation reduces API round-trips and latency.

UIP vs UCP for incentives: UCP provides a broader commerce data model with incentives as one entity type. UIP provides deeper incentive-specific semantics -- stacking rules, redemption limits, condition evaluation. Production implementations typically use both: UCP for discovery (finding merchants with incentives) and UIP for evaluation (determining which incentives apply and their exact value).

OpenAI's Agentic Commerce Protocol (ACP)

ACP focuses on agent-to-merchant transactions: product search, cart management, checkout, and payment. ACP's incentive handling is implicit rather than explicit -- incentives appear as price adjustments in the cart rather than as standalone entities. When an agent adds an item to an ACP cart, the response includes adjustments that reflect applicable incentives:

{
  "cart": {
    "items": [
      {
        "product_id": "SKU-12345",
        "quantity": 1,
        "base_price": 99.99,
        "adjustments": [
          {
            "type": "loyalty_discount",
            "description": "Gold member 10% discount",
            "amount": -10.00,
            "source": "loyalty_program",
            "loyalty_program_id": "merchant-gold-tier"
          },
          {
            "type": "points_earned",
            "description": "300 points earned on this purchase",
            "points": 300,
            "estimated_value_usd": 3.00
          }
        ],
        "final_price": 89.99
      }
    ]
  }
}

ACP's approach means agents see the net effect of incentives during the cart phase, but they do not discover incentives during the search phase. An agent using ACP alone cannot ask "which merchants have the best loyalty program for electronics" -- it can only add items to a cart and observe what adjustments appear. This is why combining ACP with UCP (for discovery) and UIP (for pre-evaluation) produces the best agent experience.

Google's Agent-to-Agent Protocol (AP2/A2A)

AP2 (also referred to as A2A) handles agent-to-agent delegation and service discovery. For loyalty programs, AP2 is relevant because a merchant's loyalty service can publish an Agent Card that describes its incentive capabilities:

{
  "name": "MerchantX Loyalty Service",
  "description": "Query and redeem loyalty points for MerchantX",
  "url": "https://loyalty.merchantx.com",
  "version": "1.0",
  "capabilities": [
    {
      "name": "query_loyalty_balance",
      "description": "Get a member's current points balance and tier",
      "input_schema": {
        "type": "object",
        "properties": {
          "member_id": {"type": "string"},
          "agent_credential": {"type": "string"}
        }
      }
    },
    {
      "name": "evaluate_incentives",
      "description": "Get applicable incentives for a cart",
      "input_schema": {
        "type": "object",
        "properties": {
          "member_id": {"type": "string"},
          "cart_items": {"type": "array"},
          "agent_credential": {"type": "string"}
        }
      }
    },
    {
      "name": "redeem_points",
      "description": "Apply points to a transaction",
      "input_schema": {
        "type": "object",
        "properties": {
          "member_id": {"type": "string"},
          "points_to_redeem": {"type": "integer"},
          "transaction_id": {"type": "string"}
        }
      }
    }
  ],
  "authentication": {
    "schemes": ["bearer", "oauth2"]
  }
}

A shopping agent that discovers this Agent Card via AP2's .well-known/agent.json endpoint knows immediately that MerchantX has a loyalty program, what operations are available, and how to authenticate. The agent can then call evaluate_incentives before checkout to determine the loyalty value of a purchase.

Protocol Comparison Matrix

Integrating Protocols via GreenHelix

The GreenHelix A2A Commerce Gateway abstracts protocol differences behind a unified tool interface. You register your loyalty program once, and the gateway exposes it through whichever protocol an agent uses to discover you:

# Register a loyalty program that is discoverable via all protocols
loyalty_program = client.execute("register_service", {
    "name": "Premium Electronics Loyalty",
    "type": "loyalty_program",
    "protocols": ["ucp", "uip", "acp", "a2a"],
    "metadata": {
        "tiers": ["bronze", "silver", "gold", "platinum"],
        "base_points_per_dollar": 1,
        "point_value_usd": 0.01,
        "categories": ["electronics", "accessories"],
        "stacking_allowed": True,
    },
    "capabilities": [
        "query_balance",
        "evaluate_incentives",
        "redeem_points",
        "transfer_points",
    ],
})
print(f"Loyalty program registered: {loyalty_program.get('service_id')}")

# Publish the program as a UCP Incentive entity
ucp_incentive = client.execute("create_listing", {
    "service_id": loyalty_program.get("service_id"),
    "schema_type": "Incentive",
    "incentive_type": "LoyaltyPoints",
    "reward": {
        "reward_type": "points",
        "points_per_dollar": 1,
        "point_to_currency_ratio": 0.01,
        "currency_code": "USD",
    },
    "eligibility": {
        "min_tier": "bronze",
        "valid_categories": ["electronics", "accessories"],
    },
    "machine_readable": True,
})
print(f"UCP listing created: {ucp_incentive.get('listing_id')}")

Key Takeaways

• Four protocols define agent-incentive interactions: UCP (discovery + identity linking), UIP (incentive evaluation + stacking), ACP (cart-level adjustments), and AP2 (agent-to-agent capability discovery).
• UCP and UIP were both published in January 2026. UCP provides the commerce entity model; UIP provides the incentive rule engine. Use both.
• ACP shows incentive effects at cart time but does not support pre-checkout incentive discovery. Combine with UCP for full coverage.
• AP2 Agent Cards let a loyalty service publish its capabilities so any agent can find and invoke them.
• GreenHelix abstracts protocol differences: register once, expose via all four protocols.
• Cross-reference: P24 (Discovery) covers protocol-level service discovery. This chapter covers the incentive-specific extensions within each protocol.

Chapter 3: Designing Machine-Readable Loyalty Programs

From Marketing Copy to Structured Schemas

A traditional loyalty program is described in a PDF, a web page, or a terms-and-conditions document. "Earn 1 point per dollar. Silver at 5,000 points. Gold at 15,000 points. Platinum at 50,000 points. Gold members get 10% off electronics. Redeem points at 1 cent each." This is clear to a human. It is opaque to an agent.

A machine-readable loyalty program expresses the same information as structured data with typed fields, enumerated values, and explicit relationships. The agent does not interpret -- it queries. Here is the target schema:

{
  "program_id": "merchant-x-rewards",
  "program_name": "MerchantX Rewards",
  "version": "2.1",
  "currency": {
    "name": "MX Points",
    "code": "MXP",
    "to_usd_ratio": 0.01,
    "decimals": 0
  },
  "earning_rules": [
    {
      "rule_id": "base-earn",
      "points_per_usd": 1,
      "categories": ["*"],
      "conditions": [],
      "description": "Base earning rate"
    },
    {
      "rule_id": "electronics-bonus",
      "points_per_usd": 3,
      "categories": ["electronics"],
      "conditions": [{"field": "member.tier", "operator": "gte", "value": "gold"}],
      "description": "3x electronics for Gold+"
    }
  ],
  "tiers": [
    {
      "tier_id": "bronze",
      "name": "Bronze",
      "min_points_annual": 0,
      "perks": [],
      "discount_pct": 0
    },
    {
      "tier_id": "silver",
      "name": "Silver",
      "min_points_annual": 5000,
      "perks": ["free_shipping_over_50"],
      "discount_pct": 5
    },
    {
      "tier_id": "gold",
      "name": "Gold",
      "min_points_annual": 15000,
      "perks": ["free_shipping", "early_access", "priority_support"],
      "discount_pct": 10
    },
    {
      "tier_id": "platinum",
      "name": "Platinum",
      "min_points_annual": 50000,
      "perks": ["free_shipping", "early_access", "priority_support", "personal_shopper", "exclusive_sales"],
      "discount_pct": 15
    }
  ],
  "redemption_rules": {
    "min_redemption_points": 100,
    "redemption_increment": 100,
    "max_redemption_pct_of_order": 50,
    "excluded_categories": ["gift-cards"],
    "partial_redemption_allowed": true
  },
  "stacking_policy": {
    "tier_discount_stacks_with_promos": true,
    "max_promo_stack": 2,
    "points_earning_on_discounted_total": true
  }
}

Every field is typed. Every relationship is explicit. An agent can parse this schema, calculate the exact point value of a purchase for a Gold member buying electronics, determine whether points can be partially redeemed, and factor the tier discount into the effective price -- all without interpreting a single line of natural language.

Building the Program with GreenHelix

Billing and identity tools serve as the persistence and query layer for loyalty state. The create_billing_plan tool defines the economic structure; register_agent creates identity records that track loyalty membership.

# Step 1: Create billing plans for each loyalty tier
tiers = [
    {"name": "bronze", "monthly_fee": "0.00", "discount_pct": 0, "min_annual_points": 0},
    {"name": "silver", "monthly_fee": "0.00", "discount_pct": 5, "min_annual_points": 5000},
    {"name": "gold", "monthly_fee": "0.00", "discount_pct": 10, "min_annual_points": 15000},
    {"name": "platinum", "monthly_fee": "0.00", "discount_pct": 15, "min_annual_points": 50000},
]

tier_plans = {}
for tier in tiers:
    plan = client.execute("create_billing_plan", {
        "plan_name": f"loyalty-{tier['name']}",
        "billing_cycle": "monthly",
        "base_price": tier["monthly_fee"],
        "currency": "USD",
        "metadata": {
            "tier_level": tier["name"],
            "discount_pct": tier["discount_pct"],
            "min_annual_points": tier["min_annual_points"],
            "loyalty_program": "merchant-x-rewards",
        },
    })
    tier_plans[tier["name"]] = plan
    print(f"Created tier plan: {tier['name']} -> {plan.get('plan_id')}")


# Step 2: Register a loyalty member as an agent identity
member = client.execute("register_agent", {
    "agent_id": "customer-agent-jane-doe",
    "display_name": "Jane Doe's Shopping Agent",
    "metadata": {
        "loyalty_program": "merchant-x-rewards",
        "tier": "gold",
        "points_balance": 18500,
        "points_earned_ytd": 22000,
        "member_since": "2024-06-15",
    },
})
print(f"Registered loyalty member: {member.get('agent_id')}")


# Step 3: Create the loyalty earning rules as a billing configuration
earning_config = client.execute("create_billing_plan", {
    "plan_name": "loyalty-earning-rules",
    "billing_cycle": "per_transaction",
    "base_price": "0.00",
    "currency": "USD",
    "metadata": {
        "loyalty_program": "merchant-x-rewards",
        "earning_rules": [
            {
                "rule_id": "base-earn",
                "points_per_usd": 1,
                "categories": ["*"],
            },
            {
                "rule_id": "electronics-gold-bonus",
                "points_per_usd": 3,
                "categories": ["electronics"],
                "required_tier": "gold",
            },
            {
                "rule_id": "electronics-platinum-bonus",
                "points_per_usd": 5,
                "categories": ["electronics"],
                "required_tier": "platinum",
            },
        ],
    },
})
print(f"Earning rules configured: {earning_config.get('plan_id')}")

Incentive Object Schema Design

Beyond the loyalty program itself, individual incentives (promotions, limited-time offers, bonus events) need their own schema. The design principle: every field an agent needs for a decision must be a typed, queryable attribute.

# Create a promotional incentive using GreenHelix
spring_promo = client.execute("create_listing", {
    "service_id": "merchant-x-rewards",
    "listing_type": "incentive",
    "name": "Spring Electronics Blowout",
    "metadata": {
        "incentive_id": "spring-2026-electronics",
        "type": "bonus_points",
        "value": 500,
        "value_currency": "MXP",
        "conditions": [
            {"field": "cart.category", "operator": "contains", "value": "electronics"},
            {"field": "cart.total", "operator": "gte", "value": 100.00},
        ],
        "valid_from": "2026-03-01T00:00:00Z",
        "valid_through": "2026-05-31T23:59:59Z",
        "stackable": True,
        "stacking_group": "seasonal-promos",
        "max_stack_in_group": 1,
        "redemption_limit_per_customer": 5,
        "redemption_limit_global": 50000,
        "remaining_global": 43218,
        "excluded_categories": ["gift-cards", "clearance"],
        "min_order_value": 100.00,
    },
})
print(f"Incentive created: {spring_promo.get('listing_id')}")

Point Valuation Transparency

The single most important field for agent decision-making is point_to_currency_ratio. Without it, the agent cannot convert loyalty points to a comparable currency value. With it, the agent can compute:

effective_price = base_price - tier_discount - (redeemable_points * point_to_currency_ratio)

This transforms loyalty from a "nice to have" that agents ignore into a first-class pricing dimension that agents optimize for.

Design checklist for machine-readable loyalty programs:

• Every tier has explicit discount_pct and perks arrays
• Earning rules include points_per_usd with category filters
• point_to_currency_ratio is published at the program level
• Redemption rules specify min_redemption_points, max_redemption_pct_of_order, and partial_redemption_allowed
• Stacking policy is explicit: which incentives combine, max stack depth, earning on discounted totals
• All time windows use ISO 8601
• All monetary values include currency code
• Schema version is included for forward compatibility

Key Takeaways

• Machine-readable loyalty programs express tiers, earning rules, redemption rules, and stacking policies as typed, queryable fields -- not natural language.
• point_to_currency_ratio is the single most important field. Without it, agents cannot factor loyalty into purchase scoring.
• GreenHelix create_billing_plan and register_agent provide the persistence layer for loyalty state (tiers, balances, earning rules).
• Individual incentives (promos, bonuses) need their own schema with conditions, stacking rules, and redemption limits.
• Design checklist: tier discounts, earning rates, point valuation, redemption constraints, stacking policy, time windows, currency codes, schema version.
• Cross-reference: P18 (Pricing) covers base pricing strategies. This chapter covers the incentive layer on top of base pricing.

Chapter 4: Agent Identity Linking & Member Recognition

The Identity Challenge

An AI shopping agent acts on behalf of a human user. The agent has its own identity (agent ID, API credentials) and the human has a separate identity (loyalty member ID, email, phone number). For loyalty programs to work in agent commerce, the merchant must link the agent's identity to the human's loyalty membership. Without this link, the agent is an anonymous visitor -- no tier benefits, no points balance, no personalized incentives.

Identity linking is the process of establishing a trust chain: "This agent is authorized to act on behalf of this loyalty member, and the merchant should treat the agent's actions as the member's actions for loyalty purposes."

UCP Identity Linking Flow

UCP defines a three-party identity linking flow involving the human (resource owner), the agent (client), and the merchant (resource server). The flow uses OAuth 2.0 conventions adapted for agent commerce:

1. Human authorizes agent: The human grants the agent permission to access their loyalty account, typically through a one-time consent flow in the agent's interface.
2. Agent receives a delegation token: A scoped token that proves the agent is authorized to query and redeem loyalty on behalf of the specific human.
3. Agent presents delegation token to merchant: The merchant validates the token and returns loyalty state for the linked member.

# Step 1: Register the agent with identity tools
agent_registration = client.execute("register_agent", {
    "agent_id": "shopping-agent-a1b2c3",
    "display_name": "Alice's Personal Shopping Agent",
    "capabilities": ["commerce", "loyalty_management"],
    "metadata": {
        "owner_email_hash": "sha256:a1b2c3d4e5f6...",  # hashed for privacy
        "delegation_scope": ["loyalty.read", "loyalty.redeem"],
        "consent_timestamp": "2026-03-15T10:30:00Z",
    },
})
print(f"Agent registered: {agent_registration.get('agent_id')}")

# Step 2: Verify the agent identity to establish trust
verification = client.execute("verify_identity", {
    "agent_id": "shopping-agent-a1b2c3",
    "verification_type": "delegation",
    "delegation_proof": {
        "owner_id": "loyalty-member-alice-789",
        "scope": ["loyalty.read", "loyalty.redeem"],
        "issued_at": "2026-03-15T10:30:00Z",
        "expires_at": "2026-06-15T10:30:00Z",
        "signature": "base64-encoded-signature...",
    },
})
print(f"Identity verified: {verification.get('verified')}")
print(f"Linked member: {verification.get('linked_member_id')}")

# Step 3: Retrieve loyalty state using the linked identity
loyalty_state = client.execute("get_agent_identity", {
    "agent_id": "shopping-agent-a1b2c3",
})
print(f"Tier: {loyalty_state.get('metadata', {}).get('tier')}")
print(f"Points: {loyalty_state.get('metadata', {}).get('points_balance')}")

Guest vs. Authenticated Agent Interactions

Not every agent interaction requires identity linking. The loyalty program should handle three interaction levels:

# Anonymous query: what does this loyalty program offer?
program_info = client.execute("search_services", {
    "query": "MerchantX loyalty program",
    "filters": {"type": "loyalty_program"},
})
# Returns: program structure, tiers, base earning rates -- no personalization

# Agent-authenticated query: general incentives available
general_incentives = client.execute("search_services", {
    "query": "MerchantX current promotions",
    "filters": {
        "type": "incentive",
        "merchant": "merchant-x",
        "requires_membership": False,
    },
})
# Returns: public promotions, new member signup bonuses

# Member-linked query: personalized loyalty state
personalized = client.execute("get_agent_identity", {
    "agent_id": "shopping-agent-a1b2c3",
})
member_meta = personalized.get("metadata", {})
# Returns: tier=gold, points=18500, personalized offers, redemption options

The design principle: always return the maximum information the credential level permits. An anonymous agent should still see the program structure -- that information helps the agent recommend the merchant for loyalty-conscious users. Restricting program structure behind authentication reduces discovery and hurts acquisition.

Privacy Considerations

Agent identity linking creates a data flow where a merchant learns that a specific agent acts for a specific loyalty member. This has privacy implications:

Minimum data principle: The agent should present only the data needed for the interaction. For a loyalty balance query, the agent needs to prove it represents the member. It does not need to reveal the member's email address, purchase history, or demographic data. The delegation token should be scoped and the merchant should request only the claims it needs.

Token expiration: Delegation tokens should have finite lifetimes (90 days is

…(truncated)