estimate_loyalty_points

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