# Revenue & Refund Tracking



# Charge Event — Revenue & Refund Tracking

This document defines the official revenue tracking standard in **Intempt**.

All real payment operations — including successful charges and refunds — must be tracked using the `Charge` event via the server-side Track API.

There are no separate `Purchase`, `OrderCompleted`, or `Refund` events for revenue accounting.

**Charge is the canonical revenue event.**

---

## Why the Charge Event Exists

Revenue tracking must be:

* accurate
* server-validated
* tied to real payment operations
* consistent across platforms
* compatible with refunds

The `Charge` event ensures:

* correct revenue aggregation
* accurate refund deduction
* clean financial reporting
* simplified data taxonomy
* consistent experiment attribution

---

## Core Rule

There is only one revenue event name:

```
Charge
```

Both successful payments and refunds must use this event.

The difference is defined by the payload properties.

---

## When to Fire the Charge Event

The `Charge` event must be fired:

* only after a payment is successfully captured
* only when money has actually moved
* from the backend (server-side)
* not from the browser

Do **NOT** fire `Charge` on:

* checkout started
* cart updated
* order created but unpaid
* pending transactions
* failed payments

It must reflect a real financial transaction.

---

# Successful Payment (Revenue)

When a payment succeeds, send:

```json
{
  "track": [
    {
      "name": "Charge",
      "payload": [
        {
          "eventId": "uuid-generated-event-id",
          "userId": "user@example.com",
          "data": {
            "amount": 271.28,
            "status": "succeeded"
          }
        }
      ]
    }
  ]
}
```

## Required Properties

| Field   | Description                                   |
| ------- | --------------------------------------------- |
| eventId | A unique random identifier (UUID recommended) |
| userId  | User identifier (email or profileId)          |
| amount  | Total charged amount                          |
| status  | Must be `"succeeded"`                         |

---

### Important Notes

* `amount` must represent the actual charged amount.
* Currency handling should be consistent across your system.
* `eventId` must be unique to prevent duplication.
* This event must be sent via the Track API endpoint.

---

# Refund (Revenue Deduction)

Refunds must also use the `Charge` event.

Only the payload changes.

```json
{
  "track": [
    {
      "name": "Charge",
      "payload": [
        {
          "eventId": "uuid-generated-event-id",
          "userId": "user@example.com",
          "data": {
            "amount_refunded": 11.0,
            "status": "succeeded"
          }
        }
      ]
    }
  ]
}
```

## Required Properties

| Field           | Description           |
| --------------- | --------------------- |
| amount_refunded | The refunded amount   |
| status          | Must be `"succeeded"` |

---

## Critical Rule

**Do NOT create a `Refund` event.**

Refund is a financial operation within the `Charge` lifecycle.

This keeps revenue modeling clean:

* `amount` → positive revenue
* `amount_refunded` → negative revenue

---

## Server-Side Implementation Requirements

The `Charge` event must:

* be sent from backend systems
* use the standard Track API path
* use your Intempt API key
* include a unique `eventId`
* use `userId` for identity

Example Track API endpoint:

```
POST /{orgName}/projects/{projectName}/sources/{sourceId}/track?apiKey=YOUR_API_KEY
```

---

## Identity Guidelines

You may use:

* `userId` (recommended if email-based system)

Identity must be consistent across:

* web
* mobile
* backend systems

This ensures:

* correct revenue attribution
* accurate experiment reporting
* proper customer lifetime value calculation

---

## WooCommerce / eCommerce Integration Example

For WooCommerce or similar systems:

### On Order Paid

Hook into:

* `woocommerce_payment_complete`
* or equivalent payment confirmation hook

Send `Charge` with:

```
amount = order total  
status = "succeeded"
```

---

### On Refund Completed

Hook into:

* `woocommerce_order_refunded`

Send `Charge` with:

```
amount_refunded = refunded value  
status = "succeeded"
```

Only fire after payment gateway confirms the transaction.

---

## Best Practices

* Always generate a random UUID for `eventId`
* Ensure idempotency (avoid duplicate firing)
* Do not rely on client-side triggers
* Do not mix test and production revenue streams
* Validate payment success before sending

---

## Common Mistakes to Avoid

❌ Sending `Purchase` instead of `Charge`

❌ Creating a separate `Refund` event

❌ Sending from frontend

❌ Firing before payment confirmation

❌ Reusing the same `eventId`

❌ Sending partial or pending payments

---

# Final Takeaway

Revenue in Intempt is modeled through a single canonical event:

```
Charge
```

* Successful payment → `amount`
* Refund → `amount_refunded`

Both use:

* the same event name
* the same Track endpoint
* server-side execution only

This ensures:

* clean financial modeling
* accurate reporting
* simplified taxonomy
* reliable revenue tracking
* correct experiment attribution