Snapbooks logo Snapbooks Developer

Billing Status API

Endpoint

GET /snapbooks/api/v2/billing/status?client_account_id={id}

Response

{
  "has_payment_method": true,
  "status": "ACTIVE",
  "can_process": true
}

Status Values

Status Description User Action
ACTIVE Account in good standing None
NO_PLAN Trial ended, no active subscription Prompt to select a plan
OVER_USAGE Exceeded monthly voucher quota Prompt to upgrade plan
PAYMENT_OVERDUE Unpaid invoices past due date (7 day grace) Prompt to pay invoices

Frontend Usage

interface BillingStatus {
  has_payment_method: boolean;
  status: 'ACTIVE' | 'NO_PLAN' | 'OVER_USAGE' | 'PAYMENT_OVERDUE';
  can_process: boolean;
}

async function checkBillingStatus(clientAccountId: number): Promise<BillingStatus> {
  const response = await fetch(
    `/snapbooks/api/v2/billing/status?client_account_id=${clientAccountId}`
  );
  return response.json();
}

Handling Blocked Status

When can_process is false, show appropriate messaging:

function getBillingMessage(status: BillingStatus): string | null {
  switch (status.status) {
    case 'NO_PLAN':
      return 'Your trial has ended. Please select a plan to continue.';
    case 'OVER_USAGE':
      return 'You have exceeded your monthly voucher limit. Please upgrade your plan.';
    case 'PAYMENT_OVERDUE':
      return 'You have unpaid invoices. Please update your payment method.';
    default:
      return null;
  }
}
  1. Check on app load - Fetch status when user logs in or switches client account
  2. Show banner - Display a dismissible banner when can_process is false
  3. Block actions - Disable upload/processing buttons when blocked
  4. Link to resolution - Direct users to billing settings page
Endpoint Purpose
GET /billing/documents List invoices
POST /billing/documents/{id}/pay Pay an invoice
GET /billing/payment-methods List saved cards
POST /billing/payment-methods/setup Add new card