# Credit API preview

Inspect credit balances and manage company allowances in an approved preview environment.

> **Preview**
>
> Confirm credit-management availability and the supported environment with Complyance before using this API for customer or production operations. Credit reads and writes do not use the same environment selection; see below.

## Authentication and environment

Base URL: `https://prod.gets.complyance.io`. Send the ISV workspace’s key in `X-API-Key`; `Authorization: Bearer` with the same key also works.

Send `X-Environment: sandbox` or `X-Environment: production` with every allowance write, including bulk jobs. Without the header, a write applies to production. Any other value is refused with `400` and `CONNECT_INVALID_ENVIRONMENT`. Read endpoints do not filter by this header, so adding `X-Environment: sandbox` to a read does not prove that its result describes sandbox data.

## Operations

| Method | Path, relative to `/v3/connect/credits` | Purpose |
| - | - | - |
| `GET` | `/pool` | Read the workspace credit pool |
| `GET` | `/allowances` | List company allowances |
| `GET` | `/allowances/{companyId}` | Read one company’s current and scheduled state |
| `PUT` | `/allowances/{companyId}/current` | Create or replace the current allowance |
| `PUT` | `/allowances/{companyId}/scheduled` | Create or replace the next allowance |
| `DELETE` | `/allowances/{companyId}/scheduled` | Cancel the scheduled allowance |
| `POST` | `/allowances/{companyId}/pause` | Pause the current allowance |
| `POST` | `/allowances/{companyId}/resume` | Resume the current allowance |
| `POST` | `/allowances/bulk` | Submit a bulk allowance job |
| `GET` | `/allowances/bulk/{jobId}` | Read its row results |
| `GET` | `/transactions` | Read credit activity |
| `POST` | `/exports` | Request a CSV export |
| `GET` | `/exports/{exportId}` | Read export status and download details |

Use the returned 24-character hexadecimal `companyId` for a managed company. Allowance writes require an active company. Single-company state and transaction reads can include retained history for an inactive company.

## Write headers

| Header | Use |
| - | - |
| `Content-Type: application/json` | JSON request bodies |
| `Idempotency-Key` | A unique key for each intended write or export request |
| `If-None-Match: *` | First creation of a current or scheduled allowance |
| `If-Match: "3"` | Replacement, pause, resume or cancellation using the latest resource version |
| `X-Correlation-Id` | Optional identifier linking allowance changes to your application |

Do not send both precondition headers. Reuse the same idempotency key only when retrying the same operation with the same payload. A different intended change needs a new key.

## Allowance body

| Field | Required | Description |
| - | - | - |
| `limit` | Yes | Number, at least zero |
| `periodType` | Yes | `monthly`, `annual` or `custom` |
| `startAt` | Yes | UTC ISO 8601 timestamp, inclusive |
| `endAt` | Yes | UTC ISO 8601 timestamp, exclusive and later than `startAt` |
| `reason` | Yes | Reason for the change, up to 500 characters |
| `planReference` | No | Plan reference, up to 500 characters |
| `metadata` | No | JSON object with your reference information |

A current allowance must already have started and must end in the future. A scheduled allowance must start in the future. Replacing a current allowance keeps its existing start and usage; the new limit cannot be below finalized usage plus reservations.

Pause, resume and scheduled-cancellation requests use a `reason` with the latest version precondition. Changing an allowance does not add credits to the shared pool.

## Bulk request body

Send an `operations` array with 1–500 rows. Every row requires a unique `operationId` (up to 200 characters), `companyId`, `operation`, `expectedVersion` and `reason`.

| Operation | Target | Version |
| - | - | - |
| `replace_current` | Current allowance | `0` for creation; otherwise the latest version |
| `replace_scheduled` | Scheduled allowance | `0` for creation; otherwise the latest version |
| `cancel_scheduled` | Scheduled allowance | Latest version, at least `1` |
| `pause` or `resume` | Current allowance | Latest version, at least `1` |

Replacement rows also require `limit`, `periodType`, `startAt` and `endAt`, with optional `planReference` and `metadata`. Action rows accept only the five common fields. A company may have only one operation for each target within a job. Timestamps must be UTC and end in `Z`. Send the explicit environment and idempotency headers for the job.

## Read parameters

`GET /allowances` accepts `cursor`, `limit` (1–100, default 25), `companyId`, `status`, `countryCode`, `blockReason`, `effectiveFrom` and `effectiveTo`. An effective range must end after it starts.

`GET /transactions` accepts `cursor`, `limit` (1–100), `companyId`, `eventType`, `occurredFrom`, `occurredTo`, `correlationId`, `idempotencyKey`, `requestId`, `transactionId` and `bulkJobId`. Keep filters unchanged while following returned cursors.

```bash title="Read a company’s credit state in an approved preview"
curl "https://prod.gets.complyance.io/v3/connect/credits/allowances/${COMPANY_ID}" \
  --header "X-API-Key: ${COMPLYANCE_API_KEY}" \
  --header 'Accept: application/json'
```

### Transaction event filters

`eventType` accepts `allowance.created`, `allowance.replaced`, `allowance.scheduled`, `allowance.cancelled`, `allowance.activated`, `allowance.expired`, `allowance.superseded`, `allowance.paused`, `allowance.resumed`, `reservation.created`, `reservation.released`, `reservation.needs_reconciliation`, `consumption.finalized`, `consumption.reversed`, `correction.created`, `credit.issued` or `credit.expired`.

## Responses and jobs

Success responses contain `success: true`, `data` and `meta`. Company state exposes the current and scheduled allowances, usage and availability. Preserve the returned version for changes.

The pool response includes `active`, `reserved`, `consumed`, `expired`, `available`, credit `lots`, `asOf` and `warnings`. Company state includes `current`, `scheduled`, `usage`, `reserved`, `available`, `effectiveAvailability`, `blockReason`, `warnings`, `asOf` and `lastChangedAt`. `current` and `scheduled` can be `null`.

`effectiveAvailability` accounts for both company allowance and pool capacity. `blockReason` can be `NO_ACTIVE_ALLOWANCE`, `ALLOWANCE_PAUSED`, `ALLOWANCE_INACTIVE`, `ALLOWANCE_EXHAUSTED` or `POOL_EXHAUSTED`; `null` means no block is reported.

Creating a current allowance returns HTTP `201`; replacing it returns `200`. Bulk submission and export creation return `202`. Credit list responses return an opaque `nextCursor`; stop when it is `null`.

Bulk jobs can be `accepted`, `processing`, `completed`, `completed_with_errors` or `failed`. Inspect every row; successful rows are not undone by another row’s failure.

For an export, send `format: "csv"` with an optional `filters` object using transaction filters except `cursor` and `limit`. HTTP `202` returns an export identifier. Read its status until `completed`, `failed` or `expired`; use `downloadUrl` only while available.

## Errors

Connect errors contain `error.code`, `error.message` and `meta.requestId`. A wrong key returns a JSON `401` with a top-level `code`, and a missing key returns a plain-text `401`, so check the HTTP status and content type before parsing. See [authentication failures](https://docs.complyance.io/api-reference/authentication/#authentication-failures).

| Condition | Action |
| - | - |
| Invalid environment or input | Correct the header, identifier, dates or body |
| `CONNECT_ALLOWANCE_WRITE_PRECONDITION_FAILED` | Read the latest resource version and review the intended change |
| Idempotency conflict | Do not reuse one key for different payloads |
| `CONNECT_CREDIT_BULK_JOB_NOT_FOUND` | Check the job identifier and workspace |

The credit API does not expose a credit-purchase or manual debit/refund operation. See [credit concepts](https://docs.complyance.io/partner-platform/isv/credits/) before implementing changes.

Source: https://docs.complyance.io/api-reference/connect/credits/