API Billing Readiness

Before paid API work, check whether the tenant is ready to proceed and what billing step may be needed. The result is advisory: it does not reserve capacity, approve an invoice, guarantee payment or provider fulfillment, or change submission, payment, or authentication requirements.

Choose your workflow

The readiness check is for headless API integrations. The Travel Agencies Portal supports interactive workflows such as Stripe Checkout; that portal checkout is not a headless API billing arrangement.

Headless clients should coordinate billing setup with their Fluxir administrator or support contact before paid submission.

Invoice-based Billing

A tenant may be configured for invoice-based billing. Invoice approval remains an explicit, staff-controlled billing execution step. Readiness does not infer approval from an invoice, balance, Marketplace status, or Stripe Checkout completion.

In this guide, deferred-payment eligibility describes the tenant's billing configuration; it does not grant postpaid credit. Fluxir invoice-based balance top-ups are prepaid. See the billing and Marketplace setup guide for details.

Automatic Payments

A tenant can be ready for API use when Fluxir currently verifies a usable automatic payment method, even if invoicing is unavailable or deferred payment is prohibited. An authorized billing user manages this method in the Travel Agencies Portal; see the Automatic payments guide. The readiness check does not guarantee that a later payment will be approved.

Check readiness

First follow the authentication guide to obtain a bearer token. Then request readiness for the tenant represented by the token:

curl --request GET 'https://api.fluxir.com/api/app/billing-readiness/current' \
  --header 'Authorization: Bearer <ACCESS_TOKEN_VALUE>' \
  --header 'X-Tenant: <YOUR_TENANT_ID>' \
  --header 'Accept: application/json'

The current-tenant readiness endpoint documents the generated API contract. Authorized delegated clients can instead use the specific-tenant readiness endpoint with a UUID path parameter. Do not use that route to probe tenants without delegated authorization.

A successful response uses these fields:

Field	Meaning
status	READY, NOT_READY, NOT_BILLABLE, or UNKNOWN.
billingArrangement	Informational arrangement: Invoice, None, or Unknown in the current implementation. It is not the readiness decision.
reason	Human-readable explanation returned by the service.
nextActions	Suggested action objects with code, title, description, and an optional trusted url.
tenantMode	Production or Test. Test mode describes the tenant mode; it does not promise no-charge execution.
evaluatedAt	UTC time when the response was evaluated.
dataAsOf	Timestamp associated with the data used, or null when source data is unavailable. It may match evaluatedAt; it is not necessarily an independent source-update time.

Interpret the status

Status	Meaning	Next step
READY	The tenant has an available billing path: invoicing is allowed, or a usable automatic payment method is available where required.	Continue with the normal submission, validation, and payment workflow.
NOT_READY	The tenant is eligible for invoicing, but deferred payment is prohibited and no usable automatic payment method is available.	Ask the billing administrator which approved payment or approval step applies.
NOT_BILLABLE	The tenant is not eligible for invoicing and has no usable automatic payment method.	An authorized billing user can configure and verify an automatic payment method. Contact Fluxir support if invoice billing is required.
UNKNOWN	Fluxir could not determine readiness for the request.	Do not guess the billing state; resolve tenant context or contact support.

billingArrangement describes invoicing eligibility, not overall readiness or automatic-payment status. For example, a tenant can be READY with billingArrangement: "None" when a usable automatic payment method provides the available billing path. A usable method does not guarantee that a later charge will be approved or settled.

Example: ready

{
  "id": "11111111-1111-4111-8111-111111111111",
  "status": "READY",
  "billingArrangement": "Invoice",
  "reason": "Your account is configured for API consumption",
  "nextActions": [],
  "tenantMode": "Production",
  "evaluatedAt": "2026-09-17T10:30:00Z",
  "dataAsOf": "2026-09-17T10:30:00Z"
}

Example: action required

{
  "id": "22222222-2222-4222-8222-222222222222",
  "status": "NOT_READY",
  "billingArrangement": "Invoice",
  "reason": "Deferred payment is prohibited for this account",
  "nextActions": [
    {
      "code": "CONTACT_BILLING",
      "title": "Contact Billing Staff",
      "description": "Deferred payment is prohibited for this account. An authorized billing user can configure and verify an automatic payment method in Settings > Automatic Payments, or contact your billing administrator.",
      "url": null
    }
  ],
  "tenantMode": "Production",
  "evaluatedAt": "2026-09-17T10:31:00Z",
  "dataAsOf": "2026-09-17T10:31:00Z"
}

Treat nextActions as advisory instructions from Fluxir. Do not interpret a status as an instruction to create an invoice or make a payment through an unapproved channel.

Unknown, errors, and permissions

UNKNOWN is a business result, not an HTTP error. Do not guess the billing state; resolve the tenant context or contact support with the response timestamps and your correlation ID. For example, a request without tenant context may return:

{
  "id": "00000000-0000-0000-0000-000000000000",
  "status": "UNKNOWN",
  "billingArrangement": "Unknown",
  "reason": "No tenant context found",
  "nextActions": [
    {
      "code": "CONTACT_SUPPORT",
      "title": "Contact Support",
      "description": "Unable to determine your billing readiness. Please contact Fluxir support.",
      "url": null
    }
  ],
  "tenantMode": "Production",
  "evaluatedAt": "2026-09-17T10:32:00Z",
  "dataAsOf": null
}

An authentication failure is not an UNKNOWN business result. Handle the HTTP status first:

• 401 Unauthorized: obtain a valid access token and retry without logging or exposing the token.
• 403 Forbidden: the token is authenticated but is not allowed to inspect the requested tenant. Do not retry by changing tenantId or disclose whether another tenant exists.
• 500 Internal Server Error or another service error: record the response status, request timestamp, and correlation ID, then contact support. Do not treat a failed request as READY.

ABP error responses use the configured RemoteServiceErrorResponse shape, for example:

{
  "error": {
    "code": "Forbidden",
    "message": "You are not authorized to perform this operation.",
    "details": null,
    "data": null,
    "validationErrors": null
  }
}

Before paid submission

1. Authenticate with the intended tenant and inspect readiness close to the planned submission time. Compare evaluatedAt and dataAsOf with your own freshness policy.
2. If the result is READY, continue with the existing submission validation and payment workflow. Readiness does not bypass schema, authorization, tenant, application, or provider validation.
3. If an action is returned, follow only the action details supplied by Fluxir or your authorized administrator. The current actions are advisory and may not include a URL.
4. If the result is UNKNOWN, 401, 403, or a service error, pause and resolve the configuration or access issue with the administrator/support team.

Security Notice

Do not send access tokens, client secrets, passport images, or passport numbers to support. Share the tenant ID only through an approved support channel, along with the correlation ID, status, reason, and timestamps.

Test tenants are identified by tenantMode: "Test", but that label is not evidence that every operation is free, that providers will fulfill requests, or that production billing rules are simulated identically. Confirm test scope and expected charges with Fluxir before running paid or provider-backed scenarios.