> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trychannel3.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Reporting
Product responses include buy URLs that look like `buy.trychannel3.com/***`. These links route shoppers to the merchant site and let Channel3 attribute clicks and sales to your account.
You can pull click and commission data for your account with the endpoints below. Use it to power dashboards, reconcile payouts, or feed analytics into your own systems.
## Tracking
### Clicks and transactions are tracked automatically
Every offer URL in a search or product response is a tracked buy link. When a shopper clicks it, Channel3 records the click. If that click converts to a sale, we attribute the commission to your account. You do not need to configure anything for this to work.
### Optional: pass a `user_id` to attribute events to your users
Send the `x-user-id` header on [`POST /v1/search`](/api-reference/v1/search) (and other catalog endpoints) to tie clicks and commissions back to a specific user.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.trychannel3.com/v1/search \
-H "x-api-key: $CHANNEL3_API_KEY" \
-H "x-user-id: ABCD" \
-H "Content-Type: application/json" \
-d '{"query": "running shoes"}'
```
Use a stable identifier from your system (UUID, Clerk ID, etc.). Values may contain letters, numbers, and `.` `_` `@` `-`, up to 128 characters.
When a shopper clicks one of those buy URLs, Channel3 records `user_id` with the click. If the click converts to a sale, the same value appears on the transaction.
Each click and transaction in reporting includes a `user_id` field when the originating request included `x-user-id`. Pass `user_id` as a query parameter on the reporting endpoints below to filter results to one user.
```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
"id": "clk_abc123",
"timestamp": "2026-07-15T14:22:00Z",
"user_id": "ABCD",
"product": {
"id": "2yh8WH5",
"title": "Running Shoe",
"image_url": "https://cdn.trychannel3.com/..."
},
"country": "US"
}
```
## Reporting endpoints
Two endpoints let you query clicks and transactions for your account.
Click events plus a total-click summary for your date window.
Transactions plus net commission totals for your date window.
Commission amounts on transactions are **your net share** after Channel3's take rate. See [Commissions](/commissions) for how payouts work.
### Date windows
Pass `start_date` and `end_date` as ISO 8601 datetimes:
* Omit both to default to the **last 30 days** ending now.
* Provide **both** or **neither** — a single bound returns `400`.
* Maximum window is **90 days**.
* Offset-aware values (e.g. `2026-08-01T00:00:00-04:00`) are converted to UTC. Naive values are treated as UTC.
* Responses echo the resolved window as UTC (`...Z`).
### Pagination
Results are newest-first. Use `page` (1-indexed) and `limit` (1–100, default 20). Each response includes `total_count`, `has_more`, and a `summary` for the full window (not just the current page).
### List clicks
```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import Channel3 from "@channel3/sdk";
const client = new Channel3();
const clicks = await client.reporting.clicks.list({
start_date: "2026-07-01T00:00:00Z",
end_date: "2026-07-31T23:59:59Z",
page: 1,
limit: 50,
user_id: "ABCD", // optional
});
console.log(clicks.summary.total_clicks);
for (const click of clicks.items) {
console.log(click.timestamp, click.product?.title, click.country);
}
```
```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from channel3_sdk import Channel3
client = Channel3()
clicks = client.reporting.clicks.list(
start_date="2026-07-01T00:00:00Z",
end_date="2026-07-31T23:59:59Z",
page=1,
limit=50,
user_id="ABCD", # optional
)
print(clicks.summary.total_clicks)
for click in clicks.items:
print(click.timestamp, click.product, click.country)
```
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.trychannel3.com/v1/reporting/clicks?start_date=2026-07-01T00:00:00Z&end_date=2026-07-31T23:59:59Z&page=1&limit=50&user_id=ABCD" \
-H "x-api-key: $CHANNEL3_API_KEY"
```
Each click includes an `id`, `timestamp`, optional `user_id`, optional geo (`city` / `country`), and a compact `product` when we can match one (`id`, `title`, `image_url`).
### List transactions
```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const transactions = await client.reporting.transactions.list({
start_date: "2026-07-01T00:00:00Z",
end_date: "2026-07-31T23:59:59Z",
user_id: "ABCD", // optional
});
console.log(transactions.summary);
// { total_count, total_commission, pending_commission, paid_commission }
for (const txn of transactions.items) {
console.log(
txn.purchased_at,
txn.status,
txn.commission_amount,
txn.brand_name,
);
}
```
```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
transactions = client.reporting.transactions.list(
start_date="2026-07-01T00:00:00Z",
end_date="2026-07-31T23:59:59Z",
user_id="ABCD", # optional
)
print(transactions.summary)
for txn in transactions.items:
print(txn.purchased_at, txn.status, txn.commission_amount, txn.brand_name)
```
```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.trychannel3.com/v1/reporting/transactions?start_date=2026-07-01T00:00:00Z&end_date=2026-07-31T23:59:59Z&user_id=ABCD" \
-H "x-api-key: $CHANNEL3_API_KEY"
```
Each transaction includes `order_amount`, `commission_amount`, `status`, `purchased_at`, `brand_name`, optional `user_id`, optional geo (`city` / `country`), and a compact `product` when we can match one.
#### Transaction status
| Status | Meaning |
| --------- | ------------------------------------------------------------------------------------------------ |
| `pending` | Not yet paid out — includes network-approved commissions waiting on the retailer's return window |
| `paid` | Commission has been paid out |
The summary breaks out `pending_commission` and `paid_commission`, and `total_commission` is their sum.