Customers and Entities

Customers represent billable accounts or workspaces. Entities represent children such as users, agents, projects, or environments.

Upsert a customer

customers.upsert() sends the merchant’s secret key directly to Nozle Core. Core derives the owning organization from that key; the SDK never provisions a customer through a global or master organization.

from nozle import Nozle

nozle = Nozle()  # reads NOZLE_SECRET_KEY

customer = nozle.customers.upsert(
    "workspace_123",
    name="Acme Workspace",
    email="billing@example.com",
)

external_id is required. name, email and billing_configuration are optional.

Link a customer that already exists in Stripe

Pass billing_configuration with the Stripe customer ID to link it in the same call (requires nozle-sdk 0.12.0). Nozle stores the link and does not create a new Stripe customer. Sending the same upsert again is safe.

nozle.customers.upsert(
    "workspace_123",
    name="Acme Workspace",
    billing_configuration={
        "payment_provider": "stripe",
        "payment_provider_code": "stripe_main",
        "provider_customer_id": "cus_ABC123",
    },
)

payment_provider is required inside billing_configuration. payment_provider_code, provider_customer_id, sync_with_provider and provider_payment_methods are optional. Nozle keeps the assignment with or without sync_with_provider, and checkout charges only through the assigned connection. See Assign the connection to customers.

Read Entities

entity = nozle.entities.get("workspace_123", "user_42")

page = nozle.entities.list(
    "workspace_123",
    status="active",
    limit=50,
)

next_page = (
    nozle.entities.list(
        "workspace_123",
        status="active",
        limit=50,
        cursor=page["next_cursor"],
    )
    if page["next_cursor"]
    else None
)

Entity status accepts active, suspended, or deleted. List limits must be integers from 1 to 100.

Upsert an Entity

result = nozle.entities.upsert(
    "workspace_123",
    "user_42",
    status="active",
    name="Asha",
    metadata={"role": "agent"},
    idempotency_key="entity-user-42-v1",
)

print(result["action"])
print(result["replayed"])

Entity IDs and idempotency keys are limited to 255 UTF-8 bytes. Retry an uncertain mutation with the same key and payload.

Suspend and activate

nozle.entities.suspend(
    "workspace_123",
    "user_42",
    idempotency_key="suspend-user-42-v1",
)

nozle.entities.activate(
    "workspace_123",
    "user_42",
    idempotency_key="activate-user-42-v2",
)

These helpers first fetch the Entity and preserve its current name and metadata.

Bulk upsert

result = nozle.entities.bulk_upsert(
    "workspace_123",
    [
        {"external_id": "user_42", "name": "Asha", "status": "active"},
        {"external_id": "user_43", "name": "Ravi", "status": "suspended"},
    ],
    idempotency_key="workspace-123-users-import-7",
)

print(result["counts"])

Each bulk call accepts 1–500 unique Entity IDs.

Seat billing is explicit

Entity lifecycle methods do not emit Feature seat events. Track seat additions and removals separately when your catalog bills seats.

nozle.track(
    "workspace_123",
    "billable_seats",
    metadata={"user_id": "user_42", "operation": "add"},
    subscription_id="workspace_123_subscription",
    transaction_id="seat-add-user-42-v1",
)

Use the same Entity ID with nozle.credits and nozle.usage for per-Entity balances and attribution.

Setup

Billing

Customers

Entitlements

Margin Intelligence

LLM Usage

Customers and Entities

Upsert a customer

Link a customer that already exists in Stripe

Read Entities

Upsert an Entity

Suspend and activate

Bulk upsert

Seat billing is explicit

​Upsert a customer

​Link a customer that already exists in Stripe

​Read Entities

​Upsert an Entity

​Suspend and activate

​Bulk upsert

​Seat billing is explicit

Upsert a customer

Link a customer that already exists in Stripe

Read Entities

Upsert an Entity

Suspend and activate

Bulk upsert

Seat billing is explicit