Plan and credit blocks

Before changing billing

Use this page when a scan, fix task, retest, monitoring setup or AI-assisted action is unavailable because the account plan, billing state or credit balance is not ready. Billing should explain what the account can buy, wait for or stop; it should not become an override path.

• Open billing
• Check `package_key`, `billing_state`, `package_entitlement_status`, `credit_balance` and `remaining_fix_credits`.
• Return to the original workflow only after billing says the entitlement or balance is ready.

Triage the plan or credit block

Follow the path `Blocked workflow → Billing → Entitlement or balance reason → Checkout, wait, retry or stop`.

1. Open `/billing` from the blocked workflow message. Result: `account_id`, `package_key`, `package_entitlement_status`, `billing_state` and `credit_balance` are visible before the customer pays or changes plan.
2. Identify the blocked product action from `/projects/{project}`, `/reports/{report}`, `/fix-tasks/{fixTask}` or monitoring setup. Result: the page shows whether scan, fix, retest, monitoring or AI work needs plan entitlement or credits.
3. If `PACKAGE_ENTITLEMENT_MISSING` appears, compare current `package_key` with `selected_package_key` and available plan actions. Result: the customer chooses a plan that includes the action instead of requesting an override.
4. If `CREDIT_BALANCE_EXHAUSTED` appears, check `remaining_fix_credits`, `credit_balance` and the required credit type. Result: the customer buys or waits for credits before the action runs.
5. If `BILLING_STATE_BLOCKED`, `CHECKOUT_PAYMENT_PENDING` or `SUBSCRIPTION_PAST_DUE` appears, open `/billing/transactions` and payment status. Result: the workflow waits for payment confirmation, invoice resolution or subscription recovery.
6. Use `/billing/checkout` only for plan changes, subscription start, plan upgrade or credit purchase shown as available. Result: checkout is tied to the account and plan catalog.
7. Do not move credits between unrelated accounts, bypass plan limits or run paid workflows while `billing_state` is blocked. Result: paid delivery stays self-service and account-scoped.
8. After payment, plan or credit update, refresh `/billing` and verify `package_entitlement_status`, `subscription_status`, `payment_status` and balance fields. Result: the blocked workflow can see the new entitlement.
9. Return to the original scan, fix, retest, monitoring or AI action and retry only when its enabled state changes. Result: product work starts from the owning workflow, not billing alone.
10. Continue to Resolve blocked or failed states, Plans and credit state, Automated fix credits or Refunds, disputes and service credits when the remaining owner is outside this page. Result: the next guide explains the correct automated billing path.

Blocked billing reasons

Use the reason code before opening checkout.

• `PACKAGE_ENTITLEMENT_MISSING` means the current plan does not include the blocked action.
• `PLAN_CHANGE_REQUIRED` means a supported plan change is available before the workflow can run.
• `CREDIT_BALANCE_EXHAUSTED` means the account has no usable balance for the action type.
• `MONITORING_ENTITLEMENT_MISSING` means recurring monitoring is not active for the project or plan.
• `AI_CREDIT_LIMIT_REACHED` means AI-assisted drafting, triage or review must wait for account-scoped `ai_credit_balance` or a non-AI fallback.
• `BILLING_STATE_BLOCKED`, `CHECKOUT_PAYMENT_PENDING` and `SUBSCRIPTION_PAST_DUE` mean the workflow must wait for payment or subscription state to recover.

Automated billing actions

Use only the billing action shown as available for the account.

• Use `/billing/checkout` for subscription start, plan upgrade, plan change or credit purchase tied to `checkout_session_id`.
• Use `/billing/transactions` to inspect invoice, receipt, dispute or payment confirmation state.
• Keep `payment_status`, `subscription_status`, `package_entitlement_status` and `monitoring_entitlement_status` visible before retrying product work.
• Do not transfer credits between unrelated accounts, hide plan limits or start paid delivery while billing is blocked.

Ready and blocked paid workflow states

A paid workflow is ready only when billing and the owning workflow both agree the action is available.

• Ready: plan includes the action, `billing_state` is active, `payment_status` is confirmed, `credit_balance` or `remaining_fix_credits` covers the action and the original workflow button is enabled.
• Still blocked: plan missing, checkout pending, subscription past due, invoice unresolved, credit balance exhausted, monitoring inactive, AI allowance exhausted or account mismatch.
• Stop: the plan catalog does not support the requested action, the account does not own the project/report/fix task or the customer is trying to bypass plan limits.

Continue after billing triage

Use the linked guide for the paid workflow or billing state that still owns the block.

• Plans and credit state explains plan keys, balances, billing state and entitlement labels.
• Automated fix credits and Scan credits explain credit-specific purchase, use and exhaustion states.
• Monitoring plans explains monitoring entitlement and recurring scan availability.
• Refunds, disputes and service credits explains payment exceptions without turning blocked workflows into manual delivery.
• Resolve blocked or failed states explains how to return to the workflow that showed the billing block.