Usage and Cost Management

Author(s)

• Faizal Khan

---

Last Updated Date

2026-03-18

---

SRS References

---

Version History

Version	Date	Author	Changes
1.0	2026-03-18	Faizal Khan	Initial usage APIs document

---

Feature Overview

The Usage APIs provide the ability to view data fetching usage for dealers across the system. It consists of two APIs (for now):

1. Aggregated Usage API: Fetches all dealers with their aggregated usage statistics (new, changed, and total records) based on a specified date range. Provides pagination.
2. Daily Breakdown API: Fetches daily usage breakdown for a specific dealer within a specified date range.

---

Request and Response Models

UsageSortBy Enum

public enum UsageSortBy
{
    DealerName = 1,
    DealerCode = 2,
    TotalRecords = 3,
    NewRecords = 4,
    ChangedRecords = 5
}

UsageFilter

public record UsageFilter
{
    public DateTime? StartDate { get; init; }
    public DateTime? EndDate { get; init; }
    public string? SearchKeyword { get; init; } // Searches against Dealer name and code
    public UsageSortBy? SortBy { get; init; } // Defaults to DealerName
    public SortOrder? SortOrder { get; init; } // Defaults to Ascending
    public int PageNumber { get; init; } = 1;
    public int RowsPerPage { get; init; } = 10;
}

UsageResponse

public record UsageResponse
{
    public Guid DealerId { get; init; }
    public string DealerName { get; init; } = string.Empty;
    public string DealerCode { get; init; } = string.Empty;
    public int NewRecords { get; init; }
    public int ChangedRecords { get; init; }
    public int TotalRecords { get; init; } // Sum of NewRecords + ChangedRecords
}

DailyUsageFilter

public record DailyUsageFilter
{
    public DateTime? StartDate { get; init; }
    public DateTime? EndDate { get; init; }
}

DailyUsageResponse

public record DailyUsageResponse
{
    public DateTime Date { get; init; }
    public int NewRecords { get; init; }
    public int ChangedRecords { get; init; }
    public int TotalRecords { get; init; }
}

ServerPaginatedData<T>

public class ServerPaginatedData<T>
{
    public List<T> Data { get; set; } = [];
    public int TotalNumber { get; set; }
    public bool HasPreviousPage { get; set; }
    public bool HasNextPage { get; set; }
    public int TotalPages { get; set; }
    public int PageNumber { get; set; }
    public int RowsPerPage { get; set; }
}

---

API Interfaces

Endpoint	Method	Purpose	Parameters	Request Model	Response Model	Status Codes
/usages	GET	Retrieve paginated list of dealer usage aggregated data within a date range	JWT in header, pagination & filter queries	UsageFilter (as FromQuery)	ServerPaginatedData<UsageResponse>	200, 400, 401, 403, 500
/usages/{dealerId}	GET	Retrieve daily breakdown of usage for a specific dealer	JWT in header, dealerId in path, queries	DailyUsageFilter (as FromQuery)	List<DailyUsageResponse>	200, 400, 401, 403, 500

---

API Examples

Get Usage Example

Request:

GET /usages?pageNumber=1&rowsPerPage=10&startDate=2026-03-01T00:00:00Z&endDate=2026-03-31T23:59:59Z
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Success Response (200 OK):

{
  "data": [
    {
      "dealerId": "123e4567-e89b-12d3-a456-426614174000",
      "dealerName": "Premium Auto Group",
      "dealerCode": "DL-00025",
      "newRecords": 342,
      "changedRecords": 905,
      "totalRecords": 1247
    }
  ],
  "totalNumber": 1,
  "hasPreviousPage": false,
  "hasNextPage": false,
  "totalPages": 1,
  "pageNumber": 1,
  "rowsPerPage": 10
}

Error Response (401 Unauthorized):

{
  "status": 401,
  "message": "Invalid or expired token."
}

Error Response (403 Forbidden):

{
  "status": 403,
  "message": "You do not have permission to access these usage logs."
}

Get Daily Breakdown Example

Request:

GET /usages/123e4567-e89b-12d3-a456-426614174000?startDate=2026-03-01T00:00:00Z&endDate=2026-03-05T23:59:59Z
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Success Response (200 OK):

[
  {
    "date": "2026-03-01T00:00:00Z",
    "newRecords": 10,
    "changedRecords": 20,
    "totalRecords": 30
  },
  {
    "date": "2026-03-02T00:00:00Z",
    "newRecords": 15,
    "changedRecords": 25,
    "totalRecords": 40
  }
]

Error Response (401 Unauthorized):

{
  "status": 401,
  "message": "Invalid or expired token."
}

Error Response (403 Forbidden):

{
  "status": 403,
  "message": "You do not have permission to access usage logs for this dealer."
}