Organizations: Actions

Base URL: $BUSINESS_API

Request organization account removal

Logs

DELETE /organizations/{organizationID}/accounts/{tenantID}

Schedule removal of an account after the configured notice period

Moves an active link to removal_pending and sets notice_period_until to now plus the deployment's configured notice period. Access ends when a scheduled sweep runs after that date, and the account keeps its data and ownership. Either an organization owner with organization:accounts:manage or an owner of the account itself may call it. If the organization pays for the account, direct billing is scheduled for the deadline and the account's owners are notified. Returns 202 with the updated link, 404 when there is no active link between the two, and 400 when the link is not active.

Parameters

organizationIDstring · path · required

ID of the organization the account is linked to.

tenantIDstring · path · required

ID of the linked account (utility workspace) to remove from the organization.

Returns

202 Account link removal scheduled; account ownership and data are retained

Show attributes
idstring · required
organization_idstring · required
tenant_idstring · required
tenant_namestring · optional
tenant_slugstring · optional
statestring · required

one of pending_consent, active, removal_pending, removed, owned

consent_approved_bystring · required
consent_approved_atstring (date-time) · optional
added_bystring · required
notice_period_untilstring (date-time) · optional
grantsobject · required

Errors 403 · 404

Permissions business:organization:read, organization:accounts:manage

curl -X DELETE "$BUSINESS_API/organizations/{organizationID}/accounts/{tenantID}" \
  -H "Authorization: Bearer sk_test_..."
Response 202
{
  "id": "org_2BfeY3PegjBaQbr8EdxWUjNy4BN",
  "organization_id": "org_2ZNeUPlw01Za6RbKMZDGGbR4cV5",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "tenant_name": "Ana Matsinhe",
  "tenant_slug": "tenant slug",
  "state": "pending_consent",
  "consent_approved_by": "consent approved by",
  "consent_approved_at": "2026-11-19T09:30:00Z",
  "added_by": "added by",
  "notice_period_until": "2026-11-19T09:30:00Z",
  "grants": {
    "key": [
      "value"
    ]
  }
}

Get organization portfolio

Logs

GET /organizations/{organizationID}/portfolio

Read aggregate account lifecycle counts permitted by organization grants

Returns only aggregate counts: the total number of accounts, plus counts by account status and by workspace state. No account details are included. Owners see the accounts the organization owns. For linked accounts in the active or removal_pending state, a caller's role is counted only when the account owner granted that role portfolio:read. Requires the organization:portfolio:read scope, and a closed organization returns 404.

Parameters

organizationIDstring · path · required

ID of the organization whose portfolio is summarised; it must equal the caller's active organization context.

Returns

200 Aggregate counts only; linked accounts require explicit portfolio:read consent

Show attributes
organization_idstring · required
account_countinteger · required
by_statusobject · required

Errors 403 · 404

Permissions organization:portfolio:read · Roles: account_analyst, account_owner

curl -X GET "$BUSINESS_API/organizations/{organizationID}/portfolio" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "organization_id": "org_2ZNeUPlw01Za6RbKMZDGGbR4cV5",
  "account_count": 1,
  "by_status": {
    "key": 1342
  }
}

List organization setting templates

Logs

GET /organizations/{organizationID}/templates

Returns the organization's setting templates, both draft and published, without pagination. Every caller needs the organization:accounts:read scope in the matching organization context. Listing drafts also requires an owner or admin with organization:accounts:manage, so other members must pass published_only=true. A closed organization returns 404.

Parameters

organizationIDstring · path · required

ID of the organization whose templates are listed; it must equal the caller's active organization context.

published_onlyboolean · query · optional · default false

Set to true to return only published templates; any other value or no value includes drafts, which only owners and admins may see.

Returns

200 Organization templates visible in the active organization context

Show attributes
keystring · required
versionstring · required
namestring · required
descriptionstring · optional
settingsobject · required

Portable setting snapshots. Implemented kinds are tariffs, billing_schedules, automation_rules, notification_templates, and connector_definitions. Secret references, health state, customer data, and other tenant records are rejected or omitted; connectors are created disabled and schedules remain paused.

idstring · required
organization_idstring · required
statestring · required

one of draft, published

created_bystring · required
published_bystring · optional
published_atstring (date-time) · optional
created_atstring (date-time) · required

Errors 403

Permissions organization:accounts:manage, organization:accounts:read · Roles: account_admin, account_owner

curl -X GET "$BUSINESS_API/organizations/{organizationID}/templates" \
  -H "Authorization: Bearer sk_test_..."
Response 200
[
  {
    "key": "key",
    "version": "version",
    "name": "Ana Matsinhe",
    "description": "Leitura confirmada no local.",
    "settings": {},
    "id": "org_2sCTxsOpzeEdvmgLlwMjjwUVH08",
    "organization_id": "org_2ZNeUPlw01Za6RbKMZDGGbR4cV5",
    "state": "draft",
    "created_by": "created by",
    "published_by": "published by",
    "published_at": "2026-11-19T09:30:00Z",
    "created_at": "2026-11-19T09:30:00Z"
  }
]

Create an unpublished organization setting template draft

Logs

POST /organizations/{organizationID}/templates

Saves a new template in the draft state with a generated ID and returns it with 201. The body needs a key, version (up to 40 characters), name (up to 160 characters), an optional description (up to 1000 characters) and a non-empty settings map. Allowed settings keys are tariffs, billing_schedules, notification_templates, automation_rules, connector_definitions, roles, custom_fields, document_layouts, branding and domains. Each value must be valid JSON up to 256 KB and must not contain secrets; otherwise the call returns 400. Requires an owner or admin with organization:accounts:manage, and the organization must be active.

Parameters

organizationIDstring · path · required

ID of the organization that will own the template; it must equal the caller's active organization context.

Body application/json

keystring · required
versionstring · required
namestring · required
descriptionstring · optional
settingsobject · required

Portable setting snapshots. Implemented kinds are tariffs, billing_schedules, automation_rules, notification_templates, and connector_definitions. Secret references, health state, customer data, and other tenant records are rejected or omitted; connectors are created disabled and schedules remain paused.

Returns

201 Draft created

Show attributes
keystring · required
versionstring · required
namestring · required
descriptionstring · optional
settingsobject · required

Portable setting snapshots. Implemented kinds are tariffs, billing_schedules, automation_rules, notification_templates, and connector_definitions. Secret references, health state, customer data, and other tenant records are rejected or omitted; connectors are created disabled and schedules remain paused.

idstring · required
organization_idstring · required
statestring · required

one of draft, published

created_bystring · required
published_bystring · optional
published_atstring (date-time) · optional
created_atstring (date-time) · required

Errors 400 · 403

Permissions organization:accounts:manage · Roles: account_admin, account_owner

curl -X POST "$BUSINESS_API/organizations/{organizationID}/templates" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "key": "key",
  "version": "version",
  "name": "Ana Matsinhe",
  "description": "Leitura confirmada no local.",
  "settings": {}
}'
Response 201
{
  "key": "key",
  "version": "version",
  "name": "Ana Matsinhe",
  "description": "Leitura confirmada no local.",
  "settings": {},
  "id": "org_2sCTxsOpzeEdvmgLlwMjjwUVH08",
  "organization_id": "org_2ZNeUPlw01Za6RbKMZDGGbR4cV5",
  "state": "draft",
  "created_by": "created by",
  "published_by": "published by",
  "published_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z"
}

Publish an immutable organization template version

Logs

POST /organizations/{organizationID}/templates/{templateID}/publish

Checks a draft template against the settings it would apply, then marks it published with the publisher and time, records an audit entry and returns it. Published templates can be offered to member accounts. Only an organization owner with organization:accounts:manage may publish. A template that is not a draft returns 409, and an unknown template or closed organization returns 404.

Parameters

organizationIDstring · path · required

ID of the organization that owns the template; it must equal the caller's active organization context.

templateIDstring · path · required

ID of the draft template to publish.

Returns

200 Published version

Show attributes
keystring · required
versionstring · required
namestring · required
descriptionstring · optional
settingsobject · required

Portable setting snapshots. Implemented kinds are tariffs, billing_schedules, automation_rules, notification_templates, and connector_definitions. Secret references, health state, customer data, and other tenant records are rejected or omitted; connectors are created disabled and schedules remain paused.

idstring · required
organization_idstring · required
statestring · required

one of draft, published

created_bystring · required
published_bystring · optional
published_atstring (date-time) · optional
created_atstring (date-time) · required

Errors 403 · 409

Permissions organization:accounts:manage · Roles: account_admin, account_owner

curl -X POST "$BUSINESS_API/organizations/{organizationID}/templates/{templateID}/publish" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "key": "key",
  "version": "version",
  "name": "Ana Matsinhe",
  "description": "Leitura confirmada no local.",
  "settings": {},
  "id": "org_2sCTxsOpzeEdvmgLlwMjjwUVH08",
  "organization_id": "org_2ZNeUPlw01Za6RbKMZDGGbR4cV5",
  "state": "draft",
  "created_by": "created by",
  "published_by": "published by",
  "published_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z"
}

Ask a member account owner to accept a template

Logs

POST /organizations/{organizationID}/templates/{templateID}/adoptions

Creates a pending adoption of the template's current version for the account named by tenant_id in the body and returns it with 202. An owner of that account must then accept it. The template must be published, and a draft returns 409. Requires an owner or admin with organization:accounts:manage in the matching organization context, and an audit entry is recorded.

Parameters

organizationIDstring · path · required

ID of the organization that owns the template; it must equal the caller's active organization context.

templateIDstring · path · required

ID of the published organization template to offer.

Body application/json

tenant_idstring · required

Returns

202 Adoption awaits explicit account-owner acceptance

Show attributes
idstring · required
template_idstring · required
organization_idstring · required
tenant_idstring · required
versionstring · required
statestring · required

one of pending_acceptance, active, detached

accepted_bystring · optional
accepted_atstring (date-time) · optional
applied_atstring (date-time) · optional
detached_atstring (date-time) · optional
created_atstring (date-time) · required

Errors 403 · 404

Permissions organization:accounts:manage · Roles: account_admin, account_owner

curl -X POST "$BUSINESS_API/organizations/{organizationID}/templates/{templateID}/adoptions" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6"
}'
Response 202
{
  "id": "org_27V0IXXc4PdUU9dGwVzoc5xWqTd",
  "template_id": "tem_2wwLTWQZrCq3poE3JiMXbI6xTEk",
  "organization_id": "org_2ZNeUPlw01Za6RbKMZDGGbR4cV5",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "version": "version",
  "state": "pending_acceptance",
  "accepted_by": "accepted by",
  "accepted_at": "2026-11-19T09:30:00Z",
  "applied_at": "2026-11-19T09:30:00Z",
  "detached_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z"
}

Set organization billing mode

Logs

PUT /organizations/{organizationID}/billing

Choose account-level or organization-level subscription ownership

Only an organization owner can change billing mode. The change is audited.

Parameters

organizationIDstring · path · required

ID of the organization whose billing mode is changed; it must equal the caller's active organization context.

Body application/json

billing_modestring · required

one of account, organization

Returns

200 Updated organization profile

Show attributes
idstring · required
namestring · required
typestring · required

one of utility, authority, operator, regulator, partner, group

statusstring · required
utility_kindstring · optional

one of authority, municipal, regional, national, rural, private, industrial

billing_modestring · required

one of account, organization

Errors 400 · 403

Permissions organization:billing:manage · Roles: account_owner

curl -X PUT "$BUSINESS_API/organizations/{organizationID}/billing" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "billing_mode": "account"
}'
Response 200
{
  "id": "org_2ZNeUPlw01Za6RbKMZDGGbR4cV5",
  "name": "Ana Matsinhe",
  "type": "utility",
  "status": "active",
  "utility_kind": "authority",
  "billing_mode": "account"
}

Read the organization-owned SaaS subscription

Logs

GET /organizations/{organizationID}/subscription

Returns the organization's own subscription: plan, status (for example trialing or active), current period and trial end. Requires the organization:billing:read scope in the matching organization context. Returns 404 when the organization has no subscription.

Parameters

organizationIDstring · path · required

ID of the organization; it must equal the caller's active organization context.

Returns

200 Organization subscription and billing period

Show attributes
idstring · required
organization_idstring · required
plan_idstring · required
statusstring · required

one of trialing, active, past_due, suspended, cancelled

current_period_startstring (date-time) · required
current_period_endstring (date-time) · required
cancel_at_period_endboolean · required
trial_ends_atstring (date-time) · optional
past_due_sincestring (date-time) · optional
suspended_atstring (date-time) · optional
created_atstring (date-time) · optional
updated_atstring (date-time) · optional
by_workspace_stateobject · optional

Errors 403 · 404

Permissions organization:billing:read · Roles: account_finance, account_owner

curl -X GET "$BUSINESS_API/organizations/{organizationID}/subscription" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "org_2TJGGLnwsdLEujr8YxdEEn36uJN",
  "organization_id": "org_2ZNeUPlw01Za6RbKMZDGGbR4cV5",
  "plan_id": "pla_2lVU4nTwUfHw6nxUwjbOeRn8u5D",
  "status": "trialing",
  "current_period_start": "2026-11-19T09:30:00Z",
  "current_period_end": "2026-11-19T09:30:00Z",
  "cancel_at_period_end": true,
  "trial_ends_at": "2026-11-19T09:30:00Z",
  "past_due_since": "2026-11-19T09:30:00Z",
  "suspended_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z",
  "by_workspace_state": {
    "key": 1342
  }
}

Attach a platform plan to an organization

Logs

POST /organizations/{organizationID}/subscription

Requires organization billing mode and the organization owner; the subscription covers administered member accounts.

Parameters

organizationIDstring · path · required

ID of the organization to subscribe; it must equal the caller's active organization context, and the caller must be an owner with organization:billing:manage.

Body application/json

plan_idstring · required

Returns

201 Organization subscription created

Show attributes
idstring · required
organization_idstring · required
plan_idstring · required
statusstring · required

one of trialing, active, past_due, suspended, cancelled

current_period_startstring (date-time) · required
current_period_endstring (date-time) · required
cancel_at_period_endboolean · required
trial_ends_atstring (date-time) · optional
past_due_sincestring (date-time) · optional
suspended_atstring (date-time) · optional
created_atstring (date-time) · optional
updated_atstring (date-time) · optional
by_workspace_stateobject · optional

Errors 403 · 409

Permissions organization:billing:manage · Roles: account_owner

curl -X POST "$BUSINESS_API/organizations/{organizationID}/subscription" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "plan_id": "pla_2lVU4nTwUfHw6nxUwjbOeRn8u5D"
}'
Response 201
{
  "id": "org_2TJGGLnwsdLEujr8YxdEEn36uJN",
  "organization_id": "org_2ZNeUPlw01Za6RbKMZDGGbR4cV5",
  "plan_id": "pla_2lVU4nTwUfHw6nxUwjbOeRn8u5D",
  "status": "trialing",
  "current_period_start": "2026-11-19T09:30:00Z",
  "current_period_end": "2026-11-19T09:30:00Z",
  "cancel_at_period_end": true,
  "trial_ends_at": "2026-11-19T09:30:00Z",
  "past_due_since": "2026-11-19T09:30:00Z",
  "suspended_at": "2026-11-19T09:30:00Z",
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z",
  "by_workspace_state": {
    "key": 1342
  }
}

List organization subscription invoices itemized by account

Logs

GET /organizations/{organizationID}/subscription/invoices

Returns one cursor-paginated page of the invoices the platform issued to the organization for its subscription. Pass limit and after to page, and status to filter. Requires the organization:billing:read scope in the matching organization context.

Parameters

organizationIDstring · path · required

ID of the organization whose subscription invoices are listed; it must equal the caller's active organization context.

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Organization invoices and account-level plan lines

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 organization:billing:read · Roles: account_finance, account_owner

curl -X GET "$BUSINESS_API/organizations/{organizationID}/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 invoice owned by the organization

Logs

GET /organizations/{organizationID}/subscription/invoices/{id}

Returns one platform invoice issued to the organization. An invoice that belongs to another organization or to a single account returns 404. Requires the organization:billing:read scope in the matching organization context.

Parameters

organizationIDstring · path · required

ID of the organization that owns the invoice; it must equal the caller's active organization context.

idstring · path · required

ID of the platform invoice.

Returns

200 Organization subscription 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 organization:billing:read · Roles: account_finance, account_owner

curl -X GET "$BUSINESS_API/organizations/{organizationID}/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"
}

List plans available to an organization payer

Logs

GET /organizations/{organizationID}/plans

Returns the plans an organization can subscribe to, wrapped in a data array. Requires the organization:billing:read scope in the matching organization context (403 otherwise). The list is not paginated.

Parameters

organizationIDstring · path · required

ID of the organization browsing plans; it must equal the caller's active organization context.

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

langstring · query · optional

The language to answer plan text in, as a language tag (pt, en, pt-MZ). It wins over Accept-Language. A language without a translation falls back to the plan's default text.

Accept-Languagestring · header · optional

The caller's languages by preference, used when lang is not sent.

Returns

200 Available platform plans, name, tagline and capability labels in the caller's language

Show attributes
dataarray of Plan · optional
Show child attributes
idstring · optional
codestring · optional
namestring · optional

Display name in the caller's language on reads

taglinestring · optional

Tagline in the caller's language on reads

name_i18nobject · optional

One text per language, keyed by language tag (pt, en, pt-MZ).

tagline_i18nobject · optional

One text per language, keyed by language tag (pt, en, pt-MZ).

default_namestring · optional

Platform plan list only; the default name behind a localised name

default_taglinestring · optional

Platform plan list only; the default tagline

price_centsinteger · optional
currencystring · optional
max_connectionsinteger · optional
max_usersinteger · optional
max_accountsinteger · optional

Maximum accounts owned by the subscribed organization's legal entity; 0 means no plan cap

max_sandboxesinteger · optional
trial_daysinteger · optional
overage_connection_centsinteger · optional
overage_user_centsinteger · optional
capabilitiesarray of string · optional
capability_labelsarray of CapabilityLabel · optional

The capabilities labelled in the caller's language (reads)

Show child attributes
codestring · required
labelstring · required

The capability's label in the caller's language

publishedboolean · optional
display_orderinteger · optional
highlightedboolean · optional
created_atstring (date-time) · optional
offersarray of PlanOffer · optional

Offers listed beside the plans; the custom offer (code custom) when a published plan has a connection limit.

Show child attributes
codestring · required
labelstring · required

Title in the caller's language

textstring · required

One line in the caller's language

ctastring · required

The link's wording in the caller's language

label_i18nobject · optional

One text per language, keyed by language tag (pt, en, pt-MZ).

text_i18nobject · optional

One text per language, keyed by language tag (pt, en, pt-MZ).

cta_i18nobject · optional

One text per language, keyed by language tag (pt, en, pt-MZ).

contact_pathstring · required

Path on the public site to contact sales

above_connectionsinteger · required

The active connection count the offer starts above

Errors 403

Permissions organization:billing:read · Roles: account_finance, account_owner

curl -X GET "$BUSINESS_API/organizations/{organizationID}/plans" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "pla_2lVU4nTwUfHw6nxUwjbOeRn8u5D",
      "code": "COD-2026-000142",
      "name": "Ana Matsinhe",
      "tagline": "tagline",
      "name_i18n": {
        "en": "Up to 100 customers",
        "pt": "Até 100 clientes"
      },
      "tagline_i18n": {
        "en": "Up to 100 customers",
        "pt": "Até 100 clientes"
      },
      "default_name": "Ana Matsinhe",
      "default_tagline": "default tagline",
      "price_cents": 125000,
      "currency": "MZN",
      "max_connections": 1,
      "max_users": 1,
      "max_accounts": 1,
      "max_sandboxes": 1,
      "trial_days": 1,
      "overage_connection_cents": 1,
      "overage_user_cents": 1,
      "capabilities": [
        "configure"
      ],
      "capability_labels": [
        {
          "code": "COD-2026-000142",
          "label": "label"
        }
      ],
      "published": true,
      "display_order": 1,
      "highlighted": true,
      "created_at": "2026-11-19T09:30:00Z"
    }
  ],
  "offers": [
    {
      "code": "custom",
      "label": "label",
      "text": "text",
      "cta": "cta",
      "label_i18n": {
        "en": "Up to 100 customers",
        "pt": "Até 100 clientes"
      },
      "text_i18n": {
        "en": "Up to 100 customers",
        "pt": "Até 100 clientes"
      },
      "cta_i18n": {
        "en": "Up to 100 customers",
        "pt": "Até 100 clientes"
      },
      "contact_path": "/contact?topic=sales",
      "above_connections": 1
    }
  ]
}

Close an organization and detach its linked accounts

Logs

POST /organizations/{organizationID}/close

Marks an active organization as closed, detaches all organization memberships and records an audit entry, then returns the closed organization. Only an organization owner with the organization:accounts:manage scope may close it, and the body must name successor_member_id: another active owner, not the caller. A missing or invalid successor returns 409. The organization must be active (404 otherwise), and the call returns 409 while the organization still owns accounts that need to be transferred first.

Parameters

organizationIDstring · path · required

ID of the organization to close; it must equal the caller's active organization context.

Body application/json

successor_member_idstring · required

Returns

200 Organization closed; linked accounts were detached and retained

Errors 403 · 409

Permissions organization:accounts:manage · Roles: account_admin, account_owner

curl -X POST "$BUSINESS_API/organizations/{organizationID}/close" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "successor_member_id": "suc_2jVWyrdmOLjMKhhC2nXY4nnW4nZ"
}'
Response 200

Organization closed; linked accounts were detached and retained

Payment instructions for an organization payer

Logs

GET /organizations/{organizationID}/subscription/payment-instructions

Returns the payment instructions the platform operator has configured, such as bank or mobile money details, wrapped in a data array that is empty when none are set. Requires the organization:billing:read scope in the matching organization context.

Parameters

organizationIDstring · path · required

ID of the organization; it must equal the caller's active organization context.

Returns

200 Organization payment instructions

Errors 403

Permissions organization:billing:read · Roles: account_finance, account_owner

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

Organization payment instructions

Submit payment evidence for an organization invoice

Logs

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

Accepts a multipart/form-data upload with a file field (PDF, JPEG or PNG, up to 5 MB by default) and the form fields amount_cents, method, reference (up to 128 characters), paid_on (YYYY-MM-DD, not in the future) and an optional note (up to 500 characters). It stores the proof as pending for platform staff to review and returns 201. Only an organization owner with organization:billing:manage may submit. The invoice must be open (409 otherwise), the method must be one of the enabled platform payment methods, and an open proof with the same method and reference returns 409.

Parameters

organizationIDstring · path · required

ID of the organization paying the invoice; it must equal the caller's active organization context.

idstring · path · required

ID of the open platform invoice that the proof pays.

Returns

201 Created; the proof waits for platform review

Errors 403 · 409

Permissions organization:billing:manage, organization:billing:read · Roles: account_owner

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

Created; the proof waits for platform review

List an organization's proofs of payment to the platform

Logs

GET /organizations/{organizationID}/subscription/payment-proofs

Returns one cursor-paginated page (limit, after) of the proofs of payment the organization has sent for its subscription invoices, with each proof's review status. Requires the organization:billing:read scope in the matching organization context.

Parameters

organizationIDstring · path · required

ID of the organization whose proofs are listed; it must equal the caller's active organization context.

invoice_idstring · query · optional

Optional platform invoice ID; when set, only proofs sent for that invoice are returned.

statusstring · query · optional

Optional review status filter: 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 Organization payment proofs

Errors 403

Permissions organization:billing:read · Roles: account_finance, account_owner

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

Organization payment proofs

Download an organization's payment proof

Logs

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

Streams the stored proof file inline with its original content type and file name, using no-store caching and a sandboxing Content-Security-Policy. A proof that belongs to another organization, or whose file is no longer in storage, returns 404. Requires the organization:billing:read scope in the matching organization context.

Parameters

organizationIDstring · path · required

ID of the organization that sent the proof; it must equal the caller's active organization context.

idstring · path · required

ID of the subscription payment proof.

Returns

200 The stored PDF

Errors 403 · 404

Permissions organization:billing:read · Roles: account_finance, account_owner

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

The stored PDF