# Manage Customers & Credentials Most billing problems don't come from the billing engine - they come from the customer layer beneath it. A customer who should be getting one consolidated invoice ends up with five. An internal team's AI usage never gets attributed back to them. A support engineer needs to know which subscription generated a spike, but there's no clean way to trace from a metering event back to the account that caused it. Revenium's customer model is built around four objects - Organizations, Subscribers, Credentials, and Statements - that together answer four related questions: *Who's the customer? Who's using the service? Which API key is this call coming from? What do they currently owe?* Getting this model right upfront is what makes the rest of billing and analytics work cleanly. All four live under **Configuration > Customers**, as tabs across the top of the page. ### :users: The Customer Hierarchy The four objects map to four levels of granularity: * **Organizations** represent the top-level customer account. An external company buying your product, or an internal business unit being allocated costs. * **Subscribers** are individual users or service accounts within an organization. They're the entity that generates usage. * **Credentials** are the unique identifiers - typically API keys - that a subscriber uses to access your service. A single subscriber can hold multiple credentials. * **Statements** are the financial view - outstanding balances and unpaid invoices per customer, aggregated across everything below. The flow runs downward: an organization has one or more subscribers, each subscriber holds one or more credentials, and statements roll up the financial state of everything underneath. A metering event arriving with a credential ID gets traced back through the chain to land on the right subscription and the right statement. ### :building: Organizations Head to **Configuration > Customers > Organizations** to see every customer account you have. The list shows Name, ID, Parent ID, and External ID - with the ID columns being Revenium's stable hash identifiers that survive renames. Click **New Org** to add one. Creation happens across three steps: #### General * **Name** (required) - what the organization is called. Shown in dashboards, invoices, and analytics. * **Parent** - optional. Setting a parent nests this organization under another one, which is how you express structures like a parent company with multiple subsidiaries or a business unit with sub-teams. Omit it for top-level organizations. * **External Id** - optional identifier for mapping to an external system (your CRM, ERP, or customer database). Useful when you want to correlate Revenium records with records elsewhere. * **Currency** - the default currency for this organization's billing. Defaults to USD. * **Associated Domains** - optional list of email domains tied to this organization. Useful for B2B scenarios where you want subscribers with matching email domains to be recognized as belonging to this organization. * **Storefront URL** - optional URL for linked commerce portal configurations. #### Billing Address and billing contact information used on invoices and statements: * **Address 1** and **Address 2** - street address * **Country**, **State**, **City**, **Zip** - geographic fields * **Billing Phone Number** - contact number for billing queries * **Billing Email** - where invoices and billing notifications are sent * **Remittance Instructions** - free-text field for payment instructions that should appear on invoices None of these are required to create the organization. They're prompted at creation because it's easier to fill them in once upfront than to come back later - but they can be skipped and added on edit. #### Metadata **Custom Metadata** lets you attach arbitrary key-value pairs to the organization. Each entry is a Field Name plus a Field Value, and you can add as many as you need with the **+** button. Metadata isn't used by Revenium's billing engine directly, but it's returned on API queries and surfaces in analytics - useful for internal tagging, segmentation, or passing attributes through to downstream finance systems. ### :basket-shopping: Subscribers **Configuration > Customers > Subscribers** lists every individual user or service account across all organizations. The table shows Organization/Email, First Name, Last Name, and Subscriber ID. Click **Add Subscriber** to create one. The form is a single step: * **First Name** and **Last Name** - optional identification fields. * **Email** (required) - this is the primary identifier for the subscriber and is what metering events should reference when they want to tie usage to a specific person or service account. * **Subscriber ID** - optional custom identifier. If not supplied, Revenium generates one. * **Organizations** (required) - which organization this subscriber belongs to. Defaults to UNCLASSIFIED if unset. The UNCLASSIFIED organization is Revenium's default bucket for subscribers whose organization hasn't been specified. If you see a lot of activity landing there, it's a signal that your metering events are missing organization identifiers - which is worth fixing for attribution and analytics clarity. ### :key: Credentials A credential is how a specific API key or token identifier gets tied to a subscriber and, optionally, a subscription. The **Credentials** tab lists every credential across the system with columns for Created, Subscriber, Credential Name, Organization/Subscriber, and Credential ID. Click **New Credential** to add one: * **Subscriber Credential Name** (required) - your internal label for this credential. Typically describes which application or team the key is for (e.g. "Mobile App Production Key" or "Data Science Team - Staging"). * **Subscriber E-Mail** (required) - which subscriber owns this credential. Pick from the subscribers in the system. * **Organization** (required) - which organization the credential belongs to. Normally matches the subscriber's organization. * **Credential ID** (required) - the actual unique identifier your application will include in metering events. This is what ties an incoming metering event to this credential. Commonly an API key, OAuth client ID, or JWT identifier. * **External Secret** - optional secret associated with the credential. Not surfaced in metering events. * **Subscription** - optionally attach this credential to a specific subscription. If not set, the credential exists standalone and will be auto-associated when the first metering event arrives. * **Tags** - optional free-form tags for filtering and grouping. The key design point: multiple credentials can belong to a single subscriber, and multiple credentials can be attached to the same subscription. This is what makes B2B scenarios work cleanly - a customer company gets one subscription, issues multiple API keys to their internal teams, and you can both consolidate billing into one invoice *and* report usage separately per key. #### When to Create Credentials Explicitly If a metering event arrives with a subscription identifier but no matching credential, Revenium auto-creates one. That's fine for simple cases, but there are two reasons to create credentials explicitly: * **Provisioning specific API keys in advance** - when your application issues keys to customers ahead of first use, so the credential exists before any metering event arrives. * **Adding metadata** - names, tags, external secrets, or explicit subscription links aren't created automatically, so explicit creation is how you get those attached. ### :file-invoice: Statements The **Statements** tab gives a customer-level financial summary. The table shows Customer, Outstanding Balance, and Open Invoices - with every customer in the system listed, regardless of whether they currently owe anything. The **Unpaid Invoices** link on each row opens the filtered invoice view for that customer - useful when chasing outstanding payments or investigating a specific account. This is the view to send to anyone asking "what do our customers currently owe us?" without giving them access to individual subscription or transaction detail. ### :object-group: Designing Your Customer Model Two decisions matter more than the rest: **One subscription per customer, or one per use case?** In B2B scenarios, most teams start with one subscription per customer company and handle internal team attribution through credentials. This gives one invoice per company, while still letting you report usage and cost per team. Creating multiple subscriptions per customer makes sense when different teams genuinely buy different products, or when contractual terms vary per subscription. **How far down to nest organizations?** Revenium supports parent/child organization hierarchies. For external customers, a flat structure is usually enough. For internal cost allocation across a large organization, nested orgs let you roll up costs from teams → departments → divisions cleanly. Don't over-model this upfront - it's easier to introduce hierarchy later than to flatten it. ### :code: Via API Everything on this page can be managed programmatically, which matters most when customer signups and provisioning need to happen automatically as part of your own product. Full endpoints for [organizations](https://revenium.readme.io/reference/get_organization), [subscribers](https://revenium.readme.io/reference/get_subscriber), and [credentials](https://revenium.readme.io/reference/get_credential) cover create, read, update, delete, and list operations. [Invoices](https://revenium.readme.io/reference/list_invoices) are available via API for teams pulling statement data into their own admin tools. The typical B2B signup flow on the customer side is four chained calls: create the organization, create the subscriber under it, issue a subscription (covered in [Build Usage-Based Billing](/monetize-your-ai/tutorial-build-usage-based-billing.md)), and optionally create explicit credentials for each API key the customer needs. Store the IDs returned from these calls against your own customer records and the rest of billing happens automatically from that point. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.revenium.io/monetize-your-ai/manage-customers-and-credentials.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.