Credits & billing

Constaia is pay-as-you-go with credits. There is no subscription: you buy packs when you need them and, meanwhile, you get 150 free credits every month. Prices and comparison at /en/pricing.

What each operation costsCopy Anchor Link

The rule is credits = ceil(pages / 2), with a minimum of 1. A Spanish DNI with both sides in one file or in a 2-page PDF costs 1 credit.

In a batch, each document is counted separately with the same rule. Every analysis shows what it cost in usage:

"usage": { "credits": 1, "pages": 2 }

What is not chargedCopy Anchor Link

• Test mode. ck_test_ keys don't use credits (usage.credits: 0).
• Failures on our side. An analysis that ends with status: "failed" (for example processing_failed) is not charged.
• Quality rejections before OCR. If the image is rejected before it is read, it is not charged.
• Retries with the same Idempotency-Key within 24 h: they return the stored response without charging twice.
• Exports. Already included.

An analysis that ends as invalid or review is charged: Constaia did the work and gave you an answer.

Reservation and captureCopy Anchor Link

When an analysis starts, Constaia reserves the credits it will cost. When it finishes:

• if it completes, the reservation is captured;
• if it fails on our side or is rejected for quality before OCR, the reservation is released and returns to your balance.

While analyses are in progress you will see credits in credits_reserved. If you don't have enough balance to reserve, the request fails with a 402 insufficient_credits and nothing is analysed.

In live mode, a batch checks when it is created that you have at least 1 credit per document; if not, the whole batch is rejected with 402. Each document then costs what its pages require.

Free planCopy Anchor Link

• 150 credits a month, renewed on the 1st of each month (UTC). Unused credits don't roll over.
• Spending them in live mode requires a verified email.
• free_tier_resets_at in the balance tells you when they renew.

PacksCopy Anchor Link

Packs are one-off payments, no subscription. Prices exclude VAT:

• Packs expire 12 months after purchase.
• Consumption order: first this month's free plan, then packs from oldest to newest (FIFO).
• Enterprise: contract, DPA, SLA and your own limits. Details at /en/pricing.

Buy packs under Billing in app.constaia.com. Payment goes through Stripe Checkout and the credits are added to your balance as soon as it is confirmed.

VAT and invoicesCopy Anchor Link

• Prices exclude VAT. Stripe Tax calculates it at checkout based on your tax details.
• Every purchase generates an invoice, which you will find under Billing in the dashboard.
• Fill in your company's tax details before your first purchase so they appear on the invoice.

Checking your balanceCopy Anchor Link

GET /v1/balance returns:

{
  "object": "balance",
  "credits_available": 4210,
  "credits_reserved": 3,
  "free_tier_remaining": 12,
  "credits_spendable": 4222,
  "free_tier_resets_at": "2026-10-01T00:00:00.000Z"
}

What you can spend right now is credits_spendable (credits_available + free_tier_remaining).

curl https://api.constaia.com/v1/balance \
  -H "Authorization: Bearer $CONSTAIA_API_KEY"

Checking usageCopy Anchor Link

GET /v1/usage?from=YYYY-MM-DD&to=YYYY-MM-DD aggregates usage by day and document type (by default, the last 30 days of the key's mode):

curl "https://api.constaia.com/v1/usage?from=2026-09-01&to=2026-09-30" \
  -H "Authorization: Bearer $CONSTAIA_API_KEY"

{
  "object": "usage",
  "from": "2026-09-01",
  "to": "2026-09-30",
  "livemode": true,
  "data": [
    { "date": "2026-09-29", "type": "es_dni", "kind": "analysis", "livemode": true, "count": 42, "pages": 84, "credits": 42 }
  ],
  "totals": { "count": 42, "pages": 84, "credits": 42 }
}

To split costs between customers or departments, send metadata with each analysis (for example { "club_id": "42" }) and filter with GET /v1/analyses?metadata[club_id]=42. More in Balance & usage.

Low-credit alertCopy Anchor Link

In the dashboard settings you set an alert threshold (50 credits by default). When, after a charged live analysis, your spendable balance drops below it, Constaia:

• sends the credits.low webhook to subscribed endpoints, and
• emails the account's owners and admins.

{
  "type": "credits.low",
  "created_at": "2026-09-29T10:00:00Z",
  "data": { "object": "balance", "credits_available": 0, "free_tier_remaining": 48, "credits_spendable": 48, "threshold": 50 }
}

The fields mean the same as in GET /v1/balance: credits_available is pack credits only and credits_spendable is what you can spend (free plan plus packs); the alert fires when credits_spendable drops below the threshold. It is sent once until you top up with a pack or the free plan renews. Subscribe from Webhooks.

Handling 402 errorsCopy Anchor Link

Without enough balance, the API responds:

{
  "error": {
    "type": "insufficient_credits",
    "code": "insufficient_credits",
    "message": "…",
    "request_id": "req_…"
  }
}

Don't retry it in a loop: it won't fix itself. Queue the work, alert your team and resume when there is balance.

import { Constaia, InsufficientCreditsError } from "@constaia/sdk";
import { fromPath } from "@constaia/sdk/node";

const constaia = new Constaia();

try {
  const analysis = await constaia.analyze(await fromPath("./dni.jpg"), { expect: "es_dni" });
  console.log(analysis.verdict?.status);
} catch (err) {
  if (err instanceof InsufficientCreditsError) {
    // Keep the document for later and alert whoever buys credits.
    console.error(`Out of credits (request ${err.requestId})`);
  } else {
    throw err;
  }
}

Monthly spend capCopy Anchor Link

You can set a monthly credit cap for the account: if a live-mode analysis would exceed it, it is rejected with 402 monthly_cap_reached and not charged, and owners and admins get an email at 80 % and 100 %. Details in Rate limits.

Next stepsCopy Anchor Link