Product Rules
Product rules enable dynamic, event-driven offer flows including upsells, cross-sells, second chance offers, and complex multi-product configurations. This structure provides partners with a powerful, declarative way to define product relationships and conditional visibility rules.
Structure
The product_rules array is returned in the Create Offer response and defines how products should be displayed, grouped, and made interactive based on user actions.
Root Object
{
"product_rules": [
{
"slug": "group_id",
"product_ids": ["product_id_1"],
"initial_state": "show",
"min_select": 1,
"max_select": 1,
"events": []
}
]
}Field Definitions
Group Object
slug
string
Yes
Unique slug for the ProductRules. Used for event targeting and reference in UI/booking
product_ids
array<string>
Yes
Array of product/quote IDs included in this group
initial_state
enum
Yes
Initial visibility/interaction state: "show", "hide", or "disable"
min_select
integer
Yes
Minimum number of products the customer must select from this group (0 = optional)
max_select
integer
Yes
Maximum number of products the customer can select from this group
events
array<Event>
No
Array of event-driven rules. Can be empty or omitted for terminal groups
Event Object
on
enum
Yes
User action that triggers this event: "select", "deselect", "accept", or "decline"
action
enum
Yes
Action to perform on target group: "show", "hide", "enable", or "disable"
target_rule
string
Yes
ProductRules Slug to apply action to (must reference existing ProductRules)
Event Triggers
select
User selects product(s) meeting min_select
Show upsells immediately when user picks a product
deselect
User's selection drops below min_select
Hide/cleanup dependent groups when selection removed
accept
User explicitly accepts the group
Show next step after accepting Offer
decline
User explicitly declines the entire group
Show second chance Offer when user opts out
Event Actions
show
Make group visible and interactive
Reveal upsell after main product selected
hide
Make group invisible
Hide alternative when user makes selection
enable
Make group interactive (if disabled)
Unlock addon after main product accepted
disable
Make group non-interactive (grayed out)
Disable competing option in XOR scenario
Initial State
show
Visible and interactive from start
Primary Offer, always available options
hide
Not visible until triggered by event
Upsells, second chance Offer
disable
Visible but non-interactive until enabled
Show addon but require main product first
Common use cases
Single Product
Simple single product Offer with no events.
Use Case: Standard single product offer where user must select the product to proceed.
Implementation:
Display the product immediately
User must select exactly 1 product
No conditional behavior
Multiple Products (XOR - One-of)
User must pick exactly one of multiple products.
Use Case: Tiered pricing where user selects one plan from multiple options (e.g., Basic vs Premium, Bronze vs Silver vs Gold).
Implementation:
Display all products in the group simultaneously
User must select exactly 1 product
Typically rendered as radio buttons or tabs
Multiple Product Rules (Second Chance Offer)
Show alternative product when user declines primary offer.
Use Case: Offer a lower-priced alternative when user declines the primary offer to maximize conversion.
Flow:
User sees primary offer (premium product at higher price)
User clicks "No thanks" →
declineevent firesPrimary group hides, second chance group shows (budget product at lower price)
If user changes mind and selects primary → second chance hides
Example with Real Data:
Business Rules & Validation
Event Processing Rules
Events fire only on user interactions, not on programmatic state changes from other events
Events are processed synchronously in the order they appear in the
eventsarrayState changes are idempotent - showing a visible group or hiding a hidden group has no effect
Cleanup must be explicit - system does not auto-reverse actions; partners must configure bidirectional events
Best Practices
Use
initial_state: "show"for primary offers - Always display the main offer immediatelyUse
initial_state: "hide"for secondary offers - Hide upsells, cross-sells, and second chance offers until triggeredConfigure bidirectional events - If
selectshows a group,deselectshould hide itProvide rule-specific content - Use
content.extrasto customize messaging for second chance offersSet appropriate min/max values - Use
min_select: 1, max_select: 1for required single selectionHandle opt-out - Record opt-out when user declines all visible groups
Last updated
Was this helpful?

