canonical: https://jentic.com/apis/api.docs.paigo.tech/paigo

# Docs Paigo Tech Paigo API

Jentic publishes the only available OpenAPI specification for Paigo API, keeping it validated and agent-ready. Paigo is a usage-based billing platform: it lets product teams define dimensions and offerings, ingest measured usage, generate invoices, and manage customers (including parent-child hierarchies) and refunds. The API also exposes webhook and settings endpoints so integrations can keep downstream systems in sync. Authentication uses OAuth 2.0 client-credentials against auth.paigo.tech to mint a bearer JWT, which is then attached to every API call.

## For AI agents

Define usage dimensions and offerings, ingest usage events, manage customers, and generate invoices through Paigo's usage-based billing API. OAuth 2.0 client-credentials.

## Scope

Does not handle payment processing, tax calculation, or subscription dunning - use for usage ingestion, dimension and offering definition, customer hierarchies, and invoice and refund issuance only.

## Capabilities

- Define metered dimensions and pricing offerings via /dimensions and /offerings
- Ingest measured usage events via POST /usage and per-customer measurements
- Manage customers and parent-child customer hierarchies via `/customers/{customerId}/children/{childId}`
- Issue and inspect invoices, including refund creation via `/customers/{customerId}/refunds`
- Configure platform settings and webhook endpoints for downstream systems
- Pull usage and invoice data for downstream billing reconciliation

## Use cases

### Usage-Based Billing for an API Product

Wire a usage-based pricing model into an API product by defining a dimension (for example api_calls), creating an offering with tiered pricing, and ingesting usage events as customers consume the API. POST /usage carries the metered events; /offerings and /dimensions hold the pricing definition. Paigo aggregates usage and issues invoices automatically.

Example prompt: Create a dimension named 'api_calls', attach it to a tiered offering with $0.001 per call after a 10k free tier, and POST /usage daily for each customer

### Parent-Child Customer Hierarchies

Bill an enterprise account where a parent organisation rolls up usage from multiple child entities. POST `/customers/{customerId}/children/{childId}` attaches a child to a parent so usage flows up the hierarchy and a single invoice covers the group. PUT and DELETE on the same path adjust the relationship as the customer's structure changes.

Example prompt: Attach customer 12345 (a subsidiary) as a child of customer 1000 (the parent) and confirm the next invoice rolls usage up to the parent

### Refund and Invoice Adjustment

Issue a refund when a customer disputes a charge or service credit is owed. POST `/customers/{customerId}/refunds` creates a refund tied to the customer's invoice. Combined with read endpoints under /invoices, support agents can resolve a dispute, apply the refund, and confirm the adjustment is reflected on the next statement - all without leaving their tooling.

Example prompt: Read the most recent /invoices for customer 12345, then POST `/customers/12345/refunds` for $49 with reason 'service credit'

### AI Agent Billing Operations

An AI agent uses Paigo via Jentic to answer billing questions and run routine ops. The agent searches Jentic by intent, loads the right schema, and calls Paigo through Jentic so the OAuth flow is handled centrally rather than in agent code. Useful for support assistants that need to look up invoices, ingest a missed usage batch, or apply a service credit.

Example prompt: Search Jentic for 'look up Paigo invoice', load the schema, and report the most recent invoice total for a named customer

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/usage` | Ingest usage events |
| POST | `/dimensions` | Create a metered dimension |
| POST | `/offerings` | Create a pricing offering |
| POST | `/customers` | Create a customer |
| POST | `/customers/{customerId}/children/{childId}` | Attach a child customer to a parent |
| POST | `/customers/{customerId}/refunds` | Issue a refund for a customer |

## Key resources

- **Customers** — Customer records and parent-child hierarchies
- **Dimensions** — Metered dimensions used to record usage
- **Offerings** — Pricing offerings combining dimensions and tiers
- **Measurements and Usage** — Ingested usage events tied to customers and dimensions
- **Invoices** — Invoices and refunds generated against customer usage
- **Webhooks and Settings** — Outbound webhooks and platform configuration

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 41 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 42 / 100
  - Developer Experience & Jentic Compatibility: 71 / 100
  - AI-Readiness & Agent Experience: 18 / 100
  - Agent Usability: 94 / 100
  - Security: 85 / 100
  - AI Discoverability: 100 / 100
- **View full report:** https://jentic.com/apis/api.docs.paigo.tech/paigo/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Paigo by hand means implementing its OAuth2 bearer flow and hand-coding calls to usage ingestion, offering, and customer endpoints yourself. Through Jentic you install once, import the Paigo API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Paigo puts the customer id in the URL path (`/customers/{customerId}/children/{childId}` and `/customers/{customerId}/refunds`), so a rule can pin your agent to one customer for those nested operations. You choose the operations it may call, so a destructive one like issuing a refund is not included unless you add it.
- **Credential handling:** Your Paigo token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'record usage for a customer' or 'define a billing dimension', and Jentic returns the matching Paigo operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **ComplyAdvantage API** — ComplyAdvantage handles AML screening that often runs alongside billing onboarding for B2B SaaS.
- **Xero Accounting API** — Xero is a typical accounting destination for Paigo-issued invoices.
- **HubSpot Account Info API** — HubSpot CRM holds the customer record that maps to a Paigo customer entity.

## FAQ

### Why is there no official OpenAPI spec for Paigo API?

Paigo documents the API on docs.paigo.tech but does not publish a downloadable OpenAPI specification suitable for code generation. Jentic generates and maintains this spec so that AI agents and developers can call Paigo API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Paigo API use?

Paigo uses OAuth 2.0 client-credentials. You POST your `client_id` and `client_secret` to `https://auth.paigo.tech/oauth/token` with the audience set to the Paigo API gateway, receive a JWT bearer token valid for 24 hours, and attach it as `Authorization: Bearer <token>` on every API call. Jentic handles the token exchange and refresh so agents never see the client secret.

### Can I ingest usage events with the Paigo API?

Yes - POST /usage is the primary ingestion endpoint. You send usage events tied to a customer and a dimension (defined under /dimensions). Paigo aggregates the events according to the offering's pricing rules and emits invoices on the configured cadence. For backfills, send historical events in batches rather than per-event.

### What are the rate limits for the Paigo API?

Paigo does not publish fixed rate limits in the public spec. Treat /usage as the high-volume endpoint and batch events into single calls where possible. If you receive a 429 response, back off and retry - Paigo returns a Retry-After header on throttled responses.

### How do I create a usage-based pricing model through Jentic?

Run `pip install jentic`, search for 'create a Paigo dimension', then for 'create a Paigo offering'. Create the dimension first (for example 'api_calls'), then the offering that prices it. Finally, search for 'ingest Paigo usage events' and call POST /usage as customers consume the metered resource. The OAuth token is handled by Jentic on every call.

### Can I model parent-child customer relationships?

Yes - POST `/customers/{customerId}/children/{childId}` attaches a child to a parent so usage rolls up the hierarchy. PUT updates the relationship metadata and DELETE detaches the child. This is the right primitive when an enterprise customer wants a single invoice that covers multiple subsidiaries.

### Can I limit what my agent is allowed to do with the Paigo API?

Yes. Because you run Jentic One yourself, you decide which Paigo operations your agent may call, so a destructive one like issuing a refund via POST `/customers/{customerId}/refunds` is left out unless you add it. Paigo carries the customer id in the URL path, so for nested operations such as POST `/customers/{customerId}/children/{childId}` and the refund endpoint you can pin your agent to a single customer. The OAuth token stays with your own instance and is injected at execution, so the agent only ever exercises the operations and credentials your rules permit.