# Credits

Transactional credits for Bijection background jobs: reserve, complete, release, refund, and reconcile.

- Package: @bijectionhq/credits
- Category: Payments
- Status: Reference
- License: Apache-2.0
- Bijection source (repository access required): https://github.com/bijectionhq/credits/tree/e5da372a6fb082cdef168d7c82361a6e0e2c7330/packages/convex-credits
- Upstream: https://github.com/clipinfit/convex-credits/tree/7813127915f7812079b3cc6ec913fd5027b417d9/packages/convex-credits
- Documentation: https://docs.bijection.com/components/using
- Directory: https://bijection.com/components/credits

## Get the source

Bijection repository access is required. Request access at https://bijection.com/contact.

```sh
git clone https://github.com/bijectionhq/credits.git
cd credits
git checkout e5da372a6fb082cdef168d7c82361a6e0e2c7330
cd packages/convex-credits
```

## Before using this component

Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute.

## Upstream package documentation

Recorded 2026-10-23. This describes @clipin/convex-credits; check the Bijection adaptation separately.

Convex Credits manages credit balances and charges for Convex apps. Grant gifts and rewards, reserve credits before work starts, and complete or release charges when work ends. The component also supports refunds, atomic transfers, safe retries with stable operation keys, and an auditable history of balance changes. Maintained by CLIPIN.

### Use cases

- Grant welcome credits, gifts, and referral rewards.
- Credit an account after the host app verifies a purchase.
- Reserve credits for AI generations and other background jobs, then complete successful charges or release failed reservations.
- Refund all or part of a completed charge.
- Transfer credits between accounts in one transaction.
- Audit balance changes and import an existing credit ledger.

### How it works

Mount the component in your Convex app and create a Credits client in the host backend. The host validates the user and chooses prices.

Use grant() for gifts, verified purchases, and rewards. reserve() debits the available balance and creates a pending charge. complete() finalizes that charge without another credit movement. release() returns a pending reservation once. refund() returns all or part of a completed charge, capped at the unrefunded amount.

Supply a stable operation key for every mutation. Identical retries return the stored result; changed arguments with the same key fail. Transfers update both accounts in one transaction.

Paginated history records nonzero balance movements. Import helpers preserve source timestamps and pending charges, then verify balances and counts before activating the account. See https://convex-credits.vercel.app/docs for setup and examples.

### Upstream README

Credit balances and charges for background jobs, maintained by CLIPIN.

Stable package: [`@clipin/convex-credits@1.0.1`](https://www.npmjs.com/package/@clipin/convex-credits).

Grant gifts and rewards. Reserve credits before work starts. Complete a successful charge without another debit, or release a failed reservation once. Refund completed charges and transfer credits between accounts atomically.

```sh
npm install @clipin/convex-credits convex
```

Mount the component in `convex/convex.config.ts`:

```ts
import { defineApp } from "convex/server";
import credits from "@clipin/convex-credits/convex.config.js";

const app = defineApp();
app.use(credits);
export default app;
```

Create a client in your host backend:

```ts
import { Credits } from "@clipin/convex-credits";
import { components } from "./_generated/api";

const credits = new Credits(components.credits);

// Inside an authorized host mutation:
await credits.grant(ctx, {
  owner: accountId,
  amount: 20,
  key: JSON.stringify(["gift", requestId]),
  reason: "Welcome gift",
});
```

The host controls authentication, grant permissions, prices, and payment verification. Call the component from a host mutation to commit both sets of database writes together.

Supply a stable operation key for each write. An identical retry returns its original result. Reusing a key with different arguments fails. Amounts are positive safe integers, and available balances cannot become negative.

History contains nonzero balance movements. Completion updates charge state without adding a movement. History uses cursor pagination through `convex-helpers`, which supports component queries. Import helpers preserve source timestamps and pending charges, then verify balances and counts before account activation.

[Documentation](https://convex-credits.vercel.app/docs) · [Example backend](https://github.com/clipinfit/convex-credits/tree/main/packages/example-backend) · [Interactive demo](https://convex-credits.vercel.app)