Get Spending Report by Account Grouped by Merchant Category

The GET /api/userReport/spendingReportByAccountGroupByCategory/v2 endpoint retrieves a spending report for a specified financial account, grouping all transaction data by merchant category. It returns aggregated totals per category along with each category's percentage share of total spending. This enables partners and customers to analyze expenditure patterns and support budgeting and financial planning decisions.

Endpoint

GET /api/userReport/spendingReportByAccountGroupByCategory/v2

Authentication

Bearer token required. Obtain via:

POST https://api.banking.netevia.dev/api/auth/v2

Include in header: Authorization: Bearer {token}
Token lifetime: 10 minutes. Refresh via POST /api/auth/refresh.

When to use

Use this endpoint when you need to present a categorized breakdown of a customer's spending for a given financial account over a specific time period. It is suited for building personal finance dashboards, budgeting tools, or monthly spending summaries. Both business and personal customer contexts are supported wherever merchant category reporting is required.

Query Parameters

Response

200 OK

{
  "categories": [
    {
      "category": "Groceries",
      "amount": 45200,
      "percentage": 35.5
    },
    {
      "category": "Restaurants",
      "amount": 23100,
      "percentage": 18.2
    },
    {
      "category": "Travel",
      "amount": 31500,
      "percentage": 24.8
    },
    {
      "category": "Entertainment",
      "amount": 12300,
      "percentage": 9.7
    },
    {
      "category": "Other",
      "amount": 14900,
      "percentage": 11.8
    }
  ],
  "total": 127000
}

Error Codes

Common Mistakes

• Omitting finAccountId: this is the primary identifier for the account to report on and must be provided.
• Using an incorrect date format for from or to: values must be full ISO 8601 date-time strings (e.g., 2024-01-01T00:00:00Z), not date-only strings.
• Assuming amount values are in dollars: all monetary amounts are returned in the smallest currency unit (cents for USD). Divide by 100 to display as dollars.
• Querying an account that belongs to a different partner or customer than the one associated with the Bearer token will result in a 403 error.

Related Endpoints

• GET /api/userReport/spendingReportByAccountGroupByCategory/v1 — Earlier version of the same spending-by-category report.
• GET /api/userReport/spendingReportByAccount/v2 — Retrieves a spending report for a financial account without category grouping.
• GET /api/userReport/transactionsByAccount/v2 — Retrieves individual transaction records for a financial account.

Example

curl -X GET "https://api.banking.netevia.dev/api/userReport/spendingReportByAccountGroupByCategory/v2?finAccountId=XXXXXXXXXX&from=2024-01-01T00%3A00%3A00Z&to=2024-01-31T23%3A59%3A59Z" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"