Skip to main content

Delivering Targeted Coupons

ai12z enables you to reward users with targeted, one-time coupons as part of your automated chat and support flows—perfect for returns, high-value purchases, loyalty milestones, and more. This guide shows you how to set up targeted coupon delivery by integrating your e-commerce or CDP system (e.g., Shopify, Klaviyo, Salesforce, Adobe, custom) with ai12z’s Custom Integrations.

1. Prerequisites​

  • Access to the ai12z portal and permissions to add Custom Integrations.
  • API credentials for your e-commerce/CDP platform (e.g., Shopify admin API, Klaviyo private key).
  • The platform must support creating or fetching coupon codes via API.

2. Common Coupon Delivery Scenarios​

  • After a return or support case (“Thanks for your patience—here’s a 10% off coupon”)
  • For loyalty/rewards users (“You’ve hit Gold! Enjoy this exclusive code”)
  • Based on user actions (e.g., leaving a review, referring a friend)
  • Manual triggers by live agents in chat

3. Integration Workflow Overview​

graph TD
    A[User Triggers Coupon Flow<br>(e.g. completes a return)] --> B[ai12z Reasoning Engine]
    B --> C[Custom Integration]
    C --> D[E-commerce/CDP Coupon API]
    D --> E[Coupon Code]
    E --> F[Bot Responds in Chat<br>with Personalized Coupon]

4. Step-by-Step Setup​

A. Set Up Coupon Generation in Your Platform​

Example: Shopify

Example API Call to Generate a Code:

import requests

SHOPIFY_DOMAIN = "yourstore.myshopify.com"
API_KEY = "your-api-key"
PASSWORD = "your-api-password"

# Step 1: Create price rule
pricerule_resp = requests.post(
    f"https://{API_KEY}:{PASSWORD}@{SHOPIFY_DOMAIN}/admin/api/2024-04/price_rules.json",
    json={
        "price_rule": {
            "title": "ReturnReward",
            "target_type": "line_item",
            "target_selection": "all",
            "allocation_method": "across",
            "value_type": "percentage",
            "value": "-10.0", # 10% off
            "customer_selection": "all",
            "starts_at": "2025-07-15T00:00:00-04:00"
        }
    }
)
pricerule_id = pricerule_resp.json()["price_rule"]["id"]

# Step 2: Create discount code
discount_resp = requests.post(
    f"https://{API_KEY}:{PASSWORD}@{SHOPIFY_DOMAIN}/admin/api/2024-04/price_rules/{pricerule_id}/discount_codes.json",
    json={
        "discount_code": {"code": "THANKS10-" + "XYZ123"}
    }
)
coupon_code = discount_resp.json()["discount_code"]["code"]

Tip: Most platforms (Klaviyo, Salesforce, Magento, WooCommerce, custom) offer similar endpoints for coupon code creation.

B. Create a Custom Integration in ai12z​

  1. Go to the ai12z portal > Integrations > Custom Integrations

  2. Create New Integration

    • Type: REST (or GraphQL, MCP if your backend supports it)
    • Method: POST (for code creation), or GET (for code fetch)
    • URL: Your coupon endpoint (e.g., Shopify’s API)
    • Headers: Add your API keys/tokens as needed
    • Parameters/body: Map {attributes.user.email} or other context fields from the chat/session

Example: ai12z Integration Request Mapping

{
  "price_rule": {
    "title": "ReturnReward",
    "customer_selection": "all",
    "value_type": "percentage",
    "value": "-10.0",
    "starts_at": "{{ now | iso8601 }}"
  }
}
  • Use JSONata or direct mapping to pass chat context (like user email, name, loyalty status).

  1. Test Integration

    • Use the “Test” button in the portal to generate a test coupon and verify the response.

C. Surface the Coupon in the Chatbot Response​

In your agent’s ReAct System Prompt:

You are a helpful assistant.
If a user completes a return or triggers a coupon scenario, call the "GenerateCoupon" integration and display the returned coupon code with a friendly message.
Always personalize your reply using `{attributes}`.

Example Chat Flow:

  • User: “I’ve submitted my return, what next?”
  • Bot: (Integration triggers, code generated) “Thank you for your return! Here’s a 10% off coupon for your next order: THANKS10-XYZ123”

D. Optional: Filter or Qualify Users​

  • Use includeTags/excludeTags or check {attributes} (e.g., loyalty level, return status) to control coupon eligibility.

5. Best Practices​

  • Security: Only trigger coupon creation from the backend (never client JS).
  • Usage Limits: Always create single-use or limited-use codes for each user.
  • Expiration: Set expiration dates to encourage quick use.
  • Personalization: Reference the user’s name, loyalty level, or purchase history in your message.
  • Testing: Always use test modes and preview codes before going live.

6. Troubleshooting & FAQ​

Q: Can I generate unique codes for each user? A: Yes—create a new code per session/user via the integration.

Q: Can I show different offers for different users? A: Yes—branch logic in your System Prompt or Integration based on {attributes} (loyalty level, segment, etc.).

Q: What platforms are supported? A: Any e-commerce or CDP platform with a REST/GraphQL API (Shopify, Magento, Klaviyo, Salesforce, WooCommerce, custom, etc.)

7. Complete Example: End-to-End Flow​

  1. User initiates a return in chat.

  2. ai12z passes user info (attributes or token) to the integration.

  3. Integration calls your e-commerce/CDP API to generate a coupon.

  4. Bot shares coupon instantly:

    “Thank you! Here’s your exclusive 10% off code for your next purchase: THANKS10-XYZ123”

8. Sample Block Diagram​

sequenceDiagram
    participant User
    participant ai12zBot
    participant ai12zIntegration
    participant Shopify

    User->>ai12zBot: Completes return
    ai12zBot->>ai12zIntegration: Pass user attributes
    ai12zIntegration->>Shopify: Create coupon via API
    Shopify-->>ai12zIntegration: Return coupon code
    ai12zIntegration-->>ai12zBot: Coupon code (THANKS10-XYZ123)
    ai12zBot-->>User: "Thank you! Here’s your coupon: THANKS10-XYZ123"

Ready to Go!

You’re now set to deliver targeted, secure, and highly personalized coupons to your users—automatically, and at any point in the customer journey—with ai12z.