Consumption and Billing

The consumption and billing APIs let you monitor how your workspace uses oHallo and manage your subscription. Conversation statistics show volume, resolution rates, and breakdowns by channel and intent. Agent breakdowns show which agents are handling the workload. Billing endpoints expose your current plan, invoices, and a self-service checkout flow powered by Stripe.

Conversation statistics

Retrieve conversation volume and resolution metrics for a workspace.

Required scope: conversations:read

curl "https://api.ohallo.eu/api/workspaces/a1b2c3d4-e5f6-7890-abcd-ef1234567890/consumption/conversation-stats?period=current" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Query parameters:

Parameter	Type	Required	Description
period	string	No	Predefined period: current, previous, last_90d (default current)
from	string	No	Start of custom range in ISO 8601 format (overrides period)
to	string	No	End of custom range in ISO 8601 format (overrides period)

The current period covers the current billing cycle. The previous period covers the immediately preceding billing cycle.

Response:

{
  "total": 482,
  "resolved": 439,
  "byResolution": {
    "ai_resolved": 387,
    "human_resolved": 52,
    "abandoned": 28,
    "open": 15
  },
  "byChannel": {
    "email": 310,
    "chat": 142,
    "whatsapp": 30
  },
  "byIntent": [
    { "intent": "order_status", "count": 156 },
    { "intent": "return_request", "count": 89 },
    { "intent": "product_question", "count": 74 },
    { "intent": "delivery_issue", "count": 62 },
    { "intent": "billing_inquiry", "count": 48 },
    { "intent": "other", "count": 53 }
  ],
  "periodStart": "2026-03-01T00:00:00.000Z",
  "periodEnd": "2026-03-31T23:59:59.999Z"
}

Agent breakdown

Retrieve a breakdown of agent activity for a workspace, split into custom (admin-defined) and system agents.

Required scope: conversations:read

curl "https://api.ohallo.eu/api/workspaces/a1b2c3d4-e5f6-7890-abcd-ef1234567890/consumption/agent-breakdown?period=current" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Query parameters:

Parameter	Type	Required	Description
period	string	No	Predefined period: current, previous, last_90d (default current)
from	string	No	Start of custom range in ISO 8601 format (overrides period)
to	string	No	End of custom range in ISO 8601 format (overrides period)

Response:

{
  "custom": [
    { "agentName": "Order Lookup Agent", "count": 312 },
    { "agentName": "Returns Agent", "count": 145 },
    { "agentName": "Meeting Booking Agent", "count": 67 }
  ],
  "system": [
    { "agentName": "Conversation Orchestrator", "count": 482 },
    { "agentName": "Message Composer", "count": 482 },
    { "agentName": "Reply Validator", "count": 478 },
    { "agentName": "Learning Extractor", "count": 439 }
  ],
  "customTotal": 524,
  "systemTotal": 1881,
  "periodStart": "2026-03-01T00:00:00.000Z",
  "periodEnd": "2026-03-31T23:59:59.999Z"
}

Get subscription

Retrieve the current subscription details for your account.

Required scope: billing:read

curl "https://api.ohallo.eu/api/subscription" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Response:

{
  "tier": "growth",
  "cadence": "monthly",
  "status": "active",
  "currentPeriodStart": "2026-03-01T00:00:00.000Z",
  "currentPeriodEnd": "2026-03-31T23:59:59.999Z",
  "conversationLimit": 1000,
  "agentRunLimit": 5000
}

Field	Description
tier	Current plan: free, starter, growth, scale, or enterprise
cadence	Billing frequency: monthly or annual
status	Subscription status: active, past_due, canceled, or trialing
currentPeriodStart	Start of the current billing period in ISO 8601 format
currentPeriodEnd	End of the current billing period in ISO 8601 format
conversationLimit	Maximum conversations included in the plan for this billing period
agentRunLimit	Maximum agent runs included in the plan for this billing period

Create checkout session

Create a Stripe checkout session to subscribe to a plan or change your current plan.

Caution

Dashboard-only. This endpoint produces a Stripe checkout URL that must be opened in a browser to complete payment. It is currently accessible only via a dashboard session (Kinde JWT); programmatic API-key access is intentionally disabled because a headless integration cannot follow the redirect. Use the dashboard at https://app.ohallo.eu/settings/billing to start a checkout flow.

List invoices

Retrieve all invoices for your account, ordered by date descending.

Required scope: billing:read

curl "https://api.ohallo.eu/api/invoices" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Response:

{
  "items": [
    {
      "id": "11223344-5566-4788-99aa-bbccddeeff00",
      "periodStart": "2026-02-01T00:00:00.000Z",
      "periodEnd": "2026-02-28T23:59:59.999Z",
      "status": "paid",
      "subtotal": 14900,
      "tax": 3129,
      "total": 18029,
      "currency": "eur",
      "stripeInvoiceUrl": "https://invoice.stripe.com/i/acct_1234/inv_5678",
      "createdAt": "2026-03-01T00:00:00.000Z"
    },
    {
      "id": "aabbccdd-eeff-4788-9233-445566778899",
      "periodStart": "2026-01-01T00:00:00.000Z",
      "periodEnd": "2026-01-31T23:59:59.999Z",
      "status": "paid",
      "subtotal": 14900,
      "tax": 3129,
      "total": 18029,
      "currency": "eur",
      "stripeInvoiceUrl": "https://invoice.stripe.com/i/acct_1234/inv_9012",
      "createdAt": "2026-02-01T00:00:00.000Z"
    }
  ],
  "total": 2
}

All monetary amounts are in the smallest currency unit (cents for EUR). For example, 14900 represents EUR 149.00.

Get billing summary

Retrieve a summary of the current billing period, including plan details, usage against limits, and projected charges.

Required scope: billing:read

curl "https://api.ohallo.eu/api/billing-summary" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Response:

{
  "currentPlan": {
    "tier": "growth",
    "cadence": "monthly",
    "basePriceMonthly": 14900
  },
  "usage": {
    "conversations": 482,
    "conversationLimit": 1000,
    "agentRuns": 2405,
    "agentRunLimit": 5000,
    "periodStart": "2026-03-01T00:00:00.000Z",
    "periodEnd": "2026-03-31T23:59:59.999Z"
  },
  "projectedCharges": {
    "base": 14900,
    "overage": 0,
    "tax": 3129,
    "total": 18029,
    "currency": "eur"
  }
}

The projectedCharges object estimates what the invoice will be at the end of the current period. If usage exceeds plan limits, the overage field reflects per-unit charges for conversations and agent runs above the included amounts.

Get pricing catalog

Retrieve the available pricing tiers and per-unit rates. This endpoint is useful for displaying plan options in a self-service upgrade flow.

Required scope: billing:read

curl "https://api.ohallo.eu/api/pricing/catalog" \
  -H "Authorization: Bearer sf_live_v1_a3Bx9kLmP2qR7wYz4nDfGhJkQpStUvWx"

Response:

{
  "tiers": [
    {
      "tier": "free",
      "displayName": "Free",
      "monthlyPrice": 0,
      "annualPrice": 0,
      "conversationsIncluded": 50,
      "agentRunsIncluded": 250,
      "features": ["1 workspace", "1 channel", "Community support"]
    },
    {
      "tier": "starter",
      "displayName": "Starter",
      "monthlyPrice": 4900,
      "annualPrice": 47000,
      "conversationsIncluded": 300,
      "agentRunsIncluded": 1500,
      "features": ["3 workspaces", "3 channels", "Email support"]
    },
    {
      "tier": "growth",
      "displayName": "Growth",
      "monthlyPrice": 14900,
      "annualPrice": 143000,
      "conversationsIncluded": 1000,
      "agentRunsIncluded": 5000,
      "features": ["10 workspaces", "Unlimited channels", "Priority support", "Custom agents"]
    },
    {
      "tier": "scale",
      "displayName": "Scale",
      "monthlyPrice": 39900,
      "annualPrice": 383000,
      "conversationsIncluded": 5000,
      "agentRunsIncluded": 25000,
      "features": ["Unlimited workspaces", "Unlimited channels", "Dedicated support", "Custom agents", "SLA guarantee"]
    },
    {
      "tier": "enterprise",
      "displayName": "Enterprise",
      "monthlyPrice": null,
      "annualPrice": null,
      "conversationsIncluded": null,
      "agentRunsIncluded": null,
      "features": ["Custom limits", "Dedicated infrastructure", "24/7 support", "Custom integrations", "On-premises option"]
    }
  ],
  "overageRates": {
    "conversationOverage": 15,
    "agentRunOverage": 3,
    "currency": "eur"
  }
}

All prices are in the smallest currency unit (cents for EUR). The enterprise tier has null prices because pricing is negotiated per customer. Overage rates apply when usage exceeds the included amounts for the active tier: conversationOverage is the per-conversation charge and agentRunOverage is the per-agent-run charge.