qualifications

Find redeemables (vouchers, promotions, campaigns) applicable to given customer.

⚠️ CRITICAL: The 'customer' parameter is ALWAYS REQUIRED - never call this tool without it!

Returns list of available discounts, vouchers, and promotions based on customer profile and selected scenario for targeted marketing and cart optimization.

Parameters:

• customer: 🔴 MANDATORY - Customer identification and profile data. This parameter is REQUIRED for every call.

• scenario: 🔴 MANDATORY - Qualification scope determining which redeemables to evaluate (optional, defaults to ALL)

Customer Object Structure: Required (one of):

• id: Customer ID with 'cust_' prefix (e.g., "cust_abc123")

• source_id: External customer identifier Optional:

• metadata: Dict of custom customer attributes for rule matching

Scenario Guide (Choose Based on Use Case):

CUSTOMER-FOCUSED:

• ALL: Scenario that returns redeemables available for the customer

• CUSTOMER_WALLET: returns vouchers applicable to the customer's cart based on the vouchers assigned to the customer's profile

• AUDIENCE_ONLY: returns all vouchers, promotion tiers, and campaigns available to the customer. It validates the rules based on the customer profile only.

PRODUCT-FOCUSED (require product context in other tools):

• PRODUCTS: returns all promotions available for the products (when a discount is defined to be applied to the item or when the item is required in the validation rule)

• PRODUCTS_DISCOUNT: returns all promotions available for products when a discount is defined as applicable to specific item(s).

• PRODUCTS_BY_CUSTOMER: returns all promotions available for a customer for the products (when a discount is defined to be applied to the item or when the item is required in the validation rule).

• PRODUCTS_DISCOUNT_BY_CUSTOMER: returns all promotions available for a customer for products when a discount is defined as applicable to specific item(s).

ADVANCED:

• PROMOTION_STACKS: returns the applicable promotion stacks

Common Usage Patterns:

• Customer wallet check: Use CUSTOMER_WALLET

• Matching redeemables to given context: Use ALL

• Customer-based targeting: Use AUDIENCE_ONLY

✅ CORRECT Examples (always include customer):

• qualifications(customer={"id": "cust_abc123"}, scenario="CUSTOMER_WALLET")

• qualifications(customer={"source_id": "user_456", "metadata": {"tier": "gold"}})

• qualifications(customer={"id": "cust_xyz789"}, scenario="ALL")

• qualifications(customer={"id": "cust_abc123"}) # scenario defaults to ALL

🚫 WRONG Examples (missing required customer parameter):

• qualifications() # ❌ NEVER do this - customer is required

• qualifications(scenario="CUSTOMER_WALLET") # ❌ NEVER do this - customer is required

• qualifications(scenario="ALL") # ❌ NEVER do this - customer is required

💡 Remember: ALWAYS provide the customer parameter - it's never optional!

Returns: JSON object containing:

• redeemables: Array of applicable vouchers/promotions

• Each redeemable includes: id, name, discount details, validation rules

• Scenario-specific filtering applied

Raises:

• ToolError: If customer missing required fields or invalid scenario