> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# ProAbono plugin

> Subscription billing API for managing customers, offers, subscriptions, usages, balance lines and invoices.

Use **ProAbono** through Corsair: one client, typed API calls.

ProAbono bills recurring subscriptions. Every account is served from its own host, `api-<account>.proabono.com`, so the plugin needs your account number as well as the two keys from Integration, API in the back office: the agent key and the API key. All three are stored with the connection. They travel as HTTP Basic, with the agent key as the username and the API key as the password.

What to know before you bill:

* **The account number.** Store `account` as `42` (or paste the endpoint, `https://api-42.proabono.com`) to reach `api-42.proabono.com`; an `account` plugin option overrides it. Without it there is no host to call, so the plugin asks for the connection rather than guessing.
* **Two steps to a subscription.** A subscription is created from an offer reference and a customer reference, and it only starts billing once the customer is billable. `TryStart: false` creates it without starting, so it can be customised first; `start` then begins it.
* **Amounts are integer cents.** Every amount, such as `AmountRecurrence` and an invoice's `AmountTotal`, is in the currency's minor unit, so 9900 is 99.00.
* **Usages accumulate.** `usages.increment` adds to a feature's usage, and a negative increment subtracts, which is how a reversed action is recorded. Every usage change needs a `DateStamp`; ProAbono records two changes with the same timestamp once. `usages.update` sends up to 50 rows at once.
* **Lists are paginated.** List answers carry `Page`, `SizePage`, `Count` and `TotalItems` beside the rows; pass `Page` for the next page.
* **A 204 is not an error.** ProAbono answers a read that finds nothing with 204 and an empty body. The plugin turns that into an empty result rather than failing the parse.
* **A 422 lists the bad fields.** It carries one entry per field; the thrown `ApiError` keeps that list on `body`.
* **Nothing to check a subscription with.** The docs warn against using `subscriptions.get` to decide whether a user is a subscriber, and point at their own method instead.
* **Webhooks.** ProAbono notifies through its portal rather than by webhook deliveries, so this plugin receives none.

**What you get:**

* 27 typed API operations

## Setup

**1. Install**

```bash npm theme={null}
npm install corsair @corsair-dev/proabono better-sqlite3
npm install --save-dev @types/better-sqlite3
```

```bash yarn theme={null}
yarn add corsair @corsair-dev/proabono better-sqlite3
yarn add --dev @types/better-sqlite3
```

```bash pnpm theme={null}
pnpm install corsair @corsair-dev/proabono better-sqlite3
pnpm install --save-dev @types/better-sqlite3
```

```bash bun theme={null}
bun add corsair @corsair-dev/proabono better-sqlite3
bun add --dev @types/better-sqlite3
```

**2. Add the plugin**

```ts corsair.ts theme={null}
import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { proabono } from '@corsair-dev/proabono';

export const corsair = createCorsair({
	plugins: [
		proabono(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});
```

With `multiTenancy: true`, scope calls with `corsair.withTenant(id)`. See [Quick start](https://docs.corsair.dev/quick-start.md) for KEK + Hub keys, and [Multi-tenancy](https://docs.corsair.dev/concepts/multi-tenancy.md) for account isolation.

**3. Choose authentication**

> [tab] API Key (Recommended)
>
> Store the ProAbono API key before the first call: `pnpm corsair setup --plugin=proabono --tenant=acme api_key=<your-key>` (leave out `--tenant` without `multiTenancy`), or pass it as `key` in the plugin options. With Hub, each tenant enters their own key on the connect page. See [API key auth](https://docs.corsair.dev/concepts/api-key).
>
> ```ts theme={null}
> proabono()
> ```
>
> More: [API Key](https://docs.corsair.dev/concepts/api-key)

**4. Connect a tenant**

Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see [Connect / OAuth](https://docs.corsair.dev/management/connect).

```ts theme={null}
const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'proabono',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl
```

## Example API calls

**List the offers in your account**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.proabono.api.offers.list({});
```

**Create a customer with your own reference**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.proabono.api.customers.create({ ReferenceCustomer: 'cust-42', Name: 'Jane Smith', Email: 'jane@example.com' });
```

See the full list on the [API](https://docs.corsair.dev/plugins/proabono/api.md) page.

## What's next

> [card] [API reference](https://docs.corsair.dev/plugins/proabono/api.md)
>
> Every `proabono.api.*` operation with input and output types.

> [card] [Connect / OAuth](https://docs.corsair.dev/management/connect)
>
> createLink, Hub delivery, and tenant connect flows.

> [card] [Use with agents](https://docs.corsair.dev/mcp-adapters/mcp-adapters)
>
> Expose this plugin's operations as MCP tools.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.