---
title: Revenue Attribution API
description: POST /v1/payments - Track revenue from any payment provider
url: https://www.supalytics.co/docs/api/revenue-attribution
---



Track revenue from any payment provider (Paddle, LemonSqueezy, custom billing, etc.) with traffic source attribution.

## Endpoint

```
POST https://api.supalytics.co/v1/payments
```

## Request

### Headers

| Header          | Value               |
| --------------- | ------------------- |
| `Authorization` | `Bearer sly_xxx...` |
| `Content-Type`  | `application/json`  |

### Body

| Field            | Type   | Required | Description                                                                                  |
| ---------------- | ------ | -------- | -------------------------------------------------------------------------------------------- |
| `amount`         | number | Yes      | Payment amount in dollars (e.g., 29.99). For trials, use the plan price (potential revenue). |
| `currency`       | string | Yes      | 3-letter ISO currency code (e.g., "USD", "EUR")                                              |
| `transaction_id` | string | Yes      | Unique ID from your payment provider                                                         |
| `visitor_id`     | string | No       | Supalytics visitor ID for attribution                                                        |
| `mode`           | string | No       | `subscription` or `payment` (one-time). Default: `subscription`                              |
| `event`          | string | No       | Event type (default: `purchase`). See below.                                                 |
| `timestamp`      | string | No       | ISO 8601 timestamp (defaults to now)                                                         |

### Event Types

| Event            | Description                                           |
| ---------------- | ----------------------------------------------------- |
| `purchase`       | New purchase (one-time or first subscription payment) |
| `trial`          | Free trial started                                    |
| `renewal`        | Recurring subscription payment                        |
| `refund`         | Full refund                                           |
| `partial_refund` | Partial refund                                        |
| `chargeback`     | Disputed charge                                       |
| `upgrade`        | Plan upgrade                                          |
| `downgrade`      | Plan downgrade                                        |
| `cancellation`   | Subscription cancelled                                |
| `past_due`       | Payment failed, subscription at risk                  |

### Examples

**New subscription purchase:**

```bash
curl -X POST https://api.supalytics.co/v1/payments \
  -H "Authorization: Bearer sly_xxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 29.99,
    "currency": "USD",
    "transaction_id": "pay_1234567890",
    "visitor_id": "abc123",
    "mode": "subscription",
    "event": "purchase"
  }'
```

**Free trial started:**

```bash
curl -X POST https://api.supalytics.co/v1/payments \
  -H "Authorization: Bearer sly_xxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 49.00,
    "currency": "USD",
    "transaction_id": "sub_trial_abc123",
    "visitor_id": "abc123",
    "mode": "subscription",
    "event": "trial"
  }'
```

The amount for trials represents the plan price (potential revenue if the trial converts).

## Response

### Success (200)

```json
{
  "message": "Payment recorded successfully",
  "transaction_id": "pay_1234567890"
}
```

## Visitor ID for Attribution

To attribute revenue to traffic sources, you need the visitor ID from when the user first signed up. See [Revenue Attribution](/docs/revenue-attribution#2-capture-the-visitor-id) for how to capture and store visitor IDs.

Without a visitor ID, payments are still recorded but won't appear in traffic source breakdowns.

## When to Use This API

Use the Payments API when:

* Using a payment provider other than Stripe (Paddle, LemonSqueezy, etc.)
* Processing payments through a custom billing system
* Syncing historical payments
* Recording manual or offline payments

If you're using Stripe, consider the [Stripe integration](/docs/revenue-attribution) instead—it syncs automatically without code changes.

## Rate Limits

* **100 requests per second** per API key
* Rate limit headers in response: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`


---

## Other Documentation

- [Autocapture](https://www.supalytics.co/llms/docs/autocapture)
- [Backfill Existing Subscriptions](https://www.supalytics.co/llms/docs/backfill-existing-subscriptions)
- [Block Your Own Traffic](https://www.supalytics.co/llms/docs/block-your-traffic)
- [CLI](https://www.supalytics.co/llms/docs/cli)
- [Custom Events](https://www.supalytics.co/llms/docs/custom-events)
- [Features](https://www.supalytics.co/llms/docs/features)
- [Conversion Funnels](https://www.supalytics.co/llms/docs/funnels)
- [Introduction](https://www.supalytics.co/llms/docs)
- [Install Script](https://www.supalytics.co/llms/docs/install-script)
- [MRR Tracking](https://www.supalytics.co/llms/docs/mrr-tracking)
- [Revenue Attribution](https://www.supalytics.co/llms/docs/revenue-attribution)
- [Agent Skills](https://www.supalytics.co/llms/docs/skills)
- [Tracking Modes](https://www.supalytics.co/llms/docs/tracking-modes)
- [Visitor Journey](https://www.supalytics.co/llms/docs/visitor-journey)
- [Annotations](https://www.supalytics.co/llms/docs/api/annotations)
- [Error Codes](https://www.supalytics.co/llms/docs/api/errors)
- [Events (Read)](https://www.supalytics.co/llms/docs/api/events)
- [API Reference](https://www.supalytics.co/llms/docs/api)
- [Journeys](https://www.supalytics.co/llms/docs/api/journeys)
- [Query API](https://www.supalytics.co/llms/docs/api/query)
- [Realtime API](https://www.supalytics.co/llms/docs/api/realtime)
- [Events (Write)](https://www.supalytics.co/llms/docs/api/server-side-events)