Credit grants

Base URL: $BUSINESS_API

The object

idstring · required
tenant_idstring · required
account_idstring · required
campaign_idstring · optional
fundingstring · required

one of cash, granted

sourcestring · required
amount_minorinteger (int64) · required
remaining_minorinteger (int64) · required
currencystring · required
applies_toarray of string · optional
charge_kindsarray of string · optional
expires_atstring (date-time) · optional
statusstring · required

one of pending_approval, active, exhausted, expired, rejected

proposed_bystring · optional
approved_bystring · optional
rejection_reasonstring · optional
reasonstring · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required
The object
{
  "id": "cre_2cmf76oNbMmjnic9ZsClLOiDDwu",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "campaign_id": "cam_2WQBFWMJR6y3LeY1tCERReuZREk",
  "funding": "cash",
  "source": "source",
  "amount_minor": 125000,
  "remaining_minor": 1,
  "currency": "MZN",
  "applies_to": [
    "2026-11-19"
  ],
  "charge_kinds": [
    "charge kind"
  ],
  "expires_at": "2026-11-19T09:30:00Z",
  "status": "pending_approval",
  "proposed_by": "proposed by",
  "approved_by": "approved by",
  "rejection_reason": "rejection reason",
  "reason": "Leitura confirmada no local.",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}

List credit grants

Logs

GET /credit-grants

List the utility's credit grants, such as those waiting for approval

Requires invoices:read. Newest first, one cursor page at a time.

Parameters

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

statusstring · query · optional

Return only grants in this status: pending_approval, active, exhausted, expired or rejected; any other value returns 400.

one of pending_approval, active, exhausted, expired, rejected

account_idstring · query · optional

Return only grants made to this account ID.

Returns

200 Grant page

Show attributes
dataarray of CreditGrant · required
Show child attributes
idstring · required
tenant_idstring · required
account_idstring · required
campaign_idstring · optional
fundingstring · required

one of cash, granted

sourcestring · required
amount_minorinteger (int64) · required
remaining_minorinteger (int64) · required
currencystring · required
applies_toarray of string · optional
charge_kindsarray of string · optional
expires_atstring (date-time) · optional
statusstring · required

one of pending_approval, active, exhausted, expired, rejected

proposed_bystring · optional
approved_bystring · optional
rejection_reasonstring · optional
reasonstring · optional
created_atstring (date-time) · required
updated_atstring (date-time) · required
has_moreboolean · required
next_cursorstring · optional

Errors 400

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

curl -X GET "$BUSINESS_API/credit-grants" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "cre_2cmf76oNbMmjnic9ZsClLOiDDwu",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
      "campaign_id": "cam_2WQBFWMJR6y3LeY1tCERReuZREk",
      "funding": "cash",
      "source": "source",
      "amount_minor": 125000,
      "remaining_minor": 1,
      "currency": "MZN",
      "applies_to": [
        "2026-11-19"
      ],
      "charge_kinds": [
        "charge kind"
      ],
      "expires_at": "2026-11-19T09:30:00Z",
      "status": "pending_approval",
      "proposed_by": "proposed by",
      "approved_by": "approved by",
      "rejection_reason": "rejection reason",
      "reason": "Leitura confirmada no local.",
      "created_at": "2026-11-19T09:30:00Z",
      "updated_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Grant promotional or manual account credit

Logs

POST /credit-grants

Creates a credit for one account; account_id and a positive amount_minor are required. Unless requires_approval is true the grant is active immediately: a grant transaction is recorded and the credit is applied to the account's open invoices, and the response shows the remaining amount after that. With requires_approval true the grant is stored as pending_approval and a different user must approve it. Optional fields default to funding granted, source promotion, applies_to water_invoice and charge_kinds water and sanitation; requires invoices:write.

Returns

201 Credit grant created

Permissions invoices:write · Roles: admin, billing_clerk, finance, owner

curl -X POST "$BUSINESS_API/credit-grants" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{}'
Response 201

Credit grant created

Approve a pending credit grant

Logs

POST /credit-grants/{id}/approve

Approve a pending credit grant (maker-checker)

Activates a grant that is pending approval, records the grant transaction and applies the credit to the account's open invoices, then returns the updated grant. The user who proposed the grant cannot approve it. Requires invoices:write; a grant that is not pending approval, or approval by its proposer, returns 400, and an unknown grant returns 404.

Parameters

idstring · path · required

Identifier of the credit grant to approve; it must be in the pending_approval status.

Returns

200 Credit grant approved

Permissions invoices:write · Roles: admin, billing_clerk, finance, owner

curl -X POST "$BUSINESS_API/credit-grants/{id}/approve" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Credit grant approved

Reject a pending credit grant

Logs

POST /credit-grants/{id}/reject

Marks a pending grant as rejected, stores the rejection reason and sets its remaining amount to zero, so no credit is ever applied. A non-empty reason is required. Requires invoices:write; a missing reason or a grant that is not pending approval returns 400, and an unknown grant returns 404.

Parameters

idstring · path · required

Identifier of the credit grant to reject; it must be in the pending_approval status.

Body application/json

reasonstring · optional

Returns

200 Credit grant rejected

Permissions invoices:write · Roles: admin, billing_clerk, finance, owner

curl -X POST "$BUSINESS_API/credit-grants/{id}/reject" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Leitura confirmada no local."
}'
Response 200

Credit grant rejected

Bulk grant promotional credits to multiple accounts

Logs

POST /credit-grants/bulk

Creates one active granted credit per account in account_ids, each for the same amount_minor, and applies each to that account's open invoices. The response reports how many grants were created and lists them. Grants are created one at a time without a transaction, so if one account fails the request returns the error and the grants already created remain. Requires invoices:write; an empty account_ids or a non-positive amount returns 400.

Returns

201 Bulk credit grants created

Permissions invoices:write · Roles: admin, billing_clerk, finance, owner

curl -X POST "$BUSINESS_API/credit-grants/bulk" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{}'
Response 201

Bulk credit grants created

Get unapplied granted-credit liability and campaign summary

Logs

GET /credit-grants/liability

Summarizes the tenant's outstanding granted credit: the unapplied remaining amount of active, unexpired granted-funding grants, how many such grants exist, and how much of that amount expires within the next 30 days. The response also lists the tenant's credit campaigns. Requires invoices:read.

Returns

200 Credit liability report

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

curl -X GET "$BUSINESS_API/credit-grants/liability" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Credit liability report