Sign in
billing

List metered occurrences behind post-paid charges

Changed on

GET /billing/usage/occurrences/ -- the line-item ledger behind post-paid charges: every MeteredOccurrence row in the caller's pooled billing subtree, paginated and filterable by period, allowance side, scope, and occurrence-start range, so a customer disputing an invoice can tie every unit of money to a specific occurrence.

Stricter than every other read in this module. BillingUsageViewSet and BillingPeriodViewSet stay open to any authenticated member (IsAuthenticated alone); this one additionally requires IsBillingManager. A ledger row carries an event_id and an exact occurrence_start -- that is calendar content, and it spans every calendar in the caller's pooled subtree, including ones the caller has no membership scope on. A count is not.

check_object_permissions is called explicitly in list() against the resolved billing root -- the same two-step dance SubscriptionViewSet.get_subscription and AddOnViewSet.create already perform, and for the same reason their comments document: has_permission cannot know which scope this read is for, because request.scope is not resolved yet at that point in TenantScopedViewMixin.initial()'s ordering (see IsBillingManager's docstring).

get/billing/usage/occurrences{format}

Request

  • The document declares no server URL.
  • Auth: one of:
    • HTTP bearer
    • API key in cookie sessionid

Path parameters

format'.json' required

Query parameters

billing_period_startstring date-time

Only rows billed to this exact period. Defaults to the current, open billing period when omitted.

is_within_allowanceboolean

Filter by whether the occurrence fell inside the included allowance

limitinteger

Number of results to return per page.

occurrence_start_afterstring date-time

Only occurrences starting on or after this instant (inclusive).

occurrence_start_beforestring date-time

Only occurrences starting on or before this instant (inclusive).

offsetinteger

The initial index from which to return the results.

orderingstring[]

Order by occurrence_start. Prefix with '-' for descending. Defaults to -occurrence_start (newest first).

  • occurrence_start - Occurrence start
  • -occurrence_start - Occurrence start (descending)
scopeinteger

Only rows attributed to this scope. Must be inside the caller's pooled billing subtree -- an id outside it is a validation error, not an empty result.

Headers

X-Organization-Idstring

Selects the active organization for this request. Optional for callers that belong to exactly one active organization — the single membership is resolved implicitly. Required when the caller has two or more active memberships; omitting it in that case returns 400. If the header names an organization the caller is not an active member of, the server returns 403.

Response

countinteger required
nextstring uri nullable
previousstring uri nullable

Example response

{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100"
}

Changes

  • f3e96ee789afRevision changes
    • ▲

      removed the required property // from the response with the status

    • ●

      deleted the query request parameter organization

    • ○

      added the new optional query request parameter scope

    • ○

      added the required property // to the response with the status

  • 7fe3d926c5e3Revision changes
    • ▲

      removed the required property /////// from the response with the status

    • ▲

      removed the required property /////// from the response with the status

    • ▲

      removed the required property /////// from the response with the status