billing

Get current usage against effective limits

Changed on

GET /billing/usage/ -- current usage against effective limits, per resource, plus billing_state, the plan snapshot, the current billing period's bounds, the plan/add-on split of each ceiling, per-scope attribution across the caller's pooled subtree, and the overage accrued so far this cycle. Resolved at the billing root, same as every other read in this app.

The "pull" half of "an scope can see where it stands". It reads usage through EntitlementService.effective_limit_from_resolved / usage_breakdown_for_root -- pre-resolved entry points onto the identical get_effective_limit / get_current_usage implementation check_limit / check_postpaid_allowance count against, and that vinta_billing.services.usage_warning_service.UsageWarningService (the "push" half -- proactive approaching-limit notifications) also reads its ceiling from -- so this endpoint, the enforcement checks, and the beat warning can never disagree about a number.

No permission beyond IsAuthenticated, deliberately -- a read never blocks, including for a RESTRICTED scope (a RESTRICTED scope has its writes blocked and sync paused, never its reads; an scope must be able to see exactly what it needs to resolve before it can act on it).

get/billing/usage/retrieve_usage{format}

Request

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

Path parameters

format'.json' required

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

billing_statestring required
billing_root_scope_idinteger required

pk of the billing root this response was resolved against.

estimated_overage_totalstring decimal required

Overage money accrued so far in the current, open billing period -- MeteredOccurrenceQuerySet.overage_total() over the caller's pooled subtree. Accrued-to-date, never a projection of the whole cycle. "0.0000" when there is no subscription.

Changes

    • ▲

      removed the required property from the response with the status

    • ▲

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

    • ○

      added the required property to the response with the status

    • ○

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

    • ○

      added the required property to the response with the status

    • ○

      added the required property to the response with the status

    • ○

      added the required property to the response with the status

    • ○

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

    • ○

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

    • ○

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

    • ○

      added the required property to the response with the status