Get usage snapshot for a month

get

https://api.benjipays.com/v2/usage

Access: Requires DISTRIBUTOR actor type

Returns usage data for all Organizations under the authenticated distributor for a specified month. Used by distributors (e.g., Sherweb) to show consumption in marketplace dashboards.

Important Notes:

Always calculates for entire month (MTD if current month, full month if past)
endDate is validated but effectively ignored for calculation
NFR plans are represented as $0 plans, no separate flag
Each organization may have 1+ items: base plan SKU + one row per overage tier (BENJI-{PLAN}-OVERAGE-TIER{n})

Calculation:

Uses existing billing.js helpers (getPlanTypeFromUser)
Queries results collection for transaction counts
Uses user.billing.details for plan info (priceRanges)
Integrates with autopay.isCompanyInFreeTrial() for trial status

Requires JWT authentication and 'partners:usage:read' scope.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Query Params

startDate

string

required

Start date - must be the 1st of the month (YYYY-MM-01)

endDate

string

required

End date - must be in the same month as startDate (YYYY-MM-DD). Note: Effectively ignored for calculation - always calculates for entire month (MTD if current month, full month if past)

partnerId

string

^[0-9a-fA-F]{24}$

Optional filter by specific partner (MongoDB ObjectId)

organizationId

string

^[0-9a-fA-F]{24}$

Optional filter by specific organization (MongoDB ObjectId)

limit

integer

1 to 500

Maximum number of results to return (default: 100, max: 500)

offset

integer

0 to 9007199254740991

Number of results to skip for pagination (default: 0)

Headers

X-Request-ID

uuid

Optional client-supplied unique ID for one request. The server generates a UUID v4 if omitted and always echoes the value in the response.

X-Correlation-ID

uuid

Optional ID that flows across service boundaries for distributed tracing. The server generates a UUID v4 if omitted and always echoes the value in the response.

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

200Successful response with usage snapshot

400Bad Request - Invalid date format or dates not in same month

401Unauthorized - Invalid or missing authentication token

403Forbidden - Distributor actor type required

429Too Many Requests - Rate limit exceeded