Skip to main content

Billing

relay accounts on the prepaid credit billing model purchase screening credits in advance. Each completed screening report draws down the account's credit balance. This section explains how the prepaid model gates report access over the REST API, the response you receive when a balance is exhausted, and how to restore service.

For a condensed engineering reference, see the Billing Technical Addendum. SDK integrators should also read the SDK Billing guide. For a plain-language overview, see Billing: What's Changing.

Who this applies to

This applies only to accounts on the prepaid credit model. Accounts billed per transaction through Stripe Connect are unaffected — nothing in this section changes their API behavior.

The prepaid credit model​

Under the prepaid model, your organization maintains a credit balance with relay:

  • Credits are purchased in advance and cover your organization's usage of relay screening services.
  • Each completed screening report draws down the balance.
  • While the balance is positive, the API behaves exactly as documented elsewhere — there are no extra parameters, headers, or steps.
  • When the balance reaches $0, report access is paused until credits are added.

The billing relationship is between your organization and relay. It is independent of how — or whether — you bill your own customers for screenings. Consumer-facing payment flows that are part of the screening product (for example, consumer-paid screening via Stripe Checkout) are a separate mechanism and are not affected by prepaid credits.

Pre-flight balance check​

Before each report pull, the platform runs a pre-flight balance check:

  1. The request authenticates and validates as usual.
  2. The platform confirms the account has sufficient credit for the pull.
  3. If the balance is sufficient, the report is generated and the balance is drawn down.
  4. If the balance is exhausted, the request is rejected with HTTP 402 Payment Required before a report is generated. No credit is consumed and no charge is incurred for a blocked request.

Because the check runs before report generation, a 402 is a deterministic billing signal — not a transient failure. The same request returns the same 402 on every attempt until the balance is restored.

The 402 Payment Required response​

When a report request is blocked for insufficient credits, the API responds with HTTP status 402 and this body:

{
  "error": {
    "code": "PAYMENT_REQUIRED",
    "message": "Your credit balance is $0. Please purchase credits to resume service.",
    "requestId": "e0d7c1a2-..."
  }
}
FieldDescription
error.codeAlways "PAYMENT_REQUIRED" for balance blocks. Match on this value.
error.messageHuman-readable description. Wording may change — never match on message.
error.requestIdInclude this when contacting support about a specific blocked request.

402 is returned by every report-pull endpoint:

const response = await fetch(reportUrl, { headers: authHeaders });

if (response.status === 402) {
  const { error } = await response.json();
  if (error.code === "PAYMENT_REQUIRED") {
    // Credit balance exhausted. Do NOT retry or queue for retry.
    // Route to your billing/ops owner; resume normally after top-up.
    alertBillingOwner({ requestId: error.requestId });
    return;
  }
}
  1. Do not retry. Unlike 5xx responses, a 402 returns the identical result on every attempt until credits are added. Exclude 402 from any automatic retry or backoff logic.
  2. Alert the balance owner, not the end user. Route the condition to whoever manages your relay credits. The person in the request path usually cannot resolve it.
  3. Resume without special recovery. Once credits are added, requests succeed again immediately. There is no session to reset and nothing to re-authenticate.

No integration changes are required to accommodate billing. Request formats, authentication, endpoints, and success response schemas are unchanged; the only recommended (optional) improvement is explicit 402 handling so an exhausted balance surfaces as a clear billing alert rather than a generic failure.

Purchasing credits and auto-recharge​

Credit balances, usage history, low-balance alerts, and automatic recharge are managed outside the API:

  • Self-service: manage credits and configure automatic recharge in your relay billing portal.
  • Assisted: contact your relay account manager or integration support to arrange a credit purchase.

Enable low-balance email alerts and automatic recharge so the balance never reaches $0 in normal operation. If you need help accessing your billing portal, contact integration support.