Tariffs

Base URL: $BUSINESS_API

The object

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
The object
{
  "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"
}

List utility billing tariffs

Logs

GET /tariffs

Returns the tenant's tariff schedules in cursor pages (limit up to 100, 20 by default, after for the next page), including drafts and superseded versions unless filtered. A free-text q parameter narrows the list further. Requires tariffs:read.

Parameters

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

categorystring · query · optional

Returns only tariffs for this customer category: residential, commercial, industrial, institutional or government.

one of residential, commercial, industrial, institutional, government

statusstring · query · optional

Returns only tariffs in this status: draft, active or superseded.

one of draft, active, superseded

Returns

200 Tariffs in the utility tenant

Show attributes
dataarray of UtilityTariff · required
Show child 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
has_moreboolean · required
next_cursorstring · optional

Errors 403

Permissions tariffs:read · Roles: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/tariffs" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "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"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Create a new tariff schedule

Logs

POST /tariffs

Creates the schedule in draft status; it has no effect on billing until it is activated. code and name are required, category defaults to residential, currency defaults to the tenant's currency, and effective_from defaults to now. Tiers, fixed charges and charge components are validated (contiguous tier volumes, positive amounts, no duplicate fixed charge per code and diameter) and a violation returns 400; requires tariffs:write.

Body application/json

codestring · required
namestring · required
categorystring · optional

one of residential, commercial, industrial, institutional, government

currencystring · optional
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

Returns

201 Tariff schedule created

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 · 403

Permissions tariffs:write · Roles: admin, finance, owner

curl -X POST "$BUSINESS_API/tariffs" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "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"
}'
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"
}

Get a utility tariff schedule

Logs

GET /tariffs/{id}

Returns one tariff schedule with its tiers, fixed charges, charge components, taxes and effective dates. Returns 404 when the tariff is not in the caller's tenant; requires tariffs:read.

Parameters

idstring · path · required

ID of the tariff in the caller's tenant.

Returns

200 Tariff in the authenticated tenant

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 403 · 404

Permissions tariffs:read · Roles: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/tariffs/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "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"
}

Activate a tariff schedule

Logs

POST /tariffs/{id}/activate

Sets the tariff to active and bounds the tariff currently in force for the same category: if the new tariff is already effective, the old one is superseded now; if it is future-dated, the old one stays active until the new effective_from. A tariff.activated event is emitted, which also records the tariff's validity in the point-in-time history. The current status is not checked, so activating again re-applies the same changes; requires tariffs:write.

Parameters

idstring · path · required

ID of the tariff in the caller's tenant to activate.

Returns

200 Activated tariff in the authenticated tenant

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 403 · 404

Permissions tariffs:write · Roles: admin, finance, owner

curl -X POST "$BUSINESS_API/tariffs/{id}/activate" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "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"
}

Get the metadata of a tariff

Logs

GET /tariffs/{id}/metadata

Returns the free-form key-value metadata the tenant has stored on the tariff, as an entry with resource_type, resource_id and a metadata map. The tariff must exist in the caller's tenant (404 otherwise); requires business:metadata:read.

Parameters

idstring · path · required

ID of the tariff in the caller's tenant, at most 120 characters.

Returns

200 Metadata

Show attributes
resource_typestring · optional
resource_idstring · optional
metadataobject · optional

Errors 404

Permissions business:metadata:read · Roles: admin, customer_service, owner

curl -X GET "$BUSINESS_API/tariffs/{id}/metadata" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}

Merge metadata

Logs

PUT /tariffs/{id}/metadata

Merge metadata; an empty value deletes the key

Merges the keys in the metadata object into what the tariff already has; keys not sent are kept, and a key sent with an empty string is removed. Keys must be non-blank, at most 40 characters, without square brackets or control characters, values at most 500 characters, and a resource holds at most 50 keys; violations return 400 with one entry per invalid key. Returns the full metadata after the merge; requires business:metadata:write.

Parameters

idstring · path · required

ID of the tariff in the caller's tenant, at most 120 characters.

Body application/json

metadataobject · required

Returns

200 Resulting metadata

Show attributes
resource_typestring · optional
resource_idstring · optional
metadataobject · optional

Errors 400 · 404

Permissions business:metadata:write · Roles: admin, owner

curl -X PUT "$BUSINESS_API/tariffs/{id}/metadata" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "metadata": {
    "key": "value"
  }
}'
Response 200
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}