Credit API preview

Authentication and environment

Base URL: https://prod.gets.complyance.io. Send X-API-Key for the ISV workspace.

Allowance writes require an explicit X-Environment: sandbox or X-Environment: production; omission defaults to production. 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

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

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

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.

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.

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. Authentication failures can return a non-JSON 401, so check the HTTP status and content type before parsing.

The credit API does not expose a credit-purchase or manual debit/refund operation. See credit concepts before implementing changes.