---
title: "Generate a report"
method: POST
path: "/v1/report"
tags: ["Reports"]
---

# Generate a report

`POST /v1/report`

## Request

- Base URL: `https://api.cashbackhive.com`
- URL: `https://api.cashbackhive.com/v1/report`
- Auth: API key in header `x-publisher-key`

Sanity catalog only. Generate a report of transactions or commissions for a given date range. Supports JSON and CSV output formats.

The `clicks` report type is currently unavailable on this endpoint and returns a 400.

## Request body

- ReportRequest
  - `start_date` string, date, required: Start date for the report period (YYYY-MM-DD).
  - `end_date` string, date, required: End date for the report period (YYYY-MM-DD).
  - `type` 'clicks' | 'transactions' | 'commissions', required: Report type. `"clicks"` is currently unavailable and returns a 400.
  - `format` 'json' | 'csv': Response format. Defaults to `"json"`.

## Response `200`

Report generated successfully. Returns JSON by default, or a CSV file when `format` is `"csv"`.

- ReportResponse
  - `report_id` string, required: Unique report identifier.
  - `type` 'clicks' | 'transactions' | 'commissions', required: Report type.
  - `start_date` string, date, required: Report start date.
  - `end_date` string, date, required: Report end date.
  - `total_records` integer, required: Number of records in the report.
  - `data` union[], required: Report rows. Shape varies by report type.
    - union
      - ClickRow
        - `date` string: Click timestamp (ISO 8601).
        - `brand` string: Store / brand name.
        - `store_slug` string: Store slug.
        - `click_id` string: Internal click ID.
        - `publisher_click_id` string, nullable: Your click ID (if provided).
        - `ip_address` string, nullable: Visitor IP address.
        - `referrer` string, nullable: HTTP referrer.
      - TransactionRow
        - `transaction_id` string: Unique transaction identifier. Stable across requests — use this as a dedup key.
        - `date` string: Transaction event date.
        - `brand` string: Merchant / brand name.
        - `amount` number: Sale amount.
        - `commission` number: Commission you earned, after your commission share (split) has been applied.
        - `status` 'pending' | 'approved' | 'cancelled' | 'unknown': Transaction status.
        - `order_number` string, nullable: Merchant order reference.
        - `currency` string: ISO 4217 currency code.
        - `publisher_click_id` string, nullable: Your click ID associated with the transaction, if provided at click time.
      - CommissionRow
        - `date` string: Transaction event date.
        - `brand` string: Merchant / brand name.
        - `amount` number: Sale amount.
        - `commission` number: Commission you earned, after your commission share (split) has been applied.
        - `status` 'pending' | 'approved' | 'cancelled' | 'unknown': Transaction status.
        - `currency` string: ISO 4217 currency code.

## Other responses

- `400`: Validation error — missing or invalid fields, or an unavailable report type (`clicks`).
- `401`: Invalid or missing API key.

## Changes

- **2026-10-23** `89457c5362eb`: 8 warning
  - added the new `approved` enum value to the `data/items/oneOf[#/components/schemas/CommissionRow]/status` response property for the response status `200` (media type: application/json)
  - added the new `approved` enum value to the `data/items/oneOf[#/components/schemas/TransactionRow]/status` response property for the response status `200` (media type: application/json)
  - added the new `cancelled` enum value to the `data/items/oneOf[#/components/schemas/CommissionRow]/status` response property for the response status `200` (media type: application/json)
  - added the new `cancelled` enum value to the `data/items/oneOf[#/components/schemas/TransactionRow]/status` response property for the response status `200` (media type: application/json)
  - …4 more

[Operation history](https://skmtc.dev/cashbackhive/apis/cashbackhive-publisher-api/changes/v1/report/post.md)

---

[API](https://skmtc.dev/cashbackhive/apis/cashbackhive-publisher-api.md) - [All operations](https://skmtc.dev/cashbackhive/apis/cashbackhive-publisher-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cashbackhive/apis/cashbackhive-publisher-api/revisions/89457c5362eb?raw)