SDK & API

Event Reference

Evidence events are the core data RecurCite uses to build dispute responses. Each event type has specific required fields and an optional stripe_refs object for linking to Stripe objects.

terms.accepted

Customer accepted your terms of service. This is one of the strongest pieces of evidence — it proves the customer agreed to your policies before the transaction.

Field	Type	Required	Description
`version`	string	Yes	Terms version identifier (e.g. "2.0")
`accepted_at`	ISO 8601	Yes	When the customer accepted

json

{
  "type": "terms.accepted",
  "payload": {
    "version": "2.0",
    "accepted_at": "2025-01-15T10:30:00Z"
  },
  "stripe_refs": {
    "stripe_customer_id": "cus_abc123"
  }
}

user.login

Customer logged into your product. Demonstrates active product usage and that the customer had access to their account.

Field	Type	Required	Description
`occurred_at`	ISO 8601	Yes	Login timestamp
`ip`	string	No	Client IP address
`user_agent`	string	No	Browser user agent
`device_fingerprint`	string	No	Device fingerprint

json

{
  "type": "user.login",
  "payload": {
    "occurred_at": "2025-01-20T14:22:00Z",
    "ip": "203.0.113.42",
    "user_agent": "Mozilla/5.0 ..."
  },
  "stripe_refs": {
    "stripe_customer_id": "cus_abc123"
  }
}

product.used

Customer used a product feature. Quantifies engagement and proves the customer derived value from your service.

Field	Type	Required	Description
`feature_key`	string	Yes	Feature identifier (e.g. "api_calls")
`count`	integer	Yes	Usage count (≥ 1)
`occurred_at`	ISO 8601	Yes	When usage occurred

json

{
  "type": "product.used",
  "payload": {
    "feature_key": "api_calls",
    "count": 150,
    "occurred_at": "2025-01-18T09:00:00Z"
  },
  "stripe_refs": {
    "stripe_customer_id": "cus_abc123",
    "stripe_subscription_id": "sub_xyz456"
  }
}

cancellation.requested

Customer requested cancellation. Shows you had a proper cancellation flow and the customer was aware of how to cancel.

Field	Type	Required	Description
`occurred_at`	ISO 8601	Yes	Request timestamp

json

{
  "type": "cancellation.requested",
  "payload": {
    "occurred_at": "2025-02-01T16:45:00Z"
  },
  "stripe_refs": {
    "stripe_customer_id": "cus_abc123"
  }
}

cancellation.confirmed

Cancellation was confirmed and processed. Proves your cancellation policy was followed.

Field	Type	Required	Description
`occurred_at`	ISO 8601	Yes	Confirmation timestamp
`receipt_id`	string	No	Cancellation receipt identifier

json

{
  "type": "cancellation.confirmed",
  "payload": {
    "occurred_at": "2025-02-01T16:50:00Z",
    "receipt_id": "cancel_receipt_789"
  },
  "stripe_refs": {
    "stripe_customer_id": "cus_abc123"
  }
}

support.ticket.created

Customer opened a support ticket. Shows you provided customer support channels and the customer engaged with them.

Field	Type	Required	Description
`occurred_at`	ISO 8601	Yes	Ticket creation timestamp
`ticket_id`	string	No	Your ticket system ID

json

{
  "type": "support.ticket.created",
  "payload": {
    "occurred_at": "2025-01-25T11:00:00Z",
    "ticket_id": "TICKET-1234"
  },
  "stripe_refs": {
    "stripe_customer_id": "cus_abc123"
  }
}

support.ticket.resolved

Support ticket was resolved. Demonstrates you addressed the customer's concerns before the dispute.

Field	Type	Required	Description
`occurred_at`	ISO 8601	Yes	Resolution timestamp
`ticket_id`	string	No	Your ticket system ID

json

{
  "type": "support.ticket.resolved",
  "payload": {
    "occurred_at": "2025-01-25T15:30:00Z",
    "ticket_id": "TICKET-1234"
  },
  "stripe_refs": {
    "stripe_customer_id": "cus_abc123"
  }
}

Stripe references

All events accept an optional stripe_refs object to link evidence to specific Stripe objects. Include as many references as possible — this helps RecurCite match events to disputes automatically.

json

{
  "stripe_refs": {
    "stripe_customer_id": "cus_abc123",
    "stripe_subscription_id": "sub_xyz456",
    "stripe_payment_intent_id": "pi_...",
    "stripe_invoice_id": "in_..."
  }
}

Tip

At minimum, always include stripe_customer_id. This is the primary key RecurCite uses to match evidence to disputes.

Evidence Health

Evidence Health is a score from 0 to 100 that measures how complete your evidence coverage is for a given dispute. A higher score means stronger evidence and better chances of winning.

Score	Grade	Meaning
80–100	A	Excellent — strong evidence across all categories
60–79	B	Good — some evidence gaps but still competitive
40–59	C	Fair — missing key evidence types
0–39	D	Weak — significant evidence gaps

Proof Discount

Maintain an Evidence Health grade of A on 80%+ of disputes to qualify for reduced success fees on Pro and Scale plans. See Pricing & Billing → Proof Discount.

Privacy rules

RecurCite enforces strict data minimization. The API validates all payloads against strict schemas — unknown fields are rejected.

No raw emails — use email_sha256 (SHA-256 hex) instead
No content payloads — only metadata, counters, and timestamps
IP + user_agent — optional, configurable per organization
No sensitive PII — SSNs, credit card numbers, etc. are rejected

Next steps

SDK Installation — set up the SDK and start sending events
Security & Data — learn about encryption, signing, and data handling