Skip to main content

Update Organization Billing State

PATCH 
/api/v1/internal/account/organizations/:organization_id/billing-state

Manually update organization billing state and sync to Airbyte.

This is an internal admin-only endpoint for testing and emergency use. It updates the billing state in Sonar and automatically syncs to Airbyte to ensure workspaces/connections are enabled or disabled appropriately.

Billing State Mapping (Sonar → Airbyte):

  • TRIAL → MANUAL (syncs enabled)
  • ENABLED → MANUAL (syncs enabled)
  • GRACE_PERIOD → MANUAL (syncs enabled, Sonar tracks grace period internally)
  • DISABLED → LOCKED (syncs disabled - Airbyte API doesn't allow DISABLED status)
  • LOCKED → LOCKED (syncs disabled, requires payment)

The mapping ensures that:

  • Paying customers (TRIAL/ENABLED/GRACE_PERIOD) have unrestricted access (MANUAL)
  • Sonar tracks grace period end dates internally without Airbyte involvement
  • Customers who cancel (DISABLED) are locked in Airbyte (LOCKED status)
  • Customers with payment issues (LOCKED) have syncs blocked until payment

Note: Airbyte's DISABLED status is reserved for internal billing automation only. When Sonar sets DISABLED, we use LOCKED which has the same effect (disables connections).

Grace Period Handling:

  • If grace_period_ends_at is not provided when transitioning to GRACE_PERIOD, it will be auto-calculated as +1 day from now (matching webhook behavior)
  • grace_period_ends_at is stored in Sonar DB but NOT sent to Airbyte

Args: organization_id: The organization to update request: The billing state to set and optional grace period end time

Returns: Updated billing state information

Raises: HTTPException 404: Organization not found HTTPException 500: Failed to sync to Airbyte (will trigger retry)

Request​

Responses​

Successful Response