Subscription

Base URL: $BUSINESS_API

The object

plan_codestring · required
active_connectionsinteger · required

Connections in status active

max_connectionsinteger · required

Plan limit; 0 means none

usersinteger · required

Active team members

max_usersinteger · required

Plan limit; 0 means none

Get utility subscription

Logs

GET /subscription

Get utility's active platform SaaS subscription and entitlements

Returns the tenant's platform subscription: its plan ID, status (for example trialing, active, past_due, suspended or cancelled), current billing period, trial end, and whether it is set to cancel at the period end. Plan limits are not embedded; read them from the plan the plan_id points to. Returns 404 when the tenant has no subscription; requires business:subscription:read.

Returns

200 Active subscription and entitlement limits

Errors 403 · 404

Permissions business:subscription:read · Roles: admin, analyst, finance, owner, viewer

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

Active subscription and entitlement limits

Request cancellation of utility platform SaaS subscription

Logs

POST /subscription/cancel

With at_period_end set to true the subscription keeps running and is only flagged to cancel when the current period ends; with it false or omitted the subscription is cancelled at once. The body is optional and returns the updated subscription. The call does not check the current status, so repeating it is harmless; requires business:subscription:cancel.

Returns

200 Cancellation recorded

Errors 403 · 404

Permissions business:subscription:cancel · Roles: admin, owner

curl -X POST "$BUSINESS_API/subscription/cancel" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Cancellation recorded

Get utility usage against the plan's limits

Logs

GET /subscription/usage

Returns the tenant's plan code, its active connections and users, and the plan's limits on both. Active connections are those in status active, the same count billing and the connection limit use; a limit of 0 means none. Returns 404 when the tenant has no subscription. Requires business:subscription:read.

Returns

200 Usage against the plan

Show attributes
plan_codestring · required
active_connectionsinteger · required

Connections in status active

max_connectionsinteger · required

Plan limit; 0 means none

usersinteger · required

Active team members

max_usersinteger · required

Plan limit; 0 means none

Errors 404

Permissions business:subscription:read · Roles: admin, analyst, finance, owner, viewer

curl -X GET "$BUSINESS_API/subscription/usage" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "plan_code": "C100",
  "active_connections": 87,
  "max_connections": 100,
  "users": 3,
  "max_users": 0
}

Get utility platform credit balance and grants

Logs

GET /subscription/credits

Returns every platform credit grant the tenant has received, together with balances in minor units. Only active, unexpired grants with something left count toward the balances, which are split into cash-funded and granted (promotional) credit plus their total. Requires business:billing:read.

Returns

200 Platform credit summary

Permissions business:billing:read · Roles: admin, finance, owner

curl -X GET "$BUSINESS_API/subscription/credits" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Platform credit summary

Redeem a platform promotional code

Logs

POST /subscription/credits/redeem

Looks up the campaign behind the code and creates a promotional credit grant for the tenant for the campaign's amount, expiring after the campaign's grant period when it sets one. The new credit is applied right away to the tenant's open platform invoices, and the grant is returned with 201. Returns 404 for an unknown code, 409 when the campaign is not active, its budget or redemption cap is used up, or the tenant has reached its per-tenant limit, and 400 when code is empty; requires business:billing:write.

Returns

201 Platform credit granted

Permissions business:billing:write · Roles: admin, finance, owner

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

Platform credit granted

List the utility's platform invoices

Logs

GET /subscription/invoices

Returns the invoices the platform has issued to the caller's tenant for its subscription, in cursor pages (limit up to 100, 20 by default, with after for the next page). Requires business:subscription:read.

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

Returns only invoices in this status: open, paid or void; omit it for all invoices.

one of open, paid, void

Returns

200 Invoices

Show attributes
dataarray of PlatformInvoice · optional
Show child attributes
payment_methodsarray of string · optional

The payment methods the platform accepts for this invoice; recording or proving a payment by any other is refused with payment.method_not_configured.

idstring · optional
tenant_idstring · optional
organization_idstring · optional
subscription_idstring · optional
numberstring · optional
plan_idstring · optional
period_startstring (date-time) · optional
period_endstring (date-time) · optional
linesarray of PlatformInvoiceLine · optional
Show child attributes
codestring · optional

Stable line code: plan, account_plan, overage_connections, overage_users, proration. Clients word it with params and fall back to description.

descriptionstring · optional
paramsobject · optional

Values the code's wording fills in: plan; plan, account, pro_rata; over, included (account, pro_rata); from, to.

tenant_idstring · optional

Account covered by this line

plan_idstring · optional

Plan applied to this account

quantitynumber · optional
unit_price_centsinteger · optional
amount_centsinteger · optional
total_centsinteger · optional
balance_centsinteger · optional
currencystring · optional
statusstring · optional

one of open, paid, void

issued_atstring (date-time) · optional
due_atstring (date-time) · optional
paid_atstring (date-time) · optional
has_moreboolean · optional
next_cursorstring · optional

Errors 403

Permissions business:subscription:read · Roles: admin, analyst, finance, owner, viewer

curl -X GET "$BUSINESS_API/subscription/invoices" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "payment_methods": [
        "payment method"
      ],
      "id": "pla_2FBOA71OWNnW0zzkW3NgMb7QEdr",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "organization_id": "org_2ZNeUPlw01Za6RbKMZDGGbR4cV5",
      "subscription_id": "sub_2vVmyFDcAD9ag9fGg1XkQfxiYTR",
      "number": "NUM-2026-000142",
      "plan_id": "pla_2lVU4nTwUfHw6nxUwjbOeRn8u5D",
      "period_start": "2026-11-19T09:30:00Z",
      "period_end": "2026-11-19T09:30:00Z",
      "lines": [
        {
          "code": "COD-2026-000142",
          "description": "Leitura confirmada no local.",
          "params": {
            "key": "value"
          },
          "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
          "plan_id": "pla_2lVU4nTwUfHw6nxUwjbOeRn8u5D",
          "quantity": 1,
          "unit_price_cents": 125000,
          "amount_cents": 125000
        }
      ],
      "total_cents": 125000,
      "balance_cents": 125000,
      "currency": "MZN",
      "status": "open",
      "issued_at": "2026-11-19T09:30:00Z",
      "due_at": "2026-11-19T09:30:00Z",
      "paid_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor"
}

Read one platform invoice of the utility

Logs

GET /subscription/invoices/{id}

Returns one platform invoice with its lines, totals and status. An invoice that belongs to another tenant answers 404 just like a missing one; requires business:subscription:read.

Parameters

idstring · path · required

ID of the platform invoice issued to the caller's tenant.

Returns

200 Invoice

Show attributes
payment_methodsarray of string · optional

The payment methods the platform accepts for this invoice; recording or proving a payment by any other is refused with payment.method_not_configured.

idstring · optional
tenant_idstring · optional
organization_idstring · optional
subscription_idstring · optional
numberstring · optional
plan_idstring · optional
period_startstring (date-time) · optional
period_endstring (date-time) · optional
linesarray of PlatformInvoiceLine · optional
Show child attributes
codestring · optional

Stable line code: plan, account_plan, overage_connections, overage_users, proration. Clients word it with params and fall back to description.

descriptionstring · optional
paramsobject · optional

Values the code's wording fills in: plan; plan, account, pro_rata; over, included (account, pro_rata); from, to.

tenant_idstring · optional

Account covered by this line

plan_idstring · optional

Plan applied to this account

quantitynumber · optional
unit_price_centsinteger · optional
amount_centsinteger · optional
total_centsinteger · optional
balance_centsinteger · optional
currencystring · optional
statusstring · optional

one of open, paid, void

issued_atstring (date-time) · optional
due_atstring (date-time) · optional
paid_atstring (date-time) · optional

Errors 403 · 404

Permissions business:subscription:read · Roles: admin, analyst, finance, owner, viewer

curl -X GET "$BUSINESS_API/subscription/invoices/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "payment_methods": [
    "payment method"
  ],
  "id": "pla_2FBOA71OWNnW0zzkW3NgMb7QEdr",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "organization_id": "org_2ZNeUPlw01Za6RbKMZDGGbR4cV5",
  "subscription_id": "sub_2vVmyFDcAD9ag9fGg1XkQfxiYTR",
  "number": "NUM-2026-000142",
  "plan_id": "pla_2lVU4nTwUfHw6nxUwjbOeRn8u5D",
  "period_start": "2026-11-19T09:30:00Z",
  "period_end": "2026-11-19T09:30:00Z",
  "lines": [
    {
      "code": "COD-2026-000142",
      "description": "Leitura confirmada no local.",
      "params": {
        "key": "value"
      },
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "plan_id": "pla_2lVU4nTwUfHw6nxUwjbOeRn8u5D",
      "quantity": 1,
      "unit_price_cents": 125000,
      "amount_cents": 125000
    }
  ],
  "total_cents": 125000,
  "balance_cents": 125000,
  "currency": "MZN",
  "status": "open",
  "issued_at": "2026-11-19T09:30:00Z",
  "due_at": "2026-11-19T09:30:00Z",
  "paid_at": "2026-11-19T09:30:00Z"
}

Change subscription plan

Logs

POST /subscription/change-plan

Change plan now, prorating the difference onto the next invoice

Moves the tenant to plan_id immediately and, when the plans differ in price, adds a proration line for the unused part of the current period to the next platform invoice (a credit when moving to a cheaper plan). Trialing subscriptions, or calls after the period has ended, get no proration. Returns 409 when the subscription is cancelled or already on that plan, and 400 when plan_id is missing or the plans use different currencies; requires business:subscription:change.

Body application/json

plan_idstring · required

Returns

200 Result with proration_cents (positive charges, negative credits)

Show attributes
subscriptionobject · optional
from_plan_idstring · optional
to_plan_idstring · optional
proration_centsinteger · optional

Errors 400 · 403 · 404 · 409

Permissions business:subscription:change · Roles: admin, owner

curl -X POST "$BUSINESS_API/subscription/change-plan" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "plan_id": "pla_2lVU4nTwUfHw6nxUwjbOeRn8u5D"
}'
Response 200
{
  "subscription": {},
  "from_plan_id": "fro_2oCrPw0hXcafj8kPpsolZgmxtIE",
  "to_plan_id": "top_2Dj6KFZoEjTcgDPWWbViOp9uE1H",
  "proration_cents": 1
}

Compute the proration of a plan change without making it

Logs

POST /subscription/change-plan/preview

Runs the same checks and proration calculation as a plan change and returns the from and to plan IDs, the proration amount in cents, the currency and the current period end, without changing the subscription or adding any invoice line. It fails the same way as the real change: 409 for a cancelled subscription or the current plan, 400 for a missing plan_id or a currency mismatch. Requires business:subscription:change.

Body application/json

plan_idstring · required

Returns

200 Preview with proration_cents (positive charges, negative credits)

Show attributes
from_plan_idstring · optional
to_plan_idstring · optional
proration_centsinteger · optional

Positive charges and negative credits on the next invoice

currencystring · optional
current_period_endstring (date-time) · optional

Errors 400 · 403 · 404 · 409

Permissions business:subscription:change · Roles: admin, owner

curl -X POST "$BUSINESS_API/subscription/change-plan/preview" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "plan_id": "pla_2lVU4nTwUfHw6nxUwjbOeRn8u5D"
}'
Response 200
{
  "from_plan_id": "fro_2oCrPw0hXcafj8kPpsolZgmxtIE",
  "to_plan_id": "top_2Dj6KFZoEjTcgDPWWbViOp9uE1H",
  "proration_cents": 1,
  "currency": "MZN",
  "current_period_end": "2026-11-19T09:30:00Z"
}

How to pay platform subscription invoices

Logs

GET /subscription/payment-instructions

How to pay platform subscription invoices: bank accounts and mobile-money codes

Returns, in a data array, the payment instructions configured by the platform operator (for example account numbers or payment codes) that a tenant uses to pay its platform invoices. The list is empty when none are configured. Requires business:subscription:read.

Returns

200 OK

Errors 403

Permissions business:subscription:read · Roles: admin, analyst, finance, owner, viewer

curl -X GET "$BUSINESS_API/subscription/payment-instructions" \
  -H "Authorization: Bearer sk_test_..."
Response 200

OK

Send a proof of paying a platform subscription invoice

Logs

POST /subscription/invoices/{id}/payment-proofs

Send a proof of paying a platform subscription invoice (multipart: amount_cents, method, reference, paid_on, note, file)

Accepts a multipart form with the payment details and a file (PDF, JPEG or PNG) and stores a pending proof for the platform's billing staff to review. The invoice must belong to the tenant and be open (409 otherwise); amount_cents must be positive, method must be one of the payment methods enabled on the installation, reference is required (up to 128 characters), paid_on is a YYYY-MM-DD date not in the future, and note is limited to 500 characters. A second open proof with the same method and reference is rejected with 409; callers need business:subscription:change or payments:write.

Returns

201 Created; the proof waits for platform review

Errors 409

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

curl -X POST "$BUSINESS_API/subscription/invoices/{id}/payment-proofs" \
  -H "Authorization: Bearer sk_test_..."
Response 201

Created; the proof waits for platform review

List the utility's proofs of payment to the platform

Logs

GET /subscription/payment-proofs

Returns the proofs of payment the caller's tenant has sent for its platform invoices, with their review status, in cursor pages (limit up to 100, 20 by default, after for the next page). Requires business:subscription:read.

Parameters

invoice_idstring · query · optional

Returns only proofs sent for this platform invoice ID.

statusstring · query · optional

Returns only proofs in this review status: pending, approved or rejected.

one of pending, approved, rejected

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 OK

Permissions business:subscription:read · Roles: admin, analyst, finance, owner, viewer

curl -X GET "$BUSINESS_API/subscription/payment-proofs" \
  -H "Authorization: Bearer sk_test_..."
Response 200

OK

Download one of the utility's proofs

Logs

GET /subscription/payment-proofs/{id}/file

Streams the file attached to a proof with its stored content type and an inline Content-Disposition carrying the original file name. Returns 404 when the proof belongs to another tenant or its file is no longer in storage; requires business:subscription:read.

Returns

200 The stored PDF, JPEG or PNG

Permissions business:subscription:read · Roles: admin, analyst, finance, owner, viewer

curl -X GET "$BUSINESS_API/subscription/payment-proofs/{id}/file" \
  -H "Authorization: Bearer sk_test_..."
Response 200

The stored PDF, JPEG or PNG