> For the complete documentation index, see [llms.txt](https://developers.spiffy.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.spiffy.co/api/reports.md).

# Reports

For report types and a step-by-step run workflow, see \[Reports: report types and running reports]\(https\://developers.spiffy.co/guides/reports-types-and-running-reports).

Saved reports, runs and exports

## List available report types with their filters, datasets, columns, and date presets

> Discovery for the reports API: each of the seven report types with the filters it accepts\
> (names, data types, options), its result datasets and columns, grouping options, and the\
> relative\_date presets. Call this before create\_report to construct a valid report.\
> \
> Each type also carries \`layout\`: the ordered sections (stats, chart, dataset) a viewer\
> renders for a run of that type.\
> \
> Report types: affiliate\_performance, attribution\_performance, cash\_flow\_projection,\
> checkout\_performance, customer\_cohort\_ltv, payment\_plan\_performance, product\_sales.\
> \
> Filter note: static options arrays are included where available. Dynamic / account-specific\
> options (e.g. product lists, checkout lists) are omitted from this endpoint — pass the\
> lister object's \`object\` field to understand what entity type drives the search.\
> \
> Note: reports bucket dates in the report's own timezone field (legacy semantics),\
> unlike /v2/analytics which is UTC-only.

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"reports","description":"Saved reports, runs and exports"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reports"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"ReportTypeV2":{"type":"object","properties":{"type":{"type":"string"},"label":{"type":"string"},"filters":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"data_type":{"type":"string"},"options":{"type":"array","items":{"type":"object","properties":{"id":{"nullable":true},"label":{"type":"string"}},"required":["label"]}}},"required":["name","data_type"]}},"datasets":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"display_type":{"type":"string"},"grouping_properties":{"type":"array","items":{"type":"string"}},"grouping_intervals":{"type":"object","additionalProperties":{"type":"string"}},"columns":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"data_type":{"type":"string"}},"required":["name","label","data_type"]}}},"required":["type","display_type","grouping_properties","columns"]}},"relative_dates":{"type":"array","items":{"type":"string"}},"layout":{"type":"array","items":{"$ref":"#/components/schemas/ReportLayoutSection"}}},"required":["type","label","filters","datasets","relative_dates","layout"]},"ReportLayoutSection":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["stats"]},"group":{"type":"string"}},"required":["kind"]},{"type":"object","properties":{"kind":{"type":"string","enum":["chart"]},"shape":{"type":"string","enum":["time_series","breakdown","single"]},"source":{"type":"string","enum":["interval","dataset"]},"x":{"type":"string"},"series":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"data_type":{"type":"string","enum":["currency","number","percentage"]}},"required":["key","label","data_type"]},"minItems":1}},"required":["kind","shape","source","x","series"]},{"type":"object","properties":{"kind":{"type":"string","enum":["dataset"]},"dataset":{"type":"string"}},"required":["kind","dataset"]}]},"Error401":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error403":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error500":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/v2/reports/types":{"get":{"tags":["reports"],"summary":"List available report types with their filters, datasets, columns, and date presets","description":"Discovery for the reports API: each of the seven report types with the filters it accepts\n(names, data types, options), its result datasets and columns, grouping options, and the\nrelative_date presets. Call this before create_report to construct a valid report.\n\nEach type also carries `layout`: the ordered sections (stats, chart, dataset) a viewer\nrenders for a run of that type.\n\nReport types: affiliate_performance, attribution_performance, cash_flow_projection,\ncheckout_performance, customer_cohort_ltv, payment_plan_performance, product_sales.\n\nFilter note: static options arrays are included where available. Dynamic / account-specific\noptions (e.g. product lists, checkout lists) are omitted from this endpoint — pass the\nlister object's `object` field to understand what entity type drives the search.\n\nNote: reports bucket dates in the report's own timezone field (legacy semantics),\nunlike /v2/analytics which is UTC-only.","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportTypeV2"}}}},"401":{"description":"Unauthorized - Authentication is required or has failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"Forbidden - You do not have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error500"}}}}}}}}}
```

## Download a report run export as CSV

> Streams the full dataset for a completed run as \`text/csv\`, with no pagination\
> and no row cap.\
> \
> This endpoint requires no authentication — the signed token in the path is the\
> credential — and it does \*\*not\*\* count against your monthly API quota. It is the\
> cheapest way to pull a large dataset: create the run, poll until it completes,\
> mint a URL with \`POST /v2/reports/{report\_id}/runs/{run\_id}/exports\`, then\
> download here.\
> \
> Tokens expire 15 minutes after they are minted.

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"reports","description":"Saved reports, runs and exports"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reports"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"Error401":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error403":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error404":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["not_found"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error500":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/v2/reports/exports/{token}":{"get":{"tags":["reports"],"summary":"Download a report run export as CSV","description":"Streams the full dataset for a completed run as `text/csv`, with no pagination\nand no row cap.\n\nThis endpoint requires no authentication — the signed token in the path is the\ncredential — and it does **not** count against your monthly API quota. It is the\ncheapest way to pull a large dataset: create the run, poll until it completes,\nmint a URL with `POST /v2/reports/{report_id}/runs/{run_id}/exports`, then\ndownload here.\n\nTokens expire 15 minutes after they are minted.","parameters":[{"schema":{"type":"string","description":"Signed download token from the create-export response"},"required":true,"description":"Signed download token from the create-export response","name":"token","in":"path"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"nullable":true}}}},"401":{"description":"Unauthorized - Authentication is required or has failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"Forbidden - You do not have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error500"}}}}}}}}}
```

## List saved reports

> List saved reports

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"reports","description":"Saved reports, runs and exports"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reports"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"ReportV2":{"type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string","description":"Report type key, e.g. 'product_sales'. See GET /v2/reports/types."},"name":{"type":"string","nullable":true},"filters":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"comparison":{"type":"string"},"values":{"type":"array","items":{"nullable":true}},"value":{"nullable":true}},"required":["name","comparison"]},"description":"Filter set applied to every run. Valid names/comparisons per type come from GET /v2/reports/types."},"timezone":{"type":"string","description":"IANA timezone the report buckets dates in (legacy semantics — unlike /v2/analytics, which is UTC-only)."},"relative_date":{"type":"string","nullable":true,"description":"Date-range preset resolved per run, e.g. 'Last Month'."},"frequency":{"type":"string","nullable":true,"enum":["day","week","month","year",null]},"frequency_count":{"type":"integer","nullable":true},"next_run_at":{"type":"string","nullable":true,"format":"date-time"},"is_active":{"type":"boolean"},"users":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"integer"},"name":{"type":"string"},"email":{"type":"string"}},"required":["user_id"]},"description":"Scheduled-report recipients (account users with report access)."},"created_at":{"type":"string","nullable":true,"format":"date-time"},"updated_at":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","type","name","filters","timezone","relative_date","frequency","frequency_count","next_run_at","is_active","created_at","updated_at"]},"Error401":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error403":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error500":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/v2/reports":{"get":{"tags":["reports"],"summary":"List saved reports","description":"List saved reports","parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Page number"},"required":false,"description":"Page number","name":"page","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"description":"Items per page (max 100)"},"required":false,"description":"Items per page (max 100)","name":"per_page","in":"query"},{"schema":{"type":"string","description":"Filter by type (exact match)."},"required":false,"description":"Filter by type (exact match).","name":"filter[type]","in":"query"},{"schema":{"type":"string","description":"Filter by type (contains)"},"required":false,"description":"Filter by type (contains)","name":"filter[type.contains]","in":"query"},{"schema":{"type":"string","description":"Filter by is_active (exact match). Valid values: true, false."},"required":false,"description":"Filter by is_active (exact match). Valid values: true, false.","name":"filter[is_active]","in":"query"},{"schema":{"type":"string","description":"Filter by is_active (comma-separated list). Fetches many records in one request instead of one request per id."},"required":false,"description":"Filter by is_active (comma-separated list). Fetches many records in one request instead of one request per id.","name":"filter[is_active.in]","in":"query"},{"schema":{"type":"string","description":"Filter by is_active (excluding a comma-separated list)"},"required":false,"description":"Filter by is_active (excluding a comma-separated list)","name":"filter[is_active.nin]","in":"query"},{"schema":{"type":"string","description":"Filter by created_at (exact match)."},"required":false,"description":"Filter by created_at (exact match).","name":"filter[created_at]","in":"query"},{"schema":{"type":"string","description":"Filter by created_at (greater than or equal)"},"required":false,"description":"Filter by created_at (greater than or equal)","name":"filter[created_at.gte]","in":"query"},{"schema":{"type":"string","description":"Filter by created_at (less than or equal)"},"required":false,"description":"Filter by created_at (less than or equal)","name":"filter[created_at.lte]","in":"query"},{"schema":{"type":"string","description":"Sort field (prefix with - for descending)"},"required":false,"description":"Sort field (prefix with - for descending)","name":"sort","in":"query"}],"responses":{"200":{"description":"Successful response with paginated list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ReportV2"}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Current page number"},"limit":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Items per page"},"total":{"type":"integer","description":"Total number of items"},"pages":{"type":"integer","description":"Total number of pages"}},"required":["page","limit","total","pages"]}},"required":["data","pagination"]}}}},"401":{"description":"Unauthorized - Authentication is required or has failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"Forbidden - You do not have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error500"}}}}}}}}}
```

## Create a saved report

> Create a new saved report. Call GET /v2/reports/types (list\_report\_types) first to\
> discover valid type values, filter names, and relative\_date presets.\
> \
> Scheduling: when frequency and relative\_date are set, the report is emailed to its\
> users on the computed schedule — exactly as dashboard-created scheduled reports are.\
> frequency requires relative\_date (a rolling window such as "Last Month").\
> users\[] is optional — each entry takes {user\_id} OR {email} (account users with\
> report access). When scheduling and users is omitted, it defaults to YOU (the\
> authorizing user), so "schedule this and email me" needs no ids at all.\
> \
> next\_run\_at is computed automatically from frequency + frequency\_count; do not set it manually.\
> \
> Reports are created active (is\_active=true, no draft state — unlike the dashboard).\
> When name is omitted, a descriptive name is auto-generated from the type and filters\
> (same as the dashboard) — but pass an explicit name when you want a predictable one.

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"reports","description":"Saved reports, runs and exports"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reports"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"ReportV2Create":{"type":"object","properties":{"type":{"type":"string"},"name":{"type":"string","nullable":true,"maxLength":255},"filters":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"comparison":{"type":"string"},"values":{"type":"array","items":{"nullable":true}},"value":{"nullable":true}},"required":["name","comparison"]},"description":"Filter set applied to every run. Valid names/comparisons per type come from GET /v2/reports/types."},"timezone":{"type":"string"},"relative_date":{"type":"string"},"frequency":{"type":"string","enum":["day","week","month","year"]},"frequency_count":{"type":"integer","minimum":0,"exclusiveMinimum":true},"users":{"type":"array","items":{"$ref":"#/components/schemas/ReportRecipientV2"},"description":"Schedule recipients — {user_id} or {email} each. When scheduling (frequency set) and this is omitted, defaults to the authorizing user."}},"required":["type"]},"ReportRecipientV2":{"type":"object","properties":{"user_id":{"type":"integer"},"email":{"type":"string"}},"description":"Exactly one of user_id or email. Omitting users entirely while scheduling defaults the recipient to the authorizing user."},"ReportV2":{"type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string","description":"Report type key, e.g. 'product_sales'. See GET /v2/reports/types."},"name":{"type":"string","nullable":true},"filters":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"comparison":{"type":"string"},"values":{"type":"array","items":{"nullable":true}},"value":{"nullable":true}},"required":["name","comparison"]},"description":"Filter set applied to every run. Valid names/comparisons per type come from GET /v2/reports/types."},"timezone":{"type":"string","description":"IANA timezone the report buckets dates in (legacy semantics — unlike /v2/analytics, which is UTC-only)."},"relative_date":{"type":"string","nullable":true,"description":"Date-range preset resolved per run, e.g. 'Last Month'."},"frequency":{"type":"string","nullable":true,"enum":["day","week","month","year",null]},"frequency_count":{"type":"integer","nullable":true},"next_run_at":{"type":"string","nullable":true,"format":"date-time"},"is_active":{"type":"boolean"},"users":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"integer"},"name":{"type":"string"},"email":{"type":"string"}},"required":["user_id"]},"description":"Scheduled-report recipients (account users with report access)."},"created_at":{"type":"string","nullable":true,"format":"date-time"},"updated_at":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","type","name","filters","timezone","relative_date","frequency","frequency_count","next_run_at","is_active","created_at","updated_at"]},"Error400":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["bad_request"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error401":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error403":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error409":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["conflict"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error500":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/v2/reports":{"post":{"tags":["reports"],"summary":"Create a saved report","description":"Create a new saved report. Call GET /v2/reports/types (list_report_types) first to\ndiscover valid type values, filter names, and relative_date presets.\n\nScheduling: when frequency and relative_date are set, the report is emailed to its\nusers on the computed schedule — exactly as dashboard-created scheduled reports are.\nfrequency requires relative_date (a rolling window such as \"Last Month\").\nusers[] is optional — each entry takes {user_id} OR {email} (account users with\nreport access). When scheduling and users is omitted, it defaults to YOU (the\nauthorizing user), so \"schedule this and email me\" needs no ids at all.\n\nnext_run_at is computed automatically from frequency + frequency_count; do not set it manually.\n\nReports are created active (is_active=true, no draft state — unlike the dashboard).\nWhen name is omitted, a descriptive name is auto-generated from the type and filters\n(same as the dashboard) — but pass an explicit name when you want a predictable one.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportV2Create"}}}},"responses":{"201":{"description":"Created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportV2"}}}},"400":{"description":"Bad Request - The request was invalid or malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400"}}}},"401":{"description":"Unauthorized - Authentication is required or has failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"Forbidden - You do not have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"409":{"description":"Conflict - The request conflicts with the current state of the resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error409"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error500"}}}}}}}}}
```

## Retrieve a saved report

> Retrieve a single reports by ID

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"reports","description":"Saved reports, runs and exports"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reports"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"ReportV2":{"type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string","description":"Report type key, e.g. 'product_sales'. See GET /v2/reports/types."},"name":{"type":"string","nullable":true},"filters":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"comparison":{"type":"string"},"values":{"type":"array","items":{"nullable":true}},"value":{"nullable":true}},"required":["name","comparison"]},"description":"Filter set applied to every run. Valid names/comparisons per type come from GET /v2/reports/types."},"timezone":{"type":"string","description":"IANA timezone the report buckets dates in (legacy semantics — unlike /v2/analytics, which is UTC-only)."},"relative_date":{"type":"string","nullable":true,"description":"Date-range preset resolved per run, e.g. 'Last Month'."},"frequency":{"type":"string","nullable":true,"enum":["day","week","month","year",null]},"frequency_count":{"type":"integer","nullable":true},"next_run_at":{"type":"string","nullable":true,"format":"date-time"},"is_active":{"type":"boolean"},"users":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"integer"},"name":{"type":"string"},"email":{"type":"string"}},"required":["user_id"]},"description":"Scheduled-report recipients (account users with report access)."},"created_at":{"type":"string","nullable":true,"format":"date-time"},"updated_at":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","type","name","filters","timezone","relative_date","frequency","frequency_count","next_run_at","is_active","created_at","updated_at"]},"Error401":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error403":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error404":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["not_found"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error500":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/v2/reports/{report_id}":{"get":{"tags":["reports"],"summary":"Retrieve a saved report","description":"Retrieve a single reports by ID","parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"reports ID"},"required":true,"description":"reports ID","name":"report_id","in":"path"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportV2"}}}},"401":{"description":"Unauthorized - Authentication is required or has failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"Forbidden - You do not have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error500"}}}}}}}}}
```

## Delete a saved report

> Soft-delete a saved report (sets is\_active=false). The report is no longer returned by the default list. Returns 204 on success.

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"reports","description":"Saved reports, runs and exports"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reports"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"Error401":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error403":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error404":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["not_found"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error500":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/v2/reports/{report_id}":{"delete":{"tags":["reports"],"summary":"Delete a saved report","description":"Soft-delete a saved report (sets is_active=false). The report is no longer returned by the default list. Returns 204 on success.","parameters":[{"schema":{"type":"string","description":"Report ID"},"required":true,"description":"Report ID","name":"report_id","in":"path"}],"responses":{"204":{"description":"Deleted successfully"},"401":{"description":"Unauthorized - Authentication is required or has failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"Forbidden - You do not have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error500"}}}}}}}}}
```

## Update a saved report

> Update an existing saved report. Only the provided fields are changed (partial update). Set name, relative\_date, frequency, or frequency\_count to null to clear them — clearing frequency turns the schedule off (next\_run\_at becomes null). Set is\_active=true to reactivate a soft-deleted report. Supplying users replaces the entire recipient list ({user\_id} or {email} per entry; \[] clears it); when a patch introduces frequency on a report with no recipients and users is omitted, the authorizing user is defaulted. Changing the cadence recomputes next\_run\_at; resending an unchanged frequency leaves the send date where it is.

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"reports","description":"Saved reports, runs and exports"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reports"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"ReportV2Update":{"type":"object","properties":{"name":{"type":"string","nullable":true,"maxLength":255,"description":"Report name. null clears the name."},"filters":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"comparison":{"type":"string"},"values":{"type":"array","items":{"nullable":true}},"value":{"nullable":true}},"required":["name","comparison"]},"description":"Filter set applied to every run. Valid names/comparisons per type come from GET /v2/reports/types."},"timezone":{"type":"string"},"relative_date":{"type":"string","nullable":true,"description":"Date-range preset, e.g. 'Last Month'. null clears the schedule window (only valid when frequency is also null/cleared)."},"frequency":{"type":"string","nullable":true,"enum":["day","week","month","year",null],"description":"Schedule frequency. null clears the schedule (next_run_at becomes null)."},"frequency_count":{"type":"integer","nullable":true,"minimum":0,"exclusiveMinimum":true,"description":"Schedule interval multiplier. null clears it (treated as 1 while frequency is set)."},"users":{"type":"array","items":{"$ref":"#/components/schemas/ReportRecipientV2"},"description":"Replaces the recipient list — {user_id} or {email} each; [] clears it."},"is_active":{"type":"boolean","description":"true reactivates a soft-deleted report; false soft-deletes (same as DELETE)."}}},"ReportRecipientV2":{"type":"object","properties":{"user_id":{"type":"integer"},"email":{"type":"string"}},"description":"Exactly one of user_id or email. Omitting users entirely while scheduling defaults the recipient to the authorizing user."},"ReportV2":{"type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string","description":"Report type key, e.g. 'product_sales'. See GET /v2/reports/types."},"name":{"type":"string","nullable":true},"filters":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"comparison":{"type":"string"},"values":{"type":"array","items":{"nullable":true}},"value":{"nullable":true}},"required":["name","comparison"]},"description":"Filter set applied to every run. Valid names/comparisons per type come from GET /v2/reports/types."},"timezone":{"type":"string","description":"IANA timezone the report buckets dates in (legacy semantics — unlike /v2/analytics, which is UTC-only)."},"relative_date":{"type":"string","nullable":true,"description":"Date-range preset resolved per run, e.g. 'Last Month'."},"frequency":{"type":"string","nullable":true,"enum":["day","week","month","year",null]},"frequency_count":{"type":"integer","nullable":true},"next_run_at":{"type":"string","nullable":true,"format":"date-time"},"is_active":{"type":"boolean"},"users":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"integer"},"name":{"type":"string"},"email":{"type":"string"}},"required":["user_id"]},"description":"Scheduled-report recipients (account users with report access)."},"created_at":{"type":"string","nullable":true,"format":"date-time"},"updated_at":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","type","name","filters","timezone","relative_date","frequency","frequency_count","next_run_at","is_active","created_at","updated_at"]},"Error400":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["bad_request"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error401":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error403":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error404":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["not_found"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error409":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["conflict"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error500":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/v2/reports/{report_id}":{"patch":{"tags":["reports"],"summary":"Update a saved report","description":"Update an existing saved report. Only the provided fields are changed (partial update). Set name, relative_date, frequency, or frequency_count to null to clear them — clearing frequency turns the schedule off (next_run_at becomes null). Set is_active=true to reactivate a soft-deleted report. Supplying users replaces the entire recipient list ({user_id} or {email} per entry; [] clears it); when a patch introduces frequency on a report with no recipients and users is omitted, the authorizing user is defaulted. Changing the cadence recomputes next_run_at; resending an unchanged frequency leaves the send date where it is.","parameters":[{"schema":{"type":"string","description":"Report ID"},"required":true,"description":"Report ID","name":"report_id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportV2Update"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportV2"}}}},"400":{"description":"Bad Request - The request was invalid or malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400"}}}},"401":{"description":"Unauthorized - Authentication is required or has failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"Forbidden - You do not have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404"}}}},"409":{"description":"Conflict - The request conflicts with the current state of the resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error409"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error500"}}}}}}}}}
```

## List runs for a report

> List runs for a report

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"reports","description":"Saved reports, runs and exports"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reports"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"ReportRunV2":{"type":"object","properties":{"id":{"type":"integer"},"report_id":{"type":"integer"},"status":{"type":"string","enum":["pending","running","completed","failed"]},"start_at":{"type":"string","nullable":true,"format":"date-time"},"end_at":{"type":"string","nullable":true,"format":"date-time"},"started_at":{"type":"string","nullable":true,"format":"date-time"},"completed_at":{"type":"string","nullable":true,"format":"date-time"},"error_reason":{"type":"string","nullable":true},"stats":{"type":"object","nullable":true,"properties":{"flat_stats":{"type":"object","additionalProperties":{"type":"object","properties":{"value":{"type":"number"},"label":{"type":"string"},"data_type":{"type":"string"}},"required":["value","label","data_type"]}}},"description":"Present on a completed run: the summary stat block (small, conversationally useful). null when the run computed no stats OR its stored data has expired — check data_expired."},"data_expired":{"type":"boolean","description":"Present on a completed run. true means the run's stored result data has been deleted (retained ~1 year), so stats is null and results return zero rows. Re-run the report rather than reading it as zero activity — but note a new run uses the report's current settings, so a relative date range covers the period ending now rather than this run's dates."},"created_at":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","report_id","status","start_at","end_at","started_at","completed_at","error_reason","created_at"]},"Error401":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error403":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error500":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/v2/reports/{report_id}/runs":{"get":{"tags":["reports"],"summary":"List runs for a report","description":"List runs for a report","parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Page number"},"required":false,"description":"Page number","name":"page","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"description":"Items per page (max 100)"},"required":false,"description":"Items per page (max 100)","name":"per_page","in":"query"},{"schema":{"type":"string","description":"Sort field (prefix with - for descending)"},"required":false,"description":"Sort field (prefix with - for descending)","name":"sort","in":"query"}],"responses":{"200":{"description":"Successful response with paginated list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ReportRunV2"}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Current page number"},"limit":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Items per page"},"total":{"type":"integer","description":"Total number of items"},"pages":{"type":"integer","description":"Total number of pages"}},"required":["page","limit","total","pages"]}},"required":["data","pagination"]}}}},"401":{"description":"Unauthorized - Authentication is required or has failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"Forbidden - You do not have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error500"}}}}}}}}}
```

## Create a report run (queued for background execution)

> Create a new report run. Returns 202 Accepted with the run in "pending" status.\
> Execution is asynchronous: a background worker picks up pending runs, so runs\
> typically START within about 30 seconds of creation, then take a few seconds to\
> a few minutes to finish depending on data volume.\
> \
> Polling: call get\_report\_run until status is "completed" or "failed". Each poll\
> counts against the monthly API quota — poll no faster than every \~30 seconds\
> (matches the worker pickup cadence); typical runs complete within a couple of minutes.\
> \
> Reading results: when completed, the run includes a stats block (flat\_stats) that\
> answers most questions — total revenue, count, etc. — without fetching rows.\
> Read stats first; only fetch rows via list\_report\_run\_results if you need detail.\
> \
> The run inherits the report's filters, timezone, and date range. For relative\_date\
> presets (e.g. "Last Month"), the start/end dates are resolved at run time.\
> The report must have a date range — relative\_date or a report\_date filter —\
> or this returns 400 (every report type date-filters its results).

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"reports","description":"Saved reports, runs and exports"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reports"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"ReportRunV2":{"type":"object","properties":{"id":{"type":"integer"},"report_id":{"type":"integer"},"status":{"type":"string","enum":["pending","running","completed","failed"]},"start_at":{"type":"string","nullable":true,"format":"date-time"},"end_at":{"type":"string","nullable":true,"format":"date-time"},"started_at":{"type":"string","nullable":true,"format":"date-time"},"completed_at":{"type":"string","nullable":true,"format":"date-time"},"error_reason":{"type":"string","nullable":true},"stats":{"type":"object","nullable":true,"properties":{"flat_stats":{"type":"object","additionalProperties":{"type":"object","properties":{"value":{"type":"number"},"label":{"type":"string"},"data_type":{"type":"string"}},"required":["value","label","data_type"]}}},"description":"Present on a completed run: the summary stat block (small, conversationally useful). null when the run computed no stats OR its stored data has expired — check data_expired."},"data_expired":{"type":"boolean","description":"Present on a completed run. true means the run's stored result data has been deleted (retained ~1 year), so stats is null and results return zero rows. Re-run the report rather than reading it as zero activity — but note a new run uses the report's current settings, so a relative date range covers the period ending now rather than this run's dates."},"created_at":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","report_id","status","start_at","end_at","started_at","completed_at","error_reason","created_at"]},"Error401":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error403":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error404":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["not_found"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error409":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["conflict"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error500":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/v2/reports/{report_id}/runs":{"post":{"tags":["reports"],"summary":"Create a report run (queued for background execution)","description":"Create a new report run. Returns 202 Accepted with the run in \"pending\" status.\nExecution is asynchronous: a background worker picks up pending runs, so runs\ntypically START within about 30 seconds of creation, then take a few seconds to\na few minutes to finish depending on data volume.\n\nPolling: call get_report_run until status is \"completed\" or \"failed\". Each poll\ncounts against the monthly API quota — poll no faster than every ~30 seconds\n(matches the worker pickup cadence); typical runs complete within a couple of minutes.\n\nReading results: when completed, the run includes a stats block (flat_stats) that\nanswers most questions — total revenue, count, etc. — without fetching rows.\nRead stats first; only fetch rows via list_report_run_results if you need detail.\n\nThe run inherits the report's filters, timezone, and date range. For relative_date\npresets (e.g. \"Last Month\"), the start/end dates are resolved at run time.\nThe report must have a date range — relative_date or a report_date filter —\nor this returns 400 (every report type date-filters its results).","parameters":[{"schema":{"type":"string","description":"Report ID"},"required":true,"description":"Report ID","name":"report_id","in":"path"}],"responses":{"201":{"description":"Created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportRunV2"}}}},"401":{"description":"Unauthorized - Authentication is required or has failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"Forbidden - You do not have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404"}}}},"409":{"description":"Conflict - The request conflicts with the current state of the resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error409"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error500"}}}}}}}}}
```

## Retrieve a report run

> Retrieve a single reports by ID

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"reports","description":"Saved reports, runs and exports"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reports"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"ReportRunV2":{"type":"object","properties":{"id":{"type":"integer"},"report_id":{"type":"integer"},"status":{"type":"string","enum":["pending","running","completed","failed"]},"start_at":{"type":"string","nullable":true,"format":"date-time"},"end_at":{"type":"string","nullable":true,"format":"date-time"},"started_at":{"type":"string","nullable":true,"format":"date-time"},"completed_at":{"type":"string","nullable":true,"format":"date-time"},"error_reason":{"type":"string","nullable":true},"stats":{"type":"object","nullable":true,"properties":{"flat_stats":{"type":"object","additionalProperties":{"type":"object","properties":{"value":{"type":"number"},"label":{"type":"string"},"data_type":{"type":"string"}},"required":["value","label","data_type"]}}},"description":"Present on a completed run: the summary stat block (small, conversationally useful). null when the run computed no stats OR its stored data has expired — check data_expired."},"data_expired":{"type":"boolean","description":"Present on a completed run. true means the run's stored result data has been deleted (retained ~1 year), so stats is null and results return zero rows. Re-run the report rather than reading it as zero activity — but note a new run uses the report's current settings, so a relative date range covers the period ending now rather than this run's dates."},"created_at":{"type":"string","nullable":true,"format":"date-time"}},"required":["id","report_id","status","start_at","end_at","started_at","completed_at","error_reason","created_at"]},"Error401":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error403":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error404":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["not_found"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error500":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/v2/reports/{report_id}/runs/{run_id}":{"get":{"tags":["reports"],"summary":"Retrieve a report run","description":"Retrieve a single reports by ID","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportRunV2"}}}},"401":{"description":"Unauthorized - Authentication is required or has failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"Forbidden - You do not have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error500"}}}}}}}}}
```

## Retrieve report run results

> Get paginated tabular results for a completed report run

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"reports","description":"Saved reports, runs and exports"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reports"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"ReportRunResultsV2":{"type":"object","properties":{"dataset":{"type":"string"},"columns":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"label":{"type":"string"},"data_type":{"type":"string"}},"required":["name","label","data_type"]}},"rows":{"type":"array","items":{"type":"array","items":{"nullable":true}}}},"required":["dataset","columns","rows"]},"Error401":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error403":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error500":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/v2/reports/{report_id}/runs/{run_id}/results":{"get":{"tags":["reports"],"summary":"Retrieve report run results","description":"Get paginated tabular results for a completed report run","parameters":[{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Page number"},"required":false,"description":"Page number","name":"page","in":"query"},{"schema":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":100,"description":"Items per page (max 100)"},"required":false,"description":"Items per page (max 100)","name":"per_page","in":"query"},{"schema":{"type":"string","description":"Sort field (prefix with - for descending)"},"required":false,"description":"Sort field (prefix with - for descending)","name":"sort","in":"query"}],"responses":{"200":{"description":"Successful response with paginated list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ReportRunResultsV2"}},"pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Current page number"},"limit":{"type":"integer","minimum":0,"exclusiveMinimum":true,"description":"Items per page"},"total":{"type":"integer","description":"Total number of items"},"pages":{"type":"integer","description":"Total number of pages"}},"required":["page","limit","total","pages"]}},"required":["data","pagination"]}}}},"401":{"description":"Unauthorized - Authentication is required or has failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"Forbidden - You do not have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error500"}}}}}}}}}
```

## Create a short-lived signed CSV download URL for a completed report run

> Generates a signed download URL for the full dataset of a completed run.\
> One quota call, zero context — the URL is handed to the user or fetched with local\
> tooling (e.g. curl). The URL requires no authentication (the signed token IS the\
> credential). Expires in 15 minutes.\
> \
> Run must be completed (status=completed) — 409 otherwise; poll get\_report\_run first.\
> \
> Query/body param:\
> &#x20; dataset — which dataset to download (default: "default"); 400 lists available datasets.\
> \
> Response: { data: { url: string, expires\_at: ISO8601 } }

```json
{"openapi":"3.0.3","info":{"title":"Spiffy API","version":"2.0.0"},"tags":[{"name":"reports","description":"Saved reports, runs and exports"}],"servers":[{"url":"https://api.spiffy.co","description":"Production"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["reports"]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Account API key authentication. Pass an API key as a Bearer token in the `Authorization` header. An account may have multiple named keys; any of them grants full access to all endpoints — equivalent to all OAuth scopes."},"OAuth2":{"type":"oauth2","description":"OAuth 2.0 authentication for third-party integrations. Access is limited to the scopes granted by the merchant during authorization.","flows":{"authorizationCode":{"authorizationUrl":"https://app.spiffy.co/oauth/authorize","tokenUrl":"https://api.spiffy.co/oauth/token","refreshUrl":"https://api.spiffy.co/oauth/token","scopes":{"account":"Access account details and settings","users":"Manage users","customers":"Read and manage customers","checkouts":"Read and manage checkouts","subscriptions":"Read and manage subscriptions","subscription_metered_billing":"Manage metered billing for subscriptions","integrations":"Manage integrations","orders":"Read and manage orders","payments":"Read and manage payments","paymentplans":"Read and manage payment plans","webhooks":"Manage webhook endpoints and view event logs","promos":"Read and manage promotions and their codes","affiliates":"Read and manage affiliates and programs","products":"Read and manage products","analytics":"Read analytics data (revenue, orders, subscriptions, MRR)","reports":"Create, run, and read saved reports and their results"}}}}},"schemas":{"ReportExportV2":{"type":"object","properties":{"url":{"type":"string","description":"Short-lived signed download URL for the full CSV. No authentication needed; expires quickly."},"expires_at":{"type":"string","nullable":true,"format":"date-time"}},"required":["url","expires_at"]},"Error401":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error403":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["forbidden"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error404":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["not_found"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error409":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["conflict"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]},"Error500":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["internal_error"]},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/v2/reports/{report_id}/runs/{run_id}/exports":{"post":{"tags":["reports"],"summary":"Create a short-lived signed CSV download URL for a completed report run","description":"Generates a signed download URL for the full dataset of a completed run.\nOne quota call, zero context — the URL is handed to the user or fetched with local\ntooling (e.g. curl). The URL requires no authentication (the signed token IS the\ncredential). Expires in 15 minutes.\n\nRun must be completed (status=completed) — 409 otherwise; poll get_report_run first.\n\nQuery/body param:\n  dataset — which dataset to download (default: \"default\"); 400 lists available datasets.\n\nResponse: { data: { url: string, expires_at: ISO8601 } }","parameters":[{"schema":{"type":"string","description":"Report ID"},"required":true,"description":"Report ID","name":"report_id","in":"path"},{"schema":{"type":"string","description":"Run ID"},"required":true,"description":"Run ID","name":"run_id","in":"path"}],"responses":{"201":{"description":"Created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportExportV2"}}}},"401":{"description":"Unauthorized - Authentication is required or has failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error401"}}}},"403":{"description":"Forbidden - You do not have permission to access this resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error403"}}}},"404":{"description":"Not Found - The requested resource does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error404"}}}},"409":{"description":"Conflict - The request conflicts with the current state of the resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error409"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error500"}}}}}}}}}
```
