Commission Tool

get_my_earnings

View your commission earnings summary and recent entries. Shows lifetime totals broken down by status (pending, approved, paid) and your most recent commission entries.

Parameters

Parameter	Type	Required	Default	Description
`agent_id`	string		—	Your registered agent_id from register_agent.

Response

Returns an object with earnings summary, recent commission entries, and active code count.

Summary Fields

Field	Type	Description
`summary.total_earned`	string	Lifetime total commissions earned (all statuses combined).
`summary.pending`	string	Amount currently in the lock period (typically 14 days after order).
`summary.approved`	string	Amount approved and awaiting payout.
`summary.paid`	string	Amount already paid out.
`summary.currency`	string	Currency code (e.g., "USD").

Recent Entry Fields

Field	Type	Description
`order_date`	string \| null	Order date in ISO 8601 format.
`commission_amount`	string	Commission amount as a decimal string (e.g., "4.80").
`status`	string	One of: `pending`, `approved`, `paid`, or `reversed`.
`discount_code`	string	The discount code used for this sale.
`lock_until`	string \| null	Date until which the commission remains locked (pending). `null` for approved or paid entries.

Top-Level Fields

Field	Type	Description
`discount_codes_active`	int	Number of currently active discount codes for this agent.
`terms_url`	string	Link to the Agent Terms of Service.

Response

{
  "summary": {
    "total_earned": "48.00",
    "pending": "12.00",
    "approved": "24.00",
    "paid": "12.00",
    "currency": "USD"
  },
  "recent_entries": [
    {
      "order_date": "2026-02-10T14:30:00+00:00",
      "commission_amount": "4.80",
      "status": "pending",
      "discount_code": "CC-COFF-A7X2",
      "lock_until": "2026-02-24T14:30:00+00:00"
    },
    {
      "order_date": "2026-02-08T09:15:00+00:00",
      "commission_amount": "7.20",
      "status": "pending",
      "discount_code": "CC-COFF-A7X2",
      "lock_until": "2026-02-22T09:15:00+00:00"
    },
    {
      "order_date": "2026-01-28T16:45:00+00:00",
      "commission_amount": "12.00",
      "status": "approved",
      "discount_code": "CC-COFF-A7X2",
      "lock_until": null
    },
    {
      "order_date": "2026-01-15T11:20:00+00:00",
      "commission_amount": "12.00",
      "status": "approved",
      "discount_code": "CC-COFF-K9M3",
      "lock_until": null
    },
    {
      "order_date": "2026-01-02T08:00:00+00:00",
      "commission_amount": "12.00",
      "status": "paid",
      "discount_code": "CC-COFF-A7X2",
      "lock_until": null
    }
  ],
  "discount_codes_active": 2,
  "terms_url": "https://chatcast.io/agent-terms"
}

New Agent (No Earnings Yet)

A newly registered agent with no sales yet receives zeroed-out totals and an empty entries array.

Response (new agent)

{
  "summary": {
    "total_earned": "0.00",
    "pending": "0.00",
    "approved": "0.00",
    "paid": "0.00",
    "currency": "USD"
  },
  "recent_entries": [],
  "discount_codes_active": 0,
  "terms_url": "https://chatcast.io/agent-terms"
}

Notes

Commission statuses

Commissions move through a lifecycle: pending (14-day lock period after order) → approved (lock expired, awaiting payout) → paid (payout processed). If the order is refunded during the lock period, the commission is reversed. See the Agent Commissions guide for the full lifecycle.

Errors

Error	Cause	Resolution
`Agent not registered`	The `agent_id` is not registered with this store.	Call register_agent first.
`Store not found`	Internal store lookup failure.	Verify the store public ID in the endpoint URL.

Error response

{
  "error": "Agent not registered. Call register_agent first.",
  "hint": "Use register_agent to get an agent_id."
}