Manage Organizations and Billing

These walkthroughs show how to use the Snowglobe Billing Management API (/management/*) to manage organizations, members, and quotas. Every example is plain Python 3 with requests. The tutorials cover the following operator flows:

Quick start: onboard a customer end-to-end

Create an organization
Add users to an organization
Remove users from an organization
Set quotas for an organization
Set up a billing hierarchy (parent and child orgs)

The mutating endpoints are: create org, create invitations, and set/delete quota. Reads (get org, list orgs, list invitations, billing reports) are available to any member.

Prerequisites

A Snowglobe account with billing_admin access. Sign up here.
A Snowglobe API key (see Setup below).
Python 3 with requests installed (pip install requests).

Setup: shared client

Every request is authenticated with an API key sent in the x-api-key header. Generate a key from the Snowglobe web app (under your account/organization settings) and export it as an environment variable. All examples below reuse this one client.

import os
import requests

BASE_URL = os.environ.get("SNOWGLOBE_BASE_URL", "https://api.snowglobe.guardrailsai.com")
API_KEY  = os.environ["SNOWGLOBE_API_KEY"]  # generated in the Snowglobe web app

session = requests.Session()
session.headers.update({
    "x-api-key": API_KEY,
    "Content-Type": "application/json",
})


def request(method: str, path: str, **kwargs) -> requests.Response:
    """Thin wrapper that raises with the server's body on any 4xx/5xx."""
    resp = session.request(method, f"{BASE_URL}{path}", **kwargs)
    if not resp.ok:
        raise RuntimeError(
            f"{method} {path} -> {resp.status_code}\n{resp.text}"
        )
    return resp

Roles

Most flows are role-gated. The four roles are owner, admin, billing_admin, and member.

Action	Required role of the caller
Create an organization	`billing_admin` (platform-level)
Create invitations	`owner`, `admin`, or `billing_admin` in org
List org / invitations	any role in the org
Set / delete quota	`billing_admin` of that org
Read billing reports	any role (child-org reports need `billing_admin`)

A 403 almost always means your API key’s roles don’t satisfy the row above, not that the org is missing (that returns 404).

Quick start: onboard a customer end-to-end

This routine chains the common onboarding path into one function: create the org, invite the initial admins and members, set the quota, and verify the result. It calls helpers defined in the flows below (create_organization_full in Flow 1, create_invitations in Flow 2, and set_quota / get_organization in Flow 4), so copy those in alongside the shared client. Each flow below explains one piece in depth.

def onboard_customer(
    display_name: str,
    name: str,
    admins: list[str],
    members: list[str],
    quota_conversations: int,
    billing_org: str | None = None,
) -> dict:
    """Create an org, invite its people, set its quota, and return a summary."""

    # 1. Create the org. The caller becomes billing_admin automatically. The
    #    admins listed here are invited with the admin role; like all members
    #    they must accept their invitation before they join.
    org = create_organization_full(
        display_name=display_name,
        name=name,
        members=[{"email": e, "roles": ["admin"]} for e in admins],
        billing_org=billing_org,
        quota={"amount": quota_conversations, "unit": "conversations"},
    )
    org_id = org["id"]
    print(f"[1/4] Created org {org_id} ({display_name})")

    # 2. Invite the member-tier users.
    if members:
        invites = create_invitations(
            org_id, [{"email": e, "roles": ["member"]} for e in members]
        )
        print(f"[2/4] Sent {len(invites)} member invitation(s)")
    else:
        print("[2/4] No member invitations to send")

    # 3. Quota was set at creation; confirm / re-assert it here so the routine
    #    is safe to re-run against an org whose quota drifted.
    quota = set_quota(org_id, amount=quota_conversations)
    print(f"[3/4] Quota set to {quota['amount']} {quota['unit']}")

    # 4. Verify final state.
    final = get_organization(org_id)
    summary = {
        "org_id": org_id,
        "members": [m["email"] for m in final["members"]],
        "pending_invitations": [i["invitee"] for i in final["pendingInvitations"]],
        "quota": final.get("quota"),
    }
    print(f"[4/4] Verified: {len(summary['members'])} member(s), "
          f"{len(summary['pending_invitations'])} pending, "
          f"quota={summary['quota']}")
    return summary


summary = onboard_customer(
    display_name="Globex Corp",
    name="globex",
    admins=["ceo@globex.example", "ops@globex.example"],
    members=["eng1@globex.example", "eng2@globex.example"],
    quota_conversations=75_000,
)
print(summary)

Notes:

The caller is assigned billing_admin on the new org automatically, and is the only account added directly. Everyone else, whether passed in members at create-time or through the invitations endpoint, and regardless of role, must accept an invitation before they join. So the admins and members here all show up under pending_invitations until they accept.
The caller must be a billing_admin for step 1 (create) and step 3 (quota). The same API key is fine for the invitations in step 2, since billing_admin satisfies that gate too.
To onboard a customer under a billing parent, pass billing_org=parent_id (see Flow 5).

Flow 1: Create an organization

Endpoint: POST /management/organizations Who: the authenticated user must be a billing_admin.

Minimal create

Only display_name is required.

def create_organization(display_name: str, name: str | None = None) -> dict:
    body = {"display_name": display_name}
    if name is not None:
        body["name"] = name
    return request("POST", "/management/organizations", json=body).json()


org = create_organization(display_name="Acme Robotics", name="acme-robotics")
print("Created org:", org["id"], "-", org["display_name"])

The 201 response is the full Organization object. The fields you’ll most often key off of afterwards:

org_id  = org["id"]                 # uuid; you pass this into every other flow
members = org["members"]            # list of {id, name, email, roles[]}
pending = org["pendingInvitations"] # list of compact invitations (empty on a fresh org)
quota   = org.get("quota")          # None unless you seeded one (see below)
usage   = org.get("usage")          # None until consumption is recorded

Create with members, a billing parent, and an initial quota

You can seed people in the same call that creates the org. members here is a list of OrganizationMemberInput, the same shape used to invite people in Flow 2 (each needs roles, plus id or email). The caller (the billing_admin making this request) is the only account added to the org directly. Everyone listed in members receives an invitation and must accept it before they appear in org["members"], regardless of the role they’re assigned. In other words, passing someone in members is a shortcut for inviting them at create-time, not a way to add them without acceptance.

def create_organization_full(
    display_name: str,
    name: str | None = None,
    members: list[dict] | None = None,
    billing_org: str | None = None,
    quota: dict | None = None,
) -> dict:
    body: dict = {"display_name": display_name}
    if name is not None:
        body["name"] = name
    if members is not None:
        body["members"] = members
    if billing_org is not None:
        body["billingOrg"] = billing_org
    if quota is not None:
        body["quota"] = quota
    return request("POST", "/management/organizations", json=body).json()


org = create_organization_full(
    display_name="Acme Robotics EU",
    name="acme-robotics-eu",
    members=[
        {"email": "ops-lead@acme.example", "roles": ["admin"]},
        {"email": "finance@acme.example",  "roles": ["billing_admin"]},
    ],
    billing_org="11111111-1111-1111-1111-111111111111",  # existing parent org id
    quota={"amount": 50_000, "unit": "conversations"},
)
print("Created:", org["id"], "| quota:", org["quota"])

billingOrg rules:

The referenced org must already exist.
It must not itself have a billingOrg. Nested billing hierarchies are rejected. A parent can have many children; a child cannot be a parent.
Violating either rule returns 400.

Confirm it exists

def get_organization(org_id: str) -> dict:
    return request("GET", f"/management/organizations/{org_id}").json()


fetched = get_organization(org["id"])
assert fetched["id"] == org["id"]

GET on an org you have no role in returns 403; a missing id returns 404.

Flow 2: Add users to an organization

Endpoint: POST /management/organizations/{orgId}/invitations Who: the caller needs owner, admin, or billing_admin in that org.

How adding a user works

There is no add-member-directly endpoint. You invite users, and they become members once they accept. The lifecycle:

POST invitations   ->  invitee appears in pendingInvitations
                       (invitee follows invitation_url and accepts, out of band)
                   ->  member appears in org["members"], drops out of pendingInvitations

Batch-invite

The request body is an array of OrganizationMemberInput. Each entry needs roles and at least one of email or id. When only id is given, the server resolves the email via the auth provider at send-time.

def create_invitations(org_id: str, invites: list[dict]) -> list[dict]:
    return request(
        "POST",
        f"/management/organizations/{org_id}/invitations",
        json=invites,
    ).json()


invitations = create_invitations(org_id, [
    {"email": "engineer@acme.example",  "roles": ["member"]},
    {"email": "manager@acme.example",   "roles": ["admin"]},
    {"id": "auth0|abc123",              "roles": ["member"]},  # resolved to email server-side
])

for inv in invitations:
    print(f"{inv['invitee']:30} roles={inv['roles']} expires={inv['expires_at']}")

The response is a list of full OrganizationInvitation objects, including the invitation_url each invitee must follow to accept. Common 400 causes: an entry missing roles, or an entry with neither id nor email.

List invitations to track who hasn’t accepted

This endpoint returns only unaccepted invitations, so everything it returns is still pending; no client-side filtering is needed. An invitation drops out of the list once the invitee accepts.

def list_invitations(org_id: str) -> list[dict]:
    return request(
        "GET", f"/management/organizations/{org_id}/invitations"
    ).json()


outstanding = list_invitations(org_id)
print(f"{len(outstanding)} invitation(s) still pending acceptance")
for inv in outstanding:
    print(f"  - {inv['invitee']:30} roles={inv['roles']} expires={inv['expires_at']}")

Verify the user landed as a member

After the invitee accepts, they move from pendingInvitations into members:

def find_member(org_id: str, email: str) -> dict | None:
    org = get_organization(org_id)
    return next((m for m in org["members"] if m["email"] == email), None)


member = find_member(org_id, "engineer@acme.example")
print("Joined." if member else "Still pending; invitation not yet accepted.")

Flow 3: Remove users from an organization

Membership changes run through the invitation lifecycle, so the operator task here is to audit who currently has access, both active members and outstanding invitations, and confirm the resulting state.

def access_report(org_id: str) -> None:
    org = get_organization(org_id)

    print(f"Organization: {org['display_name']} ({org['id']})\n")

    print("Active members:")
    for m in org["members"]:
        print(f"  - {m['email']:30} roles={m['roles']}")

    print("\nPending invitations (not yet accepted):")
    for inv in org["pendingInvitations"]:
        print(f"  - {inv['invitee']:30} roles={inv['roles']} expires={inv['expires_at']}")


access_report(org_id)

You can filter that report to find a specific person before acting on them:

def find_access(org_id: str, email: str) -> dict:
    org = get_organization(org_id)
    return {
        "member": next((m for m in org["members"] if m["email"] == email), None),
        "pending_invitation": next(
            (inv for inv in org["pendingInvitations"] if inv["invitee"] == email),
            None,
        ),
    }


status = find_access(org_id, "engineer@acme.example")
print("Active member." if status["member"] else "Not an active member.")
print("Has pending invite." if status["pending_invitation"] else "No pending invite.")

Flow 4: Set quotas for an organization

Endpoints: PUT /management/organizations/{orgId}/quota (set/replace), DELETE /management/organizations/{orgId}/quota (clear). Who: the caller must be the billing_admin of that specific org.

What a quota is

A quota is a single DimensionedValue:

{ "amount": 100000, "unit": "conversations" }

amount: an integer cap that applies per billing period. Billing periods are monthly in practice, so the quota is effectively a monthly cap; usage resets each period.
unit: a string. In practice it is always "conversations", and the server defaults it to "conversations" when omitted, so you don’t have to send it. Sending it explicitly makes the code more readable, and the field is left open for forward compatibility.

Quota is a replace, not an increment: each PUT overwrites the previous value wholesale. There is no separate “add 10k” call at this layer. The API models three distinct numeric concepts. Only the first is settable here; the other two are read-only. Keep them separate so you don’t confuse them with the quota.

Concept	Where it lives	Settable?	Unit(s)	Meaning
Quota	`org.quota`, `PUT/DELETE .../quota`	Yes (this flow)	`conversations`	The cap you set. `null` means no limit configured.
Usage	`org.usage`, and per-period in billing reports	No	`conversations`	Consumption in the current billing period.
Adjustment	`billingReport.adjustments[]`	No	`conversations` or `USD`	Manual credits/debits applied to a period’s bill (with a `description`).

When someone says “set the quota,” they mean the first row: a conversations cap via PUT. Usage and adjustments are surfaced for visibility (see reading them back below) but are not writable through this API.

Set or replace a quota

def set_quota(org_id: str, amount: int, unit: str = "conversations") -> dict:
    return request(
        "PUT",
        f"/management/organizations/{org_id}/quota",
        json={"amount": amount, "unit": unit},
    ).json()


new_quota = set_quota(org_id, amount=100_000)
print("Quota is now:", new_quota)  # -> {'amount': 100000, 'unit': 'conversations'}

The 200 response echoes back the stored DimensionedValue. Raising or lowering the cap later is the same call with a new amount.

Remove a quota (back to unlimited/unconfigured)

def delete_quota(org_id: str) -> None:
    resp = request("DELETE", f"/management/organizations/{org_id}/quota")
    assert resp.status_code == 204  # No Content


delete_quota(org_id)
assert get_organization(org_id).get("quota") is None
print("Quota cleared.")

DELETE returns 204 No Content, so there is no body to parse.

Read quota, usage, and billing back

Quota and usage ride directly on the Organization object. Historical billing (usage, adjustments, and final billed amount per period) comes from the billing-reports endpoint.

def quota_status(org_id: str) -> None:
    org   = get_organization(org_id)
    quota = org.get("quota")
    usage = org.get("usage")

    if quota is None:
        print("No quota configured (unlimited).")
    else:
        used = usage["amount"] if usage else 0
        pct  = (used / quota["amount"] * 100) if quota["amount"] else 0
        print(f"Usage: {used}/{quota['amount']} {quota['unit']} ({pct:.1f}%)")


def billing_reports(org_id: str, start: str | None = None, end: str | None = None) -> list[dict]:
    # start / end are ISO-8601 date-times, both optional.
    params = {}
    if start:
        params["startDate"] = start
    if end:
        params["endDate"] = end
    return request(
        "GET",
        f"/management/organizations/{org_id}/billing-reports",
        params=params,
    ).json()


quota_status(org_id)

for report in billing_reports(org_id, start="2026-01-01T00:00:00Z"):
    print(f"\n{report['billingPeriod']}: "
          f"{report['usage']['amount']} {report['usage']['unit']} used "
          f"-> billed {report['billedAmount']['amount']} {report['billedAmount']['unit']}")
    for adj in report["adjustments"]:
        sign = "+" if adj["amount"] >= 0 else ""
        print(f"    adjustment {sign}{adj['amount']} {adj['unit']}: "
              f"{adj.get('description', '')}")

If the caller is a billing_admin, the billing-reports endpoint also returns reports for any child orgs billed under this one (those whose billingOrg points here). A non-billing-admin sees only the org’s own reports.

Flow 5: Set up a billing hierarchy (parent and child orgs)

Snowglobe supports a one-level billing hierarchy: a parent org that carries the billing relationship, and any number of child orgs billed under it. This is the reseller / multi-tenant pattern. Each customer team gets its own org, with its own members and quota, but the bills roll up to a single parent.

The nesting rule

billingOrg may point only at an org that does not itself have a billingOrg:

parent (billingOrg = null)
  |- child A (billingOrg = parent.id)   ok
  |- child B (billingOrg = parent.id)   ok

child A (billingOrg = parent.id)
  |- grandchild (billingOrg = childA.id)   rejected, 400: childA already has a billingOrg

A parent can have many children; a child can never be a parent. Attempting to nest returns 400.

Build the hierarchy

# 1. Create the parent. It has no billingOrg of its own.
parent = create_organization_full(
    display_name="Acme Robotics Global",
    name="acme-global",
    members=[{"email": "finance@acme.example", "roles": ["billing_admin"]}],
)
parent_id = parent["id"]
print("Parent:", parent_id)

# 2. Create children pointing at the parent. Each can carry its own members
#    and its own quota independent of the parent.
children_spec = [
    {"display_name": "Acme EU",   "name": "acme-eu",   "quota": 50_000},
    {"display_name": "Acme US",   "name": "acme-us",   "quota": 120_000},
    {"display_name": "Acme APAC", "name": "acme-apac", "quota": 30_000},
]

children = []
for spec in children_spec:
    child = create_organization_full(
        display_name=spec["display_name"],
        name=spec["name"],
        billing_org=parent_id,
        quota={"amount": spec["quota"], "unit": "conversations"},
    )
    children.append(child)
    print(f"  child: {child['display_name']:20} {child['id']}  quota={child['quota']}")

create_organization_full is defined in Flow 1.

Guard against the nesting error

If you’re building the hierarchy from data you don’t fully control, check the prospective parent before you point at it. An org that already has a billingOrg cannot serve as a parent:

def assert_can_be_billing_parent(org_id: str) -> None:
    org = get_organization(org_id)
    if org.get("billingOrg"):
        raise ValueError(
            f"{org['display_name']} ({org_id}) already bills under "
            f"{org['billingOrg']}, so it cannot be a billing parent."
        )


assert_can_be_billing_parent(parent_id)  # passes; parent has no billingOrg

Read the whole hierarchy’s billing at once

When the caller is a billing_admin, the parent’s billing-reports endpoint returns reports for the parent and every child billed under it, so a single call gives you the consolidated view:

reports = billing_reports(parent_id, start="2026-01-01T00:00:00Z")

by_org: dict[str, int] = {}
for r in reports:
    by_org[r["orgId"]] = by_org.get(r["orgId"], 0) + r["billedAmount"]["amount"]

print("Consolidated billed amount by org:")
for oid, total in by_org.items():
    print(f"  {oid}: {total}")

billing_reports is defined in Flow 4. Setting or clearing a quota is always per-org (there is no inherited quota), so use Flow 4 against each child id to adjust its cap.

Appendix: status codes

Code	Meaning in this API
`200`	Read succeeded, or quota `PUT` succeeded.
`201`	Organization created.
`204`	Quota deleted (no body).
`400`	Bad payload, e.g. bad `billingOrg`, or invite entry missing `roles`/`id`+`email`.
`403`	Your API key’s roles don’t satisfy the action (see the roles table up top).
`404`	Organization not found.

The request() helper at the top raises RuntimeError with the server’s body on any 4xx/5xx code, so failures surface the actual reason rather than a bare status number.

Getting Started

How-to Guides

Examples & Showcase

Snowglobe Connect Reference

Snowglobe SDK Reference

Support

Manage Organizations and Billing

Prerequisites

Setup: shared client

Roles

Quick start: onboard a customer end-to-end

Flow 1: Create an organization

Minimal create

Create with members, a billing parent, and an initial quota

Confirm it exists

Flow 2: Add users to an organization

How adding a user works

Batch-invite

List invitations to track who hasn’t accepted

Verify the user landed as a member

Flow 3: Remove users from an organization

Flow 4: Set quotas for an organization

What a quota is

Set or replace a quota

Remove a quota (back to unlimited/unconfigured)

Read quota, usage, and billing back

Flow 5: Set up a billing hierarchy (parent and child orgs)

The nesting rule

Build the hierarchy

Guard against the nesting error

Read the whole hierarchy’s billing at once

Appendix: status codes

​Prerequisites

​Setup: shared client

​Roles

​Quick start: onboard a customer end-to-end

​Flow 1: Create an organization

​Minimal create

​Create with members, a billing parent, and an initial quota

​Confirm it exists

​Flow 2: Add users to an organization

​How adding a user works

​Batch-invite

​List invitations to track who hasn’t accepted

​Verify the user landed as a member

​Flow 3: Remove users from an organization

​Flow 4: Set quotas for an organization

​What a quota is

​The kinds of quota-related values

​Set or replace a quota

​Remove a quota (back to unlimited/unconfigured)

​Read quota, usage, and billing back

​Flow 5: Set up a billing hierarchy (parent and child orgs)

​The nesting rule

​Build the hierarchy

​Guard against the nesting error

​Read the whole hierarchy’s billing at once

​Appendix: status codes

Prerequisites

Setup: shared client

Roles

Quick start: onboard a customer end-to-end

Flow 1: Create an organization

Minimal create

Create with members, a billing parent, and an initial quota

Confirm it exists

Flow 2: Add users to an organization

How adding a user works

Batch-invite

List invitations to track who hasn’t accepted

Verify the user landed as a member

Flow 3: Remove users from an organization

Flow 4: Set quotas for an organization

What a quota is

The kinds of quota-related values

Set or replace a quota

Remove a quota (back to unlimited/unconfigured)

Read quota, usage, and billing back

Flow 5: Set up a billing hierarchy (parent and child orgs)

The nesting rule

Build the hierarchy

Guard against the nesting error

Read the whole hierarchy’s billing at once

Appendix: status codes