GET /billing/usage

L’endpoint billing/usage te retourne la consommation du mois calendaire courant pour un tenant donné. C’est ce que le dashboard utilise pour afficher la jauge “X / Y tickets utilisés” et estimer la prochaine facture.

GET https://actero.fr/api/billing/usage?client_id=<id>

Authentification

Authorization: Bearer <jwt> (session Supabase). Une clé ak_… (publique, celle de la bulle) ou un jeton développeur mcp_pat_… (réservé au serveur MCP) n’ouvre pas cette route. L’utilisateur doit être :

Admin Actero (équipe interne, accès à tous les tenants), ou
Membre du client_id (présent dans la table client_users).

Sinon → 403 Acces refuse.

Query params

string

required

ULID du tenant. Si absent → 400 Missing client_id.

Headers

Header	Valeur	Requis
`Authorization`	`Bearer <token>`	Oui

Response — `200 OK`

{
  "plan": "pro",
  "period": "2026-04",
  "tickets_used": 1247,
  "tickets_limit": 5000,
  "overage_tickets": 0,
  "overage_cost": 0,
  "quota_reached": false,
  "credits_balance": 0,
  "trial_ends_at": null,
  "next_billing_date": "2026-05-01"
}

enum

free, starter, pro, enterprise. Lu depuis clients.plan.

string

Mois calendaire au format YYYY-MM. Tous les compteurs ci-dessous sont strictement sur ce mois — ils repassent à 0 le 1er du mois suivant.

integer

Nombre de tickets traités par l’agent ce mois (passage Brain + Executor, peu importe le résultat).

integer

Quota du plan. Vaut -1 si illimité (Enterprise).

integer

Déprécié — toujours 0. Aucun plan ne facture de dépassement (plafond strict).

number

Déprécié — toujours 0.

boolean

true quand le quota mensuel est atteint : l’agent est en pause jusqu’à l’achat de crédits ou un upgrade.

integer

Crédits disponibles. Consommés automatiquement (1 crédit = 1 ticket) au-delà du quota.

string|null

ISO timestamp de fin de période d’essai. null si le tenant n’est pas en trial.

string

Date approximative du prochain prélèvement (1er du mois suivant). Format YYYY-MM-DD. Le prélèvement est opéré par Shopify pour les boutiques ayant installé Actero depuis l’App Store, et par notre prestataire de paiement pour les inscriptions directes.

Response — autres cas

`400 Bad Request`

{ "error": "Missing client_id" }

`401 Unauthorized`

{ "error": "Non autorise." }

`403 Forbidden`

{ "error": "Acces refuse." }

`404 Not Found`

{ "error": "Client introuvable." }

`503 Service Unavailable`

{ "error": "Indisponible." }

Les droits d’accès n’ont pas pu être vérifiés. Réessaie un peu plus tard.

`405 Method Not Allowed`

Cet endpoint accepte uniquement GET. Tout autre verbe renvoie 405.

`500 Internal Server Error`

{ "error": "Erreur interne." }

Dépassement de quota

Plan	Tickets inclus	Au-delà du quota
Free	50	Bloqué (crédits/upgrade)
Starter	1 000	Bloqué (crédits/upgrade)
Pro	5 000	Bloqué (crédits/upgrade)
Enterprise	Illimité	—

Les identifiants de tarif du prestataire de paiement ne sont pas exposés via l’API publique — ils restent server-side. Aucun dépassement n’est facturé : surveille quota_reached et credits_balance pour savoir si l’agent est en pause.

Exemples

curl "https://actero.fr/api/billing/usage?client_id=$ACTERO_CLIENT_ID" \
  -H "Authorization: Bearer $ACTERO_SESSION_TOKEN"

const url = new URL('https://actero.fr/api/billing/usage')
url.searchParams.set('client_id', process.env.ACTERO_CLIENT_ID)

const res = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.ACTERO_SESSION_TOKEN}` },
})
const usage = await res.json()

const pct = (usage.tickets_used / usage.tickets_limit) * 100
console.log(`${usage.tickets_used}/${usage.tickets_limit} tickets (${pct.toFixed(1)}%)`)

if (usage.quota_reached) {
  console.warn(`Quota atteint — agent en pause. Crédits restants : ${usage.credits_balance}`)
}

import os, requests

res = requests.get(
    "https://actero.fr/api/billing/usage",
    params={"client_id": os.environ["ACTERO_CLIENT_ID"]},
    headers={"Authorization": f"Bearer {os.environ['ACTERO_SESSION_TOKEN']}"},
)
usage = res.json()

if usage["tickets_limit"] != -1:
    pct = usage["tickets_used"] / usage["tickets_limit"] * 100
    print(f"{usage['tickets_used']}/{usage['tickets_limit']} tickets ({pct:.1f}%)")

Suivre la consommation sans poller

Il n’existe pas d’événement de webhook pour le quota : les webhooks sortants n’émettent que ticket.escalated, ticket.resolved et conversation.created. Pour être prévenu avant le plafond, active l’alerte de quota dans Paramètres → Notifications : Actero t’écrit par e-mail, et sur Slack si l’intégration est connectée, à 80 % puis à 100 % du quota mensuel. Si tu préfères suivre le quota depuis ton propre outil, lis quota_reached et credits_balance : une lecture par heure suffit dans la quasi-totalité des cas.

Rate limit

Cet endpoint n’a pas de limite de débit propre : il est protégé par l’authentification. Une lecture par heure suffit dans la quasi-totalité des cas.

Référence

Endpoints

GET /billing/usage

Authentification

Query params

Headers

Response — `200 OK`

Response — autres cas

`400 Bad Request`

`401 Unauthorized`

`403 Forbidden`

`404 Not Found`

`503 Service Unavailable`

`405 Method Not Allowed`

`500 Internal Server Error`

Dépassement de quota

Exemples

Suivre la consommation sans poller

Rate limit

​Authentification

​Query params

​Headers

​Response — 200 OK

​Response — autres cas

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​503 Service Unavailable

​405 Method Not Allowed

​500 Internal Server Error

​Dépassement de quota

​Exemples

​Suivre la consommation sans poller

​Rate limit

Authentification

Query params

Headers

Response — `200 OK`

Response — autres cas

`400 Bad Request`

`401 Unauthorized`

`403 Forbidden`

`404 Not Found`

`503 Service Unavailable`

`405 Method Not Allowed`

`500 Internal Server Error`

Dépassement de quota

Exemples

Suivre la consommation sans poller

Rate limit