Billing Usage

The Billing Usage API allows authorized users to retrieve aggregated message usage for a selected organization and billing period.

The feature does not calculate charges, generate invoices, or apply pricing rules. It only provides aggregated usage data that can later be used by the Platform Holder for billing and invoicing purposes.

The API does not return individual message-level billing records. It returns aggregated totals showing how many messages were requested to be sent during the selected period.

Usage Data represents aggregated records of message sending activity within the Digital Postbox Platform during a selected billing period.

Billing is based on the number of messages requested to be sent.

Each "Message Sent" event represents one message sent to one recipient.

Example:

• 1 message sent to 1 recipient = 1 billable event
• 10 messages sent to 10 recipients = 10 billable events

Usage Data includes:

• messages sent by senders in the selected organization
• messages sent by senders in descendant sub-organizations
• messages that fail due to incorrect sender-provided delivery information will still count toward usage totals
• recalled messages

:::attention Internal system retries are not counted as additional usage. :::

The Billing Usage API can be used by authorized users with permission to retrieve billing usage data.

Access is restricted through the retrieve billing data permission.

Users can only retrieve usage data for organizations they are explicitly or implicitly members of.

If the targetOrganizationId is a parent organization that the user has access to, the user can retrieve usage data for that organization and all of its descendant sub-organizations, even without direct access to the descendants.

If the targetOrganizationId is an organization that the user does not have access to, the request is forbidden and no usage data is returned.

This section describes how usage data is grouped, calculated, and returned by the API.

Organizations in the platform are arranged in a hierarchical structure under a Platform Holder. Each organization may have one or multiple sender entities associated with it.

Example hierarchy:

• Police Department
  • Finance Services Sender
  • HR Sender
  • Traffic Department
    • Traffic Services Sender
  • Criminal Investigation Department
    • Legal Services Sender

In this example:

• Police Department has two sender entities of its own
• Traffic Department and Criminal Investigation Department are sub-organizations
• Each sub-organization also has its own sender entities

When usage data is requested for an organization, the response includes:

• total usage for the entire organizational hierarchy
• usage for descendant sub-organizations
• usage for sender entities belonging to organizations within that hierarchy

Example:

If usage is requested for the Police Department, the response includes:

• total usage for Police Department, Traffic Department, and Criminal Investigation Department combined
• usage for Finance Services Sender
• usage for HR Sender
• usage for Traffic Department
• usage for Traffic Services Sender
• usage for Criminal Investigation Department
• usage for Legal Services Sender

:::info The API does not currently provide a separate total showing only usage generated directly by the Police Department itself.

Direct usage for the Police Department can instead be calculated by either:

• subtracting descendant sub-organization totals from the hierarchy total
• or adding together usage from the Police Department's own sender entities (Finance Services Sender + HR Sender) :::

This structure allows usage data to be retrieved at both organizational and hierarchy level without issuing separate requests for each sub-organization.

Usage data is aggregated using the timezone provided in the request.

The requested billing period is interpreted as calendar days in the specified timezone and then converted internally to UTC for data retrieval. This ensures that the returned usage data reflects the local business calendar of the requesting organization or Platform Holder.

Example:

A request using:

• start=2026-01-01
• end=2026-01-31
• tz=Europe/Copenhagen

returns all usage events that occurred within that local calendar period in the Europe/Copenhagen timezone.

The platform automatically accounts for daylight saving time (DST) changes when calculating billing periods.

When a requested period includes a DST transition, the system adjusts the underlying UTC time range accordingly to ensure that:

• no usage events are omitted
• no usage events are counted twice

This ensures that usage aggregation remains accurate even during timezone offset changes caused by daylight saving time transitions.

Usage data is always returned as an aggregated total for the entire requested period.

Example:

• start=2026-01-01
• end=2026-01-31

returns a single aggregated total for that full period.

The API does not currently support aggregation grouped by:

• day
• week
• month
• custom period intervals

The minimum supported aggregation period is one calendar day. Partial-day aggregation and hourly resolution are not supported.

The API supports querying usage data for up to 5 years in a single request.

Start and end dates cannot reference future dates.

This section describes how organization and sender names are represented in aggregated billing responses.

Usage aggregation is based on organization and sender identifiers rather than organization or sender names. This ensures that historical name changes do not split or duplicate usage totals.

If an organization or sender changes name, the usage data remains associated with the same underlying identifier and continues to be aggregated as a single entity.

Billing reports use sender and organization names as they were recorded when messages were logged.

When usage data is aggregated for a requested period, the response displays the latest sender or organization name that appears within that queried period.

• If a name change occurs outside the requested period, it does not affect the returned result.
• If a name change occurs within the requested period, the newer name is used in the aggregated output, provided messages were sent using that name during the queried period.

If messages were sent under different organization or sender names during the requested period, those names are included in the JSON output as a reference list.

These historical names are provided for transparency and traceability only. Usage totals are still aggregated under a single entity and are not split per historical name.

When a delivery is created, the senderOrganizationId parameter determines which organization is billed for the resulting message usage.

The senderOrganizationId is specified when calling:

• Create delivery via S3 : as a field in the request body
• Create delivery via multipart/form-data : as a query parameter

If senderOrganizationId is omitted, it is automatically resolved from the authenticated user's account.

The billed organization may be different from the sender's own organization as defined in the envelope (sender.organizationId). The senderOrganizationId on the delivery request controls billing, while the sender.organizationId inside each envelope identifies the sender identity used for delivery presentation.

Example:

• Delivery created with senderOrganizationId = 10
• Envelope contains sender.organizationId = 6 and sender.senderId = 3
• Usage is billed to organization 10, even though the sender identity belongs to organization 6

Billing usage data is currently returned in JSON format.

A Platform Holder retrieves usage data for the entire organizational hierarchy for January 2026 in order to prepare monthly invoices for customer organizations.

Example:

• Query target: Platform Holder
• Period: 2026-01-01 to 2026-01-31
• Result:
  • aggregated totals for all its organizations
  • sender-level breakdowns
  • hierarchy totals

A Police Department administrator retrieves usage data for their organization to review monthly communication activity. Police Department has two sub-organizations:

• Traffic Department
• Criminal Investigation Department

The response includes:

• aggregated total for the full organizational hierarchy
• usage for Police Department's own sender entities
• usage for Traffic Department (with sender breakdown)
• usage for Criminal Investigation Department (with sender breakdown)