Skip to main content
The Billing API provides endpoints for retrieving billing data, usage statistics, and managing free SMS fragment limits for services.

​
Base URL

All billing endpoints are prefixed with: 
/service/{service_id}/billing

​
Authentication

All endpoints require admin authentication.

​
Endpoints

​
Get Monthly Usage

Retrieve monthly billing usage data for a service for a specific year. 
GET /service/{service_id}/billing/monthly-usage?year={year}

​
Parameters

​
service_id
uuid
required
The unique identifier of the service
​
year
integer
required
The year for which to retrieve monthly usage (e.g., 2024)

​
Response

Returns an array of monthly usage records (excludes email notifications): 
[
  {
    "month": "January",
    "notification_type": "sms",
    "chargeable_units": 1500,
    "notifications_sent": 1200,
    "rate": 0.0165,
    "postage": null,
    "cost": 24.75,
    "free_allowance_used": 500,
    "charged_units": 1000
  },
  {
    "month": "January",
    "notification_type": "letter",
    "chargeable_units": 300,
    "notifications_sent": 300,
    "rate": 0.45,
    "postage": "second",
    "cost": 135.00,
    "free_allowance_used": 0,
    "charged_units": 300
  }
]

​
Response Fields

  • month - Month name (January, February, etc.)
  • notification_type - Type of notification (sms, letter)
  • chargeable_units - Total number of chargeable units
  • notifications_sent - Total number of notifications sent
  • rate - Rate per unit in GBP
  • postage - Postage class for letters (first, second, europe, rest-of-world) or null for SMS
  • cost - Total cost in GBP
  • free_allowance_used - Number of units from free allowance
  • charged_units - Number of units charged (after free allowance)

​
Error Responses

​
400
error
{
  "result": "error",
  "message": "No valid year provided"
}

​
Get Yearly Usage Summary

Retrieve annual billing usage summary for a service. 
GET /service/{service_id}/billing/yearly-usage-summary?year={year}

​
Parameters

​
service_id
uuid
required
The unique identifier of the service
​
year
integer
required
The year for which to retrieve the annual summary (e.g., 2024)

​
Response

Returns an array of yearly totals by notification type: 
[
  {
    "notification_type": "sms",
    "chargeable_units": 18500,
    "notifications_sent": 15200,
    "rate": 0.0165,
    "cost": 305.25,
    "free_allowance_used": 25000,
    "charged_units": 0
  },
  {
    "notification_type": "letter",
    "chargeable_units": 3600,
    "notifications_sent": 3600,
    "rate": 0.45,
    "cost": 1620.00,
    "free_allowance_used": 0,
    "charged_units": 3600
  },
  {
    "notification_type": "email",
    "chargeable_units": 0,
    "notifications_sent": 125000,
    "rate": 0.0,
    "cost": 0.0,
    "free_allowance_used": 0,
    "charged_units": 0
  }
]

​
Response Fields

  • notification_type - Type of notification (sms, letter, email)
  • chargeable_units - Total chargeable units for the year
  • notifications_sent - Total notifications sent for the year
  • rate - Average rate per unit in GBP
  • cost - Total cost for the year in GBP
  • free_allowance_used - Total free allowance units used
  • charged_units - Total units charged (after free allowance)

​
Error Responses

​
400
error
{
  "result": "error",
  "message": "No valid year provided"
}

​
Get Free SMS Fragment Limit

Retrieve the free SMS fragment limit for a service for a specific financial year. 
GET /service/{service_id}/billing/free-sms-fragment-limit?financial_year_start={year}

​
Parameters

​
service_id
uuid
required
The unique identifier of the service
​
financial_year_start
integer
The start year of the financial year (e.g., 2024). Defaults to current financial year if not provided.

​
Response

{
  "free_sms_fragment_limit": 250000,
  "financial_year_start": 2024,
  "has_custom_allowance": false
}

​
Response Fields

  • free_sms_fragment_limit - The free SMS fragment allowance for the service
  • financial_year_start - The financial year this allowance applies to
  • has_custom_allowance - Whether this is a custom allowance or the default for the organisation type
If no annual billing record exists for the specified year, the system automatically creates one with the default allowance based on the service’s organisation type.

​
Error Responses

​
400
error
Invalid financial year format

​
Update Free SMS Fragment Limit

Create or update the free SMS fragment limit for a service. 
POST /service/{service_id}/billing/free-sms-fragment-limit

​
Parameters

​
service_id
uuid
required
The unique identifier of the service

​
Request Body

{
  "free_sms_fragment_limit": 500000
}
​
free_sms_fragment_limit
integer
required
The new free SMS fragment limit (must be >= 0)

​
Response

{
  "free_sms_fragment_limit": 500000
}
This endpoint updates the free allowance for the current financial year. If the new allowance matches the default for the organisation type, has_custom_allowance is set to false. Otherwise, it’s set to true.

​
Error Responses

​
400
error
Invalid request body or free_sms_fragment_limit value

​
Data Models

​
Billing Record

Each billing record represents usage for a specific notification type and period:
  • SMS: Charged per fragment after free allowance is exhausted
  • Letters: Charged per sheet based on postage class and sheet count
  • Email: Free, not charged

​
Financial Year

GOV.UK Notify uses the UK government financial year:
  • Starts: April 1st
  • Ends: March 31st
  • Referenced by the start year (e.g., FY 2024 = April 1, 2024 - March 31, 2025)

​
Free Allowance

Services receive a free SMS fragment allowance based on their organisation type. This allowance:
  • Resets each financial year
  • Can be customized per service
  • Is tracked separately from chargeable usage

Build docs developers (and LLMs) love

Get started for freeTalk to us