Tenants API

Read and update your tenant (organization) configuration — company details, billing currency, tax settings and invoicing terms.

Get Tenant Settings

GET /api/v1/tenant

Returns your tenant's current configuration.

Response:

{
  "company_name": "My SaaS Company",
  "currency": "USD",
  "address": {
    "line1": "123 Main St",
    "line2": "Suite 400",
    "city": "San Francisco",
    "state": "California",
    "zip": "94105",
    "country": "US"
  },
  "prepaid_settings": {
    "invoice_settings": {
      "net_terms_days": 15,
      "suspension_days_after_overdue": 7,
      "termination_days_after_overdue": 30
    },
    "tax_settings": {
      "taxes": [
        { "id": "16", "name": "VAT", "tax_percent": 20, "applied_to": "all_charges", "used": false, "assigned": true }
      ],
      "inclusive": false
    }
  },
  "postpaid_settings": {
    "invoice_settings": {
      "net_terms_days": 15,
      "suspension_days_after_overdue": 7,
      "termination_days_after_overdue": 30
    },
    "tax_settings": {
      "taxes": [
        { "id": "16", "name": "VAT", "tax_percent": 20, "applied_to": "all_charges", "used": false, "assigned": true }
      ],
      "inclusive": false
    }
  },
  "onboarding_completed": true
}

Field	Description
company_name	Your company / business name.
currency	Base billing currency (ISO 4217 code, e.g. USD).
address	Company billing address (line1, line2, city, state, zip, country).
prepaid_settings, postpaid_settings	The invoicing and tax settings for your prepaid and your postpaid customers. The two billing models share one set of settings, so the two objects are always equal. Each holds the following fields.
tax_settings.taxes	Configured tax options. Each has an id, a name, tax_percent (e.g. 20 for 20%) and what it is applied_to: all_charges, only_usage_charges or all_recurring_charges. used and assigned are filled by the billing backend and are not part of an update. assigned is false on a tax that no longer applies.
tax_settings.inclusive	When true, listed prices already include tax; when false, tax is added on top.
invoice_settings.net_terms_days	Days after an invoice is issued before it becomes overdue.
invoice_settings.suspension_days_after_overdue	Days an invoice can be overdue before the customer is auto-suspended.
invoice_settings.termination_days_after_overdue	Days an invoice can be overdue before the customer is auto-terminated.
onboarding_completed	true once initial setup has been completed.

Update Tenant Settings

PATCH /api/v1/tenant

Updates tenant configuration. Only the fields you include are changed; everything else is left as-is.

Request:

{
  "company_name": "My SaaS Company",
  "address": {
    "line1": "123 Main St",
    "city": "San Francisco",
    "state": "California",
    "zip": "94105",
    "country": "US"
  },
  "prepaid_settings": {
    "invoice_settings": {
      "net_terms_days": 15,
      "suspension_days_after_overdue": 7,
      "termination_days_after_overdue": 30
    },
    "tax_settings": {
      "taxes": [
        { "id": "16", "name": "VAT", "tax_percent": 20, "applied_to": "all_charges" }
      ],
      "inclusive": false
    }
  }
}

Field	Description
company_name	New company name (omit to leave unchanged). Trimmed of surrounding whitespace, at most 59 characters, and emoji are not accepted.
address	New billing address (omit to leave unchanged). zip takes letters, digits, spaces and hyphens only, 2 to 10 characters.
prepaid_settings, postpaid_settings	New settings for your prepaid or your postpaid customers (omit to leave unchanged), each holding invoice_settings and tax_settings and nothing else. The two billing models share one set of settings, so a change sent in either applies to both. A request that sends invoice_settings, or tax_settings, in both is refused with a 422 unless the two are identical.
prepaid_settings.tax_settings	New tax configuration (omit to leave unchanged). When you send taxes, send every tax you want applied: a tax that carries the id from a read is changed, and a tax with no id is added. A tax you leave out stops applying and is deleted. If the billing engine still records it as in use, it stays in the list with assigned: false, so leave it out of later writes too.
prepaid_settings.invoice_settings	New invoicing / dunning configuration (omit to leave unchanged).
onboarding_completed	Mark onboarding complete (omit to leave unchanged).

invoice_settings and tax_settings sent at the top level of the request are refused with a 422: send them inside prepaid_settings or postpaid_settings.

Inside address, omitting a field leaves it unchanged and sending it empty clears it. The country is the exception: send null to clear it, not "". A state sent with the country empty is refused with a 422, because the region is stored against its country.

Returns the updated tenant settings (same shape as Get Tenant Settings).

Get Currencies

GET /api/v1/currencies

Returns the list of supported billing currencies.

Response:

{
  "currencies": [
    { "code": "USD", "name": "US Dollar" },
    { "code": "EUR", "name": "Euro" }
  ],
  "default_currency": "USD"
}

Field	Description
currencies	Available currencies, each with a code (ISO 4217) and name.
default_currency	Your tenant's base/default currency code.