Customers

A customer in PortaAIM represents a billing entity — a business or individual that uses your AI services, receives invoices, and makes payments.

Customer Lifecycle

Created → Active → (Suspended) → (Terminated)

Status	Description
Active	Customer can use services and is billed normally
Suspended	Service access is blocked; the subscription fee is credited back for the suspended days; can be reactivated
Terminated	Account is closed; no billing or service access

Service status

The status above is the account's lifecycle. Separately, a customer can be Active yet temporarily unable to use paid services — most often because their balance has reached the credit limit. PortaAIM exposes this as a distinct service status, so an "Active" customer who can't actually transact is never hidden behind the lifecycle badge.

Service status	What it means
Open	Paid services are available
Credit exceeded	A postpaid customer's balance has reached the credit limit — paid services are paused until they pay down the balance (or you raise the limit)
No available funds	A prepaid customer's balance has reached zero — paid services are paused until they top up
Spending limit reached	The customer hit their daily spending cap; it resets at the start of the next day
Service limited	A non-payment service limitation has been applied
Suspension delayed / Service limitation delayed	A pause has been temporarily lifted until a set date; services work in the meantime
Suspended / Blocked	Services are stopped (an overdue invoice, or an administrative block)
Payment frozen	Automatic payment is paused after repeated failures; services still work
Provisionally terminated / Closed / Exported	The account is no longer operational

For example, a customer over their credit limit shows an Active lifecycle status with a Credit exceeded service status. See How a Customer Is Billed for how the balance and credit limit interact.

In the app, the service status is the status shown in the customer's status badge: a customer who can't transact reads as Credit exceeded (amber), not "Active". Active, Suspended, and Terminated still show as before. Hover any status badge for what it means and how it clears.

You can also filter the customer list by status. The filter groups the lifecycle statuses (Active, Suspended, Terminated) and the blocked ones (Credit exceeded, No available funds, Spending limit reached, Service limited). Filtering by Active shows every active customer — including those whose paid services are currently blocked; pick a specific blocked status to find just the customers who can't transact right now.

Customer Properties

Each customer has:

Property	Description
Name	Company or individual name
Email	Primary contact email
External ID	The customer's unique identifier in your SaaS platform (required). Used to match charging requests to the correct customer.
Plan	The pricing plan they're on
Balance	What the customer currently owes (see Customer Balance below)
Credit limit	Maximum amount the customer is allowed to owe before paid services are blocked
Status	Active, Suspended, or Terminated
Service status	Whether paid services are usable right now — e.g. Open, Credit exceeded, No available funds (see Service status above)
Trial end date	If on a trial, when it expires

How a Customer Is Billed

Each customer is created on one of two billing models, Postpaid or Prepaid, and the choice is recorded on the customer as billing_model. It is set at creation and cannot be changed afterwards: a customer on the wrong model has to be replaced, not corrected. Omit it and the customer is postpaid.

The mechanic underneath is the same either way. Each customer has a credit limit that caps how much they're allowed to owe at any moment. As usage and subscription fees accumulate, the customer's balance grows toward that limit. When the balance reaches the credit limit, paid service usage is blocked, and subscription fees continue to accrue regardless.

The two models are the two common SaaS billing patterns:

Postpaid (Pay After Use)

• Create the customer with billing_model: "postpaid" (or omit it, since this is the default) and a positive credit_limit (e.g. $500)
• Usage and subscription fees accumulate during the billing period
• An invoice is generated at the end of each period
• The customer pays the invoice by the due date — collection happens through your own payment integration
• When the balance approaches the credit limit, paid services are blocked until payment lands

Prepaid (Pay Before Use)

In a prepaid setup the customer pays for credit upfront in your own application, and PortaAIM enforces "no using what you haven't paid for":

1. Collect a payment from the end user during signup (e.g. $50) using your own payment processor
2. Create the customer in PortaAIM with billing_model: "prepaid", entering the money you collected in the Available Funds field (initial_funds in the API) so they are usable straight away. They are created on a credit limit of 0, so their usage can accrue no debt, whatever credit_limit you send. An update cannot raise it: a credit limit sent for a prepaid customer is rejected with 422.
3. The balance is now -50: a negative balance means the customer is $50 ahead, and Available funds reports the $50 they can consume. The field is required: enter 0 and they are created at zero, which means blocked until you top them up.
4. As the customer uses your service, the balance climbs from -50 toward 0 and available funds fall. Each charge moves the balance up by the amount of the charge.
5. When the balance reaches 0 (the credit limit), paid services are blocked.
6. To let the customer continue, top up again the same way. The balance goes negative again and usage resumes.

In both patterns the underlying mechanic is identical: only the recorded billing_model, the credit_limit value, and the timing of payment collection in your application differ.

No credit limit

If you'd rather never have PortaAIM pause a customer's paid services for an unpaid balance, choose No limit in the Credit Limit field (or omit credit_limit when creating the customer via the API). The customer accrues charges without any cap — useful for trusted or enterprise accounts you bill and collect entirely on your side. This is distinct from a credit limit of 0, which blocks service until the customer is in credit (prepaid).

Customer Balance

The balance represents what the customer currently owes you. Charges (usage and subscription fees) increase the balance; payments and credit adjustments decrease it. The credit limit is the upper bound — when balance reaches credit limit, paid service usage is blocked.

How the balance changes depends on the customer's billing model:

• Postpaid (default): The balance is normally positive. An increase means the customer owes more money, and a decrease means they owe less.
• Prepaid: The balance is normally negative (representing prepaid funds the customer has loaded upfront). An increase (closer to 0) consumes their prepaid funds, and a decrease (more negative) adds prepaid funds.

You can manually adjust the balance:

• Manual charge: Increases the balance (increases a postpaid customer's debt, or decreases a prepaid customer's available funds).
• Payment: Decreases the balance (records a payment received, reducing a postpaid customer's debt or increasing a prepaid customer's available funds).
• Credit: Decreases the balance (applies a goodwill credit, refund/correction, or promotional adjustment, reducing a postpaid customer's debt or increasing a prepaid customer's available funds).

Customer Statistics

Each customer has tracked statistics visible on their detail page:

• Total events: Number of usage events processed
• Revenue: Total billed amount
• Costs: Your vendor costs (for services with Has vendor cost enabled)
• MRR: Monthly recurring revenue from subscriptions
• Usage trends: Period-over-period changes

Per-Customer Data

The customer detail page groups everything about one customer into five tabs:

Tab	What it answers
General	Who the customer is and how the account is set up: contact details, address, external ID, credit limit, billing timezone, when they were created, and the lifecycle actions (suspend, reactivate, terminate)
Quota	How much of the plan's included usage is left in the current period, per service and item, and what happens once it runs out: billed overage, a hard block, or postpaid usage up to the credit limit
Transactions	One ledger of everything that moved the balance: usage charges, subscription fees, payments, credits, refunds, manual charges, and taxes
Usage Events	The raw usage events behind those charges, including attempts that failed or were never charged and so have no ledger row at all
Invoices	Every invoice issued to the customer, with its period, amount due and payment status; download the PDF

Charges and payments are one tab, not two, because they are a single stream of billing records, and splitting them showed the same rows twice. Usage events stay separate for the opposite reason: a rejected or failed request never becomes a charge, so it exists only as an event.

Quota counters are read live from the billing engine, so they reflect real consumption and the plan's real reset cycle rather than a nightly snapshot. Until a customer has generated usage there is nothing counted yet: the card still shows the plan's allowance and a zero, badged as not-yet-counted rather than measured.

For the field-by-field walkthrough of each tab, see the customer detail page guide.