Agent Commissions

How It Works

ChatCast enables AI agents to earn commissions on sales they influence. The flow has seven steps, from registration through earning tracking. Steps 1-4 are tool calls you make; steps 5-6 happen automatically; step 7 lets you check your earnings.

Step 1: Register Your Agent

Call register_agent with your agent name and description. You receive a unique agent_id used in all subsequent calls for attribution.

register_agent({
  "name": "CoffeeBot",
  "description": "AI shopping assistant for coffee enthusiasts"
})

{
  "agent_id": "agent_abc123def456",
  "name": "CoffeeBot",
  "message": "Registration successful. Pass agent_id in tool calls for attribution.",
  "terms_url": "https://chatcast.io/agent-terms"
}

Step 2: Check Commission Rates

Call get_commission_rates to see the store's base commission rate. This is the percentage you earn on each attributed sale.

get_commission_rates()

{
  "default_rate": 0.08,
  "category_rates": null,
  "product_rates": null
}

This store pays 8% commission on all products by default.

Step 3: Find Active Campaigns

Call get_active_campaigns to discover bonus commission rates and customer discount codes.

get_active_campaigns()

[
  {
    "name": "Spring Sale",
    "bonus_rate": 0.05,
    "customer_discount_percent": 10.0,
    "customer_discount_code": "SPRING10",
    "starts_at": "2026-03-01T00:00:00+00:00",
    "ends_at": "2026-03-31T23:59:59+00:00"
  }
]

The "Spring Sale" campaign adds +5% bonus commission (total 13%) and offers customers 10% off.

Step 4: Get Your Discount Code

Call get_my_discount_code to receive a unique, trackable discount code attributed to your agent. This code is synced to Shopify automatically.

get_my_discount_code({
  "agent_id": "agent_abc123def456"
})

{
  "discount_codes": [
    {
      "discount_code": "CC-COFF-X7K2",
      "discount_percent": 10.0,
      "campaign_name": "Spring Sale",
      "campaign_id": 5,
      "expires_at": "2026-03-31T23:59:59+00:00",
      "is_active": true
    }
  ]
}

Your unique code is CC-COFF-X7K2. This gives customers 10% off and tracks the sale back to your agent.

Step 5: Share the Code with Customers

When recommending products, share your discount code with the customer. For example:

Step 6: Customer Purchases with Your Code

When the customer applies your discount code at the Shopify checkout:

1. Shopify processes the order with the discount applied.
2. An order webhook fires and ChatCast detects your agent's discount code.
3. A commission entry is created with status pending and a 14-day lock period.

This step is fully automatic -- no tool calls needed.

Step 7: Check Your Earnings

Call get_my_earnings at any time to see your commission summary and recent entries.

get_my_earnings({
  "agent_id": "agent_abc123def456"
})

{
  "summary": {
    "total_earned": "17.55",
    "pending": "17.55",
    "approved": "0.00",
    "paid": "0.00",
    "currency": "USD"
  },
  "recent_entries": [
    {
      "order_date": "2026-03-15T14:30:00+00:00",
      "commission_amount": "17.55",
      "status": "pending",
      "discount_code": "CC-COFF-X7K2",
      "lock_until": "2026-03-29T14:30:00+00:00"
    }
  ],
  "discount_codes_active": 1,
  "terms_url": "https://chatcast.io/agent-terms"
}

Commission Lifecycle

Every commission moves through a defined lifecycle:

Rate Calculation

Your effective commission rate is calculated as:

End-to-End Example

Here is a complete scenario showing an agent earning a commission on a real product sale.

Scenario: CoffeeBot recommends a coffee grinder

1. CoffeeBot connects to Cool Coffee Co's MCP endpoint and registers (steps 1-4 above). It has agent ID agent_abc123def456 and discount code CC-COFF-X7K2 (10% off via Spring Sale).

2. A user asks: "Can you recommend a good coffee grinder?" CoffeeBot searches the store:

search_products({
  "query": "coffee grinder",
  "limit": 3,
  "agent_id": "agent_abc123def456"
})

[
  {
    "public_id": "prod_grinder_001",
    "name": "Pro Burr Grinder",
    "description": "Professional-grade conical burr grinder with 40 grind settings...",
    "price": {
      "amount_in_cents": 14999,
      "currency": "USD"
    },
    "image_urls": ["https://cdn.shopify.com/..."],
    "has_variations": false,
    "_meta": {
      "commission": {
        "default_rate": 0.08,
        "effective_rate": 0.13,
        "rate_breakdown": {
          "base": 0.08,
          "campaign_bonus": 0.05,
          "campaign_name": "Spring Sale",
          "campaign_ends": "2026-03-31T23:59:59+00:00"
        }
      },
      "attribution": {
        "agent_ref": "agent_abc123def456"
      }
    }
  }
]

Notice the _meta.commission field shows the effective rate (13%) and the _meta.attribution field confirms the agent_id is being tracked.

3. CoffeeBot recommends the Pro Burr Grinder and shares the discount code:

4. The customer buys the grinder at $134.99 using the discount code. CoffeeBot earns:

5. The commission appears as "pending" for 14 days, then moves to "approved" (assuming no refund), and eventually "paid" when the merchant processes the payout.

Related Tools