Tariff templates

Base URL: $BUSINESS_API

The object

country_codestring · required
currencystring · optional
availableboolean · required
reasonstring · optional

one of no_template_for_country, country_unset

templatesarray of object · required
Show child attributes
idstring · required
codestring · required
namestring · required
categorystring · required

one of residential, commercial, industrial, institutional, government

currencystring · required
fixed_fee_centsinteger · required
min_consumption_m3number · required
sanitation_surcharge_percentnumber · required
tax_percentnumber · required
tiersarray of object · required
Show child attributes
min_m3number · optional
max_m3number · optional

0 means no upper bound

rate_per_m3_centsinteger · optional
The object
{
  "country_code": "MZ",
  "currency": "MZN",
  "available": true,
  "reason": "no_template_for_country",
  "templates": [
    {
      "id": "mz.dom",
      "code": "COD-2026-000142",
      "name": "Ana Matsinhe",
      "category": "residential",
      "currency": "MZN",
      "fixed_fee_cents": 125000,
      "min_consumption_m3": 13.42,
      "sanitation_surcharge_percent": 1,
      "tax_percent": 1,
      "tiers": [
        {
          "min_m3": 1,
          "max_m3": 1,
          "rate_per_m3_cents": 1
        }
      ]
    }
  ]
}

Tariff templates for the utility's country

Logs

GET /tariff-templates

The tariffs of the seed dataset for the utility's country, at the dataset's latest prices, as starting points, so a tariff never starts from a blank form and no tariff values live in clients. available is false with reason no_template_for_country or country_unset when there is none. Requires tariffs:read.

Returns

200 The templates

Show attributes
country_codestring · required
currencystring · optional
availableboolean · required
reasonstring · optional

one of no_template_for_country, country_unset

templatesarray of object · required
Show child attributes
idstring · required
codestring · required
namestring · required
categorystring · required

one of residential, commercial, industrial, institutional, government

currencystring · required
fixed_fee_centsinteger · required
min_consumption_m3number · required
sanitation_surcharge_percentnumber · required
tax_percentnumber · required
tiersarray of object · required
Show child attributes
min_m3number · optional
max_m3number · optional

0 means no upper bound

rate_per_m3_centsinteger · optional

Errors 401 · 403

curl -X GET "$BUSINESS_API/tariff-templates" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "country_code": "MZ",
  "currency": "MZN",
  "available": true,
  "reason": "no_template_for_country",
  "templates": [
    {
      "id": "mz.dom",
      "code": "COD-2026-000142",
      "name": "Ana Matsinhe",
      "category": "residential",
      "currency": "MZN",
      "fixed_fee_cents": 125000,
      "min_consumption_m3": 13.42,
      "sanitation_surcharge_percent": 1,
      "tax_percent": 1,
      "tiers": [
        {
          "min_m3": 1,
          "max_m3": 1,
          "rate_per_m3_cents": 1
        }
      ]
    }
  ]
}

Create a tariff from a template

Logs

POST /tariff-templates/{templateID}/apply

Creates the template's tariff through the billing service, optionally with another code or name and an effective date (default now), and activates it when activate is true. A template applied and activated in the real account completes the utility_real tariffs step. Returns the created tariff. Requires tariffs:write.

Parameters

templateIDstring · path · required

Template ID from the list

Body application/json

codestring · optional
namestring · optional
effective_fromstring (date-time) · optional
activateboolean · optional

Returns

201 The created tariff

Show attributes
idstring · required
tenant_idstring · required
codestring · required
namestring · required
categorystring · required

one of residential, commercial, industrial, institutional, government

currencystring · required
minor_unitsinteger · optional
fixed_fee_centsinteger (int64) · optional
min_consumption_m3number · optional
minimum_charge_centsinteger (int64) · optional
sanitation_surcharge_percentnumber · optional
tax_percentnumber · optional
tiersarray of UtilityTariffTier · optional
Show child attributes
tier_numberinteger · optional
min_m3number · optional
max_m3number · optional

Zero means unbounded

rate_per_m3_centsinteger (int64) · optional
volume_start_linteger (int64) · optional
volume_end_linteger (int64) · optional · nullable
fixed_chargesarray of UtilityTariffFixedCharge · optional
Show child attributes
charge_codestring · required
descriptionstring · optional
diameter_mminteger · optional
amount_minorinteger (int64) · required
charge_componentsarray of UtilityTariffChargeComponent · optional
Show child attributes
codestring · required
namestring · required
descriptionstring · optional
labelsobject · optional
kindstring · required

one of fixed, percentage

amount_minorinteger (int64) · optional
rate_basis_pointsinteger (int64) · optional
rate_percentnumber · optional
basisstring · optional

one of service_subtotal

taxableboolean · optional
sort_orderinteger · optional
cadencestring · optional

one of every_bill, every_n_periods, one_time

interval_periodsinteger · optional
anchor_datestring (date-time) · optional · nullable
effective_fromstring (date-time) · optional · nullable
effective_tostring (date-time) · optional · nullable
partial_period_policystring · optional

one of full, prorate, skip

skipped_cycle_policystring · optional

one of skip

activeboolean · optional
diameter_mminteger · optional · nullable
service_area_idstring · optional
payment_termsstring · optional

one of inherit_invoice

accounting_rolestring · optional
effective_fromstring (date-time) · optional
effective_tostring (date-time) · optional · nullable
statusstring · required

one of draft, active, superseded

created_atstring (date-time) · optional
updated_atstring (date-time) · optional

Errors 400 · 401 · 403 · 404 · 409

curl -X POST "$BUSINESS_API/tariff-templates/{templateID}/apply" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "code": "COD-2026-000142",
  "name": "Ana Matsinhe",
  "effective_from": "2026-11-19T09:30:00Z",
  "activate": true
}'
Response 201
{
  "id": "uti_2lVUY3v2KN5iaJpucZDwaxd8of9",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "code": "COD-2026-000142",
  "name": "Ana Matsinhe",
  "category": "residential",
  "currency": "MZN",
  "minor_units": 1,
  "fixed_fee_cents": 125000,
  "min_consumption_m3": 13.42,
  "minimum_charge_cents": 1,
  "sanitation_surcharge_percent": 1,
  "tax_percent": 1,
  "tiers": [
    {
      "tier_number": 1,
      "min_m3": 1,
      "max_m3": 1,
      "rate_per_m3_cents": 1,
      "volume_start_l": 1342,
      "volume_end_l": 1342
    }
  ],
  "fixed_charges": [
    {
      "charge_code": "CHA-2026-000142",
      "description": "Leitura confirmada no local.",
      "diameter_mm": 1,
      "amount_minor": 125000
    }
  ],
  "charge_components": [
    {
      "code": "COD-2026-000142",
      "name": "Ana Matsinhe",
      "description": "Leitura confirmada no local.",
      "labels": {
        "key": "value"
      },
      "kind": "fixed",
      "amount_minor": 125000,
      "rate_basis_points": 1,
      "rate_percent": 1,
      "basis": "service_subtotal",
      "taxable": true,
      "sort_order": 1,
      "cadence": "every_bill",
      "interval_periods": 1,
      "anchor_date": "2026-11-19T09:30:00Z",
      "effective_from": "2026-11-19T09:30:00Z",
      "effective_to": "2026-11-19T09:30:00Z",
      "partial_period_policy": "full",
      "skipped_cycle_policy": "skip",
      "active": true,
      "diameter_mm": 1,
      "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
      "payment_terms": "inherit_invoice",
      "accounting_role": "accounting role"
    }
  ],
  "effective_from": "2026-11-19T09:30:00Z",
  "effective_to": "2026-11-19T09:30:00Z",
  "status": "draft",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}