Billing Technical Addendum

A concise technical reference on relay's prepaid credit billing model for engineering teams with REST API integrations. For the complete billing reference, see the Billing section. For a plain-language overview, see Billing: What's Changing.

Summary

• Accounts on the prepaid credit model purchase screening credits in advance; completed screening reports draw down the balance.
• No changes to your API integration are required to accommodate billing. Request formats, authentication, endpoints, and response schemas are unchanged.
• When an account's credit balance is exhausted, affected report requests return HTTP 402 Payment Required with a structured error body until credits are added.
• A 402 is a billing signal, not a transient error — do not retry. The result is deterministic until the balance is restored.

The 402 response

When a request is blocked for insufficient credits, the platform 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-..."
  }
}

Field	Description
error.code	Always "PAYMENT_REQUIRED" for balance blocks. Match on this value.
error.message	Human-readable description. Wording may change — never match on message.
error.requestId	Include this when contacting support about a specific blocked request.

How to handle it

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.
    // Alert your billing/ops contact; resume normally after top-up.
    alertBillingOwner({ requestId: error.requestId });
    return;
  }
}

Recommended behavior:

1. Do not retry. Unlike 5xx responses, a 402 will return the identical result on every attempt until credits are added. Exclude 402 from any automatic retry or backoff logic.
2. Alert the balance owner. Route the condition to whoever manages your relay credits — not to the end user in the request path.
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 API changes required

This billing change introduces no new required parameters, headers, endpoints, or response schema changes. Integrations that already handle non-2xx responses defensively will continue to work without modification. The only recommended (optional) improvement is explicit 402 handling as shown above, so an exhausted balance surfaces as a clear billing alert rather than a generic failure.

Separation of concerns

relay's billing relationship is with your organization, not with your customers:

• Prepaid credits cover your organization's usage of relay screening services.
• Nothing about this model touches your end-customer billing. How — or whether — you charge your own customers for screenings is entirely your business and is unaffected by this change.
• Consumer-facing payment flows that are part of the screening product (e.g., consumer-paid screening via Stripe Checkout) are a separate mechanism and are not altered by prepaid credits.

Transition period

Existing TSPs on the Stripe Connect / MOR billing model continue to operate that integration without interruption during the transition to prepaid credit billing. There is no hard cutover for existing accounts — the existing per-transaction Stripe Connect flow and the new prepaid credit model run in parallel until an account completes billing setup and migrates. Your existing report-pull integration is unaffected until you migrate.

Managing credits

Credit balances, usage, low-balance alerts, and automatic recharges are managed through your relay billing portal, or with the help of your account manager / integration support. If you need help accessing your billing portal, contact integration support.

---

Questions? Contact integration support with the requestId from any 402 response you have questions about.