reports

Stable. Describes behaviour that is built and covered by tests in this repository.

API reference

GET /v1/reports/revenue #

Invoices summed by period, payment provider, customer country and currency (currencies are never added together)

Parameters

NameInTypeDescription
fromquerystringFirst period, YYYY-MM
toquerystringLast period, YYYY-MM
group_byquerystringComma-separated: period, provider, country (default period). Currency is always split

Responses

StatusMeaningBody
200OKGetRevenueReportResponse
400Error envelopeError
Example response
{
  "rows": [
    {
      "period": "string",
      "provider": "string",
      "country": "string",
      "currency": "string",
      "invoices": "string",
      "billed_minor": "string",
      "collected_minor": "string",
      "refunded_minor": "string",
      "outstanding_minor": "string",
      "uncollectible_minor": "string",
      "void_minor": "string",
      "credited_minor": "string"
    }
  ]
}
curl
curl -X GET https://YOUR-API-ADDRESS/v1/reports/revenue \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY"

GET /v1/reports/dunning #

Invoices whose payment has not gone through (declined and retrying, outcome unknown, given up)

Parameters

NameInTypeDescription
limitqueryinteger

Responses

StatusMeaningBody
200OKGetDunningReportResponse
400Error envelopeError
Example response
{
  "invoices": [
    {
      "invoice_id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
      "number": "string",
      "customer_external_id": "string",
      "period": "string",
      "provider": "string",
      "currency": "string",
      "total_minor": "string",
      "state": "PAYMENT_DECLINED",
      "dunning_attempt": 1,
      "next_attempt_time": "2026-11-03T10:15:00Z",
      "last_error": "string"
    }
  ],
  "summary": [
    {
      "state": "string",
      "provider": "string",
      "currency": "string",
      "invoices": "string",
      "total_minor": "string"
    }
  ]
}
curl
curl -X GET https://YOUR-API-ADDRESS/v1/reports/dunning \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY"

GET /v1/reports/subscriptions #

Subscriptions and monthly recurring revenue at the end of a month, with the new and the churned, by provider, country and currency

Parameters

NameInTypeDescription
monthquerystringYYYY-MM in the tenant's time zone; default the current month
group_byquerystringComma-separated: provider, country. Currency is always split

Responses

StatusMeaningBody
200OKGetSubscriptionReportResponse
400Error envelopeError
Example response
{
  "month": "string",
  "rows": [
    {
      "provider": "string",
      "country": "string",
      "currency": "string",
      "active": "string",
      "trialing": "string",
      "paused": "string",
      "past_due": "string",
      "mrr_minor": "string",
      "new_subscriptions": "string",
      "new_mrr_minor": "string",
      "churned": "string",
      "churned_mrr_minor": "string",
      "plan_code": "string"
    }
  ]
}
curl
curl -X GET https://YOUR-API-ADDRESS/v1/reports/subscriptions \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY"

Models

Error

FieldTypeDescription
error requiredobject

GetDunningReportInvoice

FieldTypeDescription
invoice_id requiredstring · uuid
number requiredstring
customer_external_id requiredstring
period requiredstring
provider requiredstring
currency requiredstring
total_minor requiredstring · int64
state requiredPAYMENT_DECLINED | PAYMENT_UNKNOWN | PAYMENT_PENDING | PAYMENT_ACTION_REQUIRED | PAYMENT_HELD | UNCOLLECTIBLE
dunning_attempt requiredinteger
next_attempt_time requiredstring · date-time
last_error requiredstring

GetDunningReportResponse

FieldTypeDescription
invoices requiredarray of GetDunningReportInvoice
summary requiredarray of GetDunningReportSummary

GetDunningReportSummary

FieldTypeDescription
state requiredstring
provider requiredstring
currency requiredstring
invoices requiredstring · int64
total_minor requiredstring · int64

GetRevenueReportResponse

FieldTypeDescription
rows requiredarray of GetRevenueReportRow

GetRevenueReportRow

FieldTypeDescription
period requiredstring
provider requiredstring
country requiredstring
currency requiredstring
invoices requiredstring · int64
billed_minor requiredstringFinalized invoices that are not void, format: int64
collected_minor requiredstringPaid, format: int64
refunded_minor requiredstringInvoices that were refunded, format: int64
outstanding_minor requiredstringOpen, format: int64
uncollectible_minor requiredstring · int64
void_minor requiredstring · int64
credited_minor requiredstringCredit notes issued against these invoices, format: int64

GetSubscriptionReportResponse

FieldTypeDescription
month requiredstring
rows requiredarray of GetSubscriptionReportRow

GetSubscriptionReportRow

FieldTypeDescription
provider requiredstring
country requiredstring
currency requiredstring
active requiredstring · int64
trialing requiredstring · int64
paused requiredstring · int64
past_due requiredstring · int64
mrr_minor requiredstringFixed fees per month of active and past due subscriptions, format: int64
new_subscriptions requiredstring · int64
new_mrr_minor requiredstring · int64
churned requiredstringEnded with no successor; a plan change or provider migration is not churn, format: int64
churned_mrr_minor requiredstring · int64
plan_code requiredstring