| find_customerA | Find a customer by email or ID and return complete customer object. Lookup Behavior: ID lookup: Direct retrieval by customer ID (faster, more reliable) Email lookup: Searches customers and returns first match (case-insensitive) Returns complete customer object including loyalty summary when available
Parameters: Validation Rules: Exactly one parameter (email OR id) must be provided Email must be valid email format ID must start with 'cust_' prefix
Examples: Returns:
JSON object containing complete customer data including: id, source_id, email, name metadata (custom attributes) loyalty summary (points, tier, etc.) when available creation and update timestamps
Raises: |
| get_campaignA | Retrieve detailed information about a specific campaign by its ID. Returns complete campaign configuration including discount details, validation rules,
voucher settings, and current status for campaign analysis and management. Enhanced Features: Automatically fetches and processes validation rules for detailed rule analysis Provides both raw validation_rules_assignments and processed assigned_validation_rules Includes complete campaign hierarchy and voucher generation settings
Parameters: Identifier Requirements: Campaign ID: Must start with 'camp_' prefix (e.g., "camp_X26jzR8ObD55nlwOUcr63Px0") ID must correspond to existing campaign
Validation Rules: Examples: Returns:
JSON object containing complete campaign details including: Core Campaign Information: id: Campaign system identifier (e.g., "camp_X26jzR8ObD55nlwOUcr63Px0") name: Human-readable campaign name (e.g., "Burger Deluxe Family Campaign") campaign_type: Campaign type ("DISCOUNT_COUPONS", "GIFT_VOUCHERS", "LOYALTY_PROGRAM", "PROMOTION") type: Campaign generation type ("STATIC", "DYNAMIC") active: Boolean campaign status object: Always "campaign"
Campaign Configuration: auto_join: Boolean automatic customer enrollment setting join_once: Boolean single enrollment restriction use_voucher_metadata_schema: Boolean voucher metadata schema usage protected: Boolean protection status against modifications
Voucher Template Settings: Campaign Status and Statistics: vouchers_count: Total vouchers generated in campaign creation_status: Campaign creation status ("DONE", "IN_PROGRESS", "FAILED") vouchers_generation_status: Voucher generation status ("DONE", "IN_PROGRESS", "FAILED") created_at: Campaign creation timestamp (ISO 8601)
Access and Categorization: access_settings_assignments: Access control assignments with data array and total count category_id: Campaign category identifier (null if uncategorized) categories: Array of campaign categories (empty if uncategorized)
Validation Rules (Enhanced): Use Cases: Analyze campaign configuration and discount mechanics Understand validation rules and product requirements Check campaign status and voucher generation progress Review campaign hierarchy and settings Get complete campaign blueprint for duplication
Raises: |
| list_campaignsA | List all campaigns with basic information for campaign resolution. Primary Use Case:
Resolve campaign ID when user provides only campaign name or partial name.
Returns comprehensive list of all campaigns for further name-based matching. Behavior: Retrieves all campaigns (up to 1000) in single request No filtering - returns complete campaign catalog Avoid multiple calls as results are comprehensive
No Parameters Required:
This tool requires no input parameters and returns all available campaigns. Returns:
JSON array of campaign objects, each containing: id: Campaign identifier starting with 'camp_' name: Human-readable campaign name campaign_type: Campaign type (e.g., 'DISCOUNT_COUPONS', 'GIFT_VOUCHERS') created_at: ISO 8601 creation timestamp
Example Output:
[
{
"id": "camp_abc123def456",
"name": "Summer Sale 2025",
"campaign_type": "DISCOUNT_COUPONS",
"created_at": "2025-01-01T00:00:00.000Z"
},
{
"id": "camp_xyz789ghi012",
"name": "Holiday Promotions",
"campaign_type": "GIFT_VOUCHERS",
"created_at": "2024-12-01T00:00:00.000Z"
}
] Usage Pattern: Call list_campaigns() to get all campaigns Match user's campaign name against returned names Use resolved campaign ID for other campaign tools
Limitations: Maximum 1000 campaigns returned No filtering options available Results sorted by creation date
|
| get_campaign_summaryA | Retrieve comprehensive analytics summary for a specific campaign. Returns detailed statistics including validations, redemptions, publications, and
campaign-type-specific metrics for performance analysis. Parameters: campaign_id: Valid campaign identifier with 'camp_' prefix start_date: Optional analysis period start (ISO 8601 date format) end_date: Optional analysis period end (ISO 8601 date format)
Date Parameter Rules: Both start_date and end_date must be provided together or omitted together Empty strings are invalid - use null/None for no date filtering Omitting both dates returns full campaign period summary Date format: YYYY-MM-DD (e.g., "2025-01-01")
Examples: get_campaign_summary(campaign_id="camp_aPVb581gdJ1xF6esnDnDocVK") get_campaign_summary(
campaign_id="camp_aPVb581gdJ1xF6esnDnDocVK",
start_date="2025-01-01",
end_date="2025-01-31"
)
Examples of bad usage: Returns:
JSON object containing campaign analytics including: validations: Validation attempt statistics redemptions: Successful redemption counts and values publications: Voucher distribution metrics campaign_type specific metrics (varies by campaign type) date range information performance indicators
Raises: |
| get_voucherA | Retrieve detailed information about a specific voucher by its code or ID. Returns complete voucher configuration including discount details, usage limits,
validation rules, and current status for voucher analysis and management. Enhanced Features: Automatically fetches and processes validation rules for detailed rule analysis Provides both raw validation_rules_assignments and processed validation_rules Includes QR/barcode assets for voucher display and distribution
Parameters: Identifier Types: Voucher Code: Human-readable code with alphanumeric and special characters (e.g., "WELCOME10", "SAVE20", "TEST-ABC") Voucher ID: System identifier with 'v_' prefix (e.g., "v_abc123def456")
Validation Rules: Examples: Returns:
JSON object containing complete voucher details including: Core Voucher Information: id: Voucher system identifier (e.g., "v_4dyaDRCMD0bUDNv47pDqnGlCJhSVWtnT") code: Human-readable voucher code (e.g., "DELUXE-SG63RY") type: Voucher type ("DISCOUNT_VOUCHER", "GIFT_VOUCHER", "LOYALTY_CARD") active: Boolean voucher status object: Always "voucher"
Discount Configuration: discount: Discount details with type and value (e.g., {"type": "PERCENT", "percent_off": 25}) gift: Gift voucher amount (null for discount vouchers) loyalty_card: Loyalty card details (null for regular vouchers)
Validity and Constraints: start_date, expiration_date: Validity period (ISO 8601 or null) validity_timeframe, validity_hours: Time-based restrictions validity_day_of_week: Array of valid weekdays (1=Monday, 7=Sunday)
Usage Tracking: redemption: Usage statistics with quantity limits and current usage publish: Publication information and count holder_id: Customer ID if voucher is assigned
Campaign and Categorization: campaign, campaign_id: Parent campaign information (null for standalone vouchers) category, category_id, categories: Voucher categorization
Validation Rules (Enhanced): Additional Data: metadata: Custom voucher attributes additional_info: Extra voucher information assets: QR code and barcode URLs for voucher display is_referral_code: Boolean indicating referral voucher created_at, updated_at: ISO 8601 timestamps
Use Cases: Verify voucher validity and details Check voucher usage and limits Analyze voucher configuration and discount mechanics Understand validation rules and product requirements Check voucher ownership and assignment Get QR/barcode assets for voucher display
Raises: |
| get_promotion_tierA | Retrieve detailed information about a specific promotion tier by its ID. Returns complete promotion tier configuration including discount rules,
validation criteria, and metadata for promotion analysis and management. Enhanced Features: Automatically fetches and processes validation rules for detailed rule analysis Provides both raw validation_rules_assignments and processed assigned_validation_rules Includes complete promotion tier hierarchy and action settings
Parameters: Identifier Requirements: Promotion Tier ID: Must start with 'promo_' prefix (e.g., "promo_abc123def456") ID must correspond to existing promotion tier
Validation Rules: Examples: Returns:
JSON object containing complete promotion tier details including: Core Promotion Tier Information: id: Promotion tier system identifier (e.g., "promo_abc123def456") name: Human-readable tier name banner: Display banner text for promotion object: Always "promotion_tier"
Discount Configuration: Promotion Settings: hierarchy: Tier ordering and priority within campaign campaign: Parent campaign information campaign_id: Parent campaign identifier summary: Promotion tier summary and statistics
Validation Rules (Enhanced): Additional Data: Use Cases: Analyze promotion tier configuration and discount mechanics Understand validation rules and eligibility requirements Review promotion tier hierarchy and priority Get complete promotion tier blueprint for management Check promotion tier status and performance
Raises: |
| qualificationsA | 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: 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: |
| get_best_dealsA | Find top 5 best deal promotions for customer's order with validation analysis. Analyzes order items against available promotions to identify highest-value deals.
Returns promotions with validation rules - some may be partially valid, requiring
additional items or changes to qualify for the discount. Use Case: Upselling and cross-selling optimization Identify best promotions for current cart Determine what customer needs to add/change for qualification Optimize cart value through targeted recommendations
Important: This tool is specialized for order-based promotion analysis.
Do not combine with 'qualifications' tool as they serve different purposes. Parameters:
Parameters: customer: š“ MANDATORY - Customer identification and profile data. This parameter is REQUIRED for every call. order: š“ MANDATORY - Order with items list for promotion matching and analysis. This parameter is REQUIRED for every call.
Order Item Configuration:
Each item can be specified in multiple ways: By Product ID (most precise):
{"product_id": "prod_abc123", "price": 2000, "quantity": 1} By Source ID (requires related_object):
{"source_id": "special-meal", "related_object": "product", "price": 3000, "quantity": 1} Generic with metadata (for product collection matching):
{"quantity": 2, "product": {"metadata": {"category": "Electronics"}}} Price-less items (uses catalog price):
{"source_id": "drink", "related_object": "product", "quantity": 1}
Pricing Rules: All prices in cents (2000 = $20.00, 150 = $1.50) Items without price use product catalog pricing Quantity must be positive integer
Examples: get_best_deals(
customer={"id": "cust_abc123"},
order={
"items": [
{"product_id": "prod_112e92ce9a7cf5b1d8", "price": 2000, "quantity": 1},
{"source_id": "special-meal", "related_object": "product", "price": 3000, "quantity": 1}
]
}
)
Example of invalid usage: Returns:
JSON array of up to 5 promotion objects, each containing: id: Promotion identifier result: Qualification status (APPLICABLE, PARTIALLY_APPLICABLE, etc.) is_applicable: Boolean indicating if given incentive meets all validation rules redeemable_details: Promotion information (banner, description, campaign) validation_rules: Array of validation requirements with status resolved_order: Order with calculated totals and promotion effects if incentive is applicable
Each validation rule includes: validation_rules_definition: Rule logic and requirements validation_status: Current compliance status validation_omitted_sub_rules: Missing requirements for qualification
See "Validation Rules Structure" section in server instructions for detailed rule format documentation Raises: |
| estimate_loyalty_pointsA | Estimate how many loyalty points a customer will earn for a given order. CRITICAL: customer and order are ALWAYS required, even when loyalty_card is provided.
The loyalty_card only identifies the campaign ā it does NOT replace customer or order. Calculates the estimated number of points a customer will receive in a
loyalty campaign based on the campaign's earning rules and the provided order. Important Limitations: Returns an estimation, not a precise point value Works only for "Order paid" earning rules For campaigns with tiers, mappings, and multiple earning rules, the actual
points may differ as the customer may change tiers during final calculation
Use Case: Show loyalty point banners in checkout flows Display estimated points before order placement Motivate customers by showing point rewards for their current cart Combine with get_best_deals for comprehensive loyalty estimations
Campaign Identification (at least one required): loyalty_card: Loyalty card code or voucher ID ā resolves the campaign ID only. campaign_id: Direct loyalty campaign ID ā use when already known. Both can be provided: the tool verifies the loyalty card belongs to the given campaign.
Parameters: customer: REQUIRED - Customer identification (id or source_id required). Always provide. order: REQUIRED - Order details with source_id for existing orders or amount for estimation. Always provide. loyalty_card: Loyalty card code or voucher ID (at least one of loyalty_card/campaign_id required) campaign_id: Loyalty campaign ID with 'camp_' prefix (at least one of loyalty_card/campaign_id required)
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
Order Object Structure:
Required (one of): source_id: Existing order ID assigned by Voucherify (e.g., "ord_34567890") amount: Total order amount in cents (e.g., 5000 for $50.00)
Optional: metadata: Dict of custom order attributes
Pricing Rules: Examples: estimate_loyalty_points(
loyalty_card="Loyalty-ZC4Vg",
customer={"source_id": "customer123"},
order={"amount": 5000}
) estimate_loyalty_points(
campaign_id="camp_XXXXXXXXX",
customer={"id": "cust_abc123"},
order={"source_id": "ord_34567890"}
) estimate_loyalty_points(
loyalty_card="Loyalty-ZC4Vg",
campaign_id="camp_XXXXXXXXX",
customer={"source_id": "customer123"},
order={"amount": 8000, "metadata": {"source": "checkout"}}
)
Returns:
JSON object containing: campaign: Campaign details (id, name, object) points_estimation: Estimated number of points the customer will earn
Example Response:
{
"campaign": {
"id": "camp_XXXXXXXXX",
"name": "Loyalty-campaign",
"object": "campaign"
},
"points_estimation": 51
} Error Cases: 400: Campaign doesn't allow auto-join for non-members, inactive campaign,
inactive loyalty card, or missing customer/order objects 404: Campaign ID or loyalty card not found
Raises: |
| list_productsA | List products with optional filtering and pagination. Returns paginated product catalog with flexible filtering capabilities for
product discovery, inventory analysis, and catalog management. Parameters: filters: Optional filter criteria using field paths and operators page: Optional page number (default: 1, provide only for page 2+)
Filter Structure:
{
"field_path": {
"conditions": {
"$operator": "value"
}
}
} Supported Fields: name: Product name (string) source_id: External product identifier (string) price: Product price in cents (integer) created_at: Creation date (ISO 8601) metadata.: Custom metadata fields (various types)
Operators by Field Type:
String fields (name, source_id, metadata): $is, $is_not: Exact match $contains, $starts_with: Partial match $in: Match any from array
Numeric fields (price, numeric metadata): $more_than, $less_than: Comparison $more_than_equal, $less_than_equal: Inclusive comparison
Date fields (created_at): Pricing Rules: Examples: list_products() # All products, page 1 list_products(page=2) # All products, page 2 list_products(
filters={
"metadata.category": {"conditions": {"$is": "Electronics"}},
"price": {"conditions": {"$more_than": 5000}}
}
) list_products(
filters={
"name": {"conditions": {"$contains": "Premium"}},
"created_at": {"conditions": {"$after": "2025-01-01"}}
},
page=3
)
Returns:
JSON object containing: products: Array of product objects with full details total: Total number of matching products has_more: Boolean indicating if more pages available Each product includes: id, name, source_id, price, metadata, timestamps
Pagination: Raises: |
