Total Spend Amount by Category

This endpoint retrieves spending data distributed across different categories for a specified time period. For each category, it returns the total amount spent along with that category's percentage share of overall spending. It is useful for analyzing customer spending behavior and tracking trends across business accounts.

Endpoint

GET /api/Widget/SpendsByCategory

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 a breakdown of spending by category for a given reporting period. It is well suited for partner dashboards that display spending analytics, and for business customers seeking to understand how their cardholders are spending across categories such as groceries, utilities, or travel. Optional filters allow narrowing results to a specific ISO or agent.

Query Parameters

Response

200 OK

Returns an array of spending category objects.

[
  {
    "category": "Groceries",
    "amount": 154200,
    "percentage": 32.5
  },
  {
    "category": "Utilities",
    "amount": 87500,
    "percentage": 18.4
  },
  {
    "category": "Dining",
    "amount": 63000,
    "percentage": 13.3
  },
  {
    "category": "Travel",
    "amount": 41800,
    "percentage": 8.8
  },
  {
    "category": "Other",
    "amount": 127500,
    "percentage": 27.0
  }
]

Error Codes

Common Mistakes

• Providing period in an incorrect format — use ISO 8601 date-time (e.g., 2025-01-01T00:00:00Z) rather than a plain date string.
• Omitting the period parameter when a specific reporting window is intended — without it, the API may return data for a default or undefined period.
• Expecting amount in whole currency units — the field is expressed in the smallest currency unit (cents), so 154200 represents $1,542.00.
• Using isoId or agentId values that do not belong to the authenticated partner, which will result in empty or unauthorized responses.

Related Endpoints

• GET /api/Widget/SpendsByMerchant — Retrieves total spend amount broken down by merchant
• GET /api/Widget/SpendsByTime — Retrieves spending data distributed across time intervals
• GET /api/Widget/TransactionSummary — Returns an aggregated summary of transactions for a period

Example

curl -X GET "https://api.banking.netevia.dev/api/Widget/SpendsByCategory?period=2025-01-01T00%3A00%3A00Z&isoId=101&agentId=55" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"