voucherify-core-mcp

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:

• All amounts in cents (5000 = $50.00, 150 = $1.50)

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:

• ToolError: If parameters invalid, campaign not found, or customer not eligible

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:

• email: Valid email address for customer search

• id: Customer identifier with 'cust_' prefix for direct lookup

Validation Rules:

• Exactly one parameter (email OR id) must be provided

• Email must be valid email format

• ID must start with 'cust_' prefix

Examples:

• find_customer(email="john.doe@example.com")

• find_customer(id="cust_abc123def456")

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:

• ToolError: If both/neither parameters provided, customer not found, or invalid format

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:

1. By Product ID (most precise): {"product_id": "prod_abc123", "price": 2000, "quantity": 1}

2. By Source ID (requires related_object): {"source_id": "special-meal", "related_object": "product", "price": 3000, "quantity": 1}

3. Generic with metadata (for product collection matching): {"quantity": 2, "product": {"metadata": {"category": "Electronics"}}}

4. 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:

• get_best_deals()

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:

• ToolError: If customer missing required fields or order structure invalid

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:

• campaign_id: Campaign identifier for lookup

Identifier Requirements:

• Campaign ID: Must start with 'camp_' prefix (e.g., "camp_X26jzR8ObD55nlwOUcr63Px0")

• ID must correspond to existing campaign

Validation Rules:

• Campaign ID must be valid and existing

• ID format is case-sensitive

Examples:

• get_campaign(campaign_id="camp_X26jzR8ObD55nlwOUcr63Px0")

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:

• voucher: Complete voucher template configuration:

  • type: Voucher type ("DISCOUNT_VOUCHER", "GIFT_VOUCHER", etc.)

  • discount: Discount configuration (e.g., {"type": "PERCENT", "percent_off": 3})

  • redemption: Usage limits (e.g., {"quantity": null} for unlimited)

  • code_config: Code generation settings:

    • length: Code length (e.g., 8)

    • charset: Character set for code generation

    • pattern: Code pattern (e.g., "########")

  • is_referral_code: Boolean referral code status

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):

• assigned_validation_rules: Processed validation rules with detailed conditions (added by this tool) See "Validation Rules Structure" section in server instructions for complete field documentation

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:

• ToolError: If campaign not found or invalid campaign ID format

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:

• get_campaign_summary(campaign_id="camp_aPVb581gdJ1xF6esnDnDocVK", start_date="", end_date="")

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:

• ToolError: If campaign not found, invalid date format, or mismatched date parameters

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:

• promotion_tier_id: Promotion tier identifier for lookup

Identifier Requirements:

• Promotion Tier ID: Must start with 'promo_' prefix (e.g., "promo_abc123def456")

• ID must correspond to existing promotion tier

Validation Rules:

• Promotion tier ID must be valid and existing

• ID format is case-sensitive

Examples:

• get_promotion_tier(promotion_tier_id="promo_abc123def456")

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:

• action: Complete discount configuration including:

  • discount: Discount type and value settings

  • unit_off: Fixed amount discount (if applicable)

  • unit_off_formula: Dynamic discount calculation (if applicable)

  • percent_off: Percentage discount (if applicable)

  • percent_off_formula: Dynamic percentage calculation (if applicable)

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):

• assigned_validation_rules: Processed validation rules with detailed conditions (added by this tool) See "Validation Rules Structure" section in server instructions for complete field documentation

Additional Data:

• metadata: Custom promotion tier attributes

• created_at, updated_at: ISO 8601 timestamps

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:

• ToolError: If promotion tier not found or invalid ID format

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: Voucher code or ID for lookup

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:

• Identifier must correspond to existing voucher

• Both codes and IDs are case-sensitive

Examples:

• get_voucher(identifier="WELCOME10")

• get_voucher(identifier="v_abc123def456")

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):

• assigned_validation_rules: Processed validation rules with detailed conditions (added by this tool) See "Validation Rules Structure" section in server instructions for complete field documentation

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:

• ToolError: If voucher not found or invalid identifier format

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:

1. Call list_campaigns() to get all campaigns

2. Match user's campaign name against returned names

3. Use resolved campaign ID for other campaign tools

Limitations:

• Maximum 1000 campaigns returned

• No filtering options available

• Results sorted by creation date

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):

• $after, $before: Date comparison (ISO 8601 format)

Pricing Rules:

• All prices in cents (2000 = $20.00, 150 = $1.50)

• Consistent across all Voucherify tools

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:

• 100 products per page

• Results sorted by created_at descending (newest first)

• Custom sorting not supported

Raises:

• ToolError: If filter structure invalid or unsupported operators used

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