API reference for invoices, payments, quotes, credit notes, and billing summary.

Billing API

The Billing API provides endpoints for managing invoices, recording payments, generating quotes, issuing credit notes, and viewing billing summaries. All endpoints require a valid JWT token.

Billing Summary

Get an overview of your billing metrics.

curl https://api.nextroute.app/api/billing/summary \
  -H "Authorization: Bearer YOUR_TOKEN"

Returns aggregated totals for invoices, payments, outstanding balances, and monthly revenue.

Invoices

List Invoices

Retrieve a paginated list of invoices with optional filters.

curl "https://api.nextroute.app/api/invoices?status=sent&page=1&limit=50" \
  -H "Authorization: Bearer YOUR_TOKEN"

Query Parameters:

Parameter	Type	Description
`status`	string	Filter by status: `draft`, `sent`, `paid`, `overdue`, `void`
`customer_id`	string	Filter by customer
`from_date`	string	Invoice created after this date
`to_date`	string	Invoice created before this date
`page`	integer	Page number (default: 1)
`limit`	integer	Results per page (default: 50, max: 200)

Get Invoice

Retrieve a single invoice with line items.

curl https://api.nextroute.app/api/invoices/inv_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Response (200):

{
  "id": "inv_abc123",
  "invoice_number": "INV-1042",
  "customer_id": "cus_xyz789",
  "customer_name": "John Doe",
  "status": "sent",
  "subtotal_cents": 7500,
  "tax_rate": 8.25,
  "tax_cents": 619,
  "total_cents": 8119,
  "due_date": "2026-04-01",
  "created_at": "2026-03-15T00:00:00Z",
  "line_items": [
    {
      "description": "Weekly Bin Cleaning - March 2026",
      "quantity": 1,
      "unit_price_cents": 7500,
      "total_cents": 7500,
      "service_plan_id": "sp_abc123"
    }
  ]
}

Generate Invoices (Auto-Billing)

Trigger automatic invoice generation for all active customers based on their service plans.

curl -X POST https://api.nextroute.app/api/invoices/generate \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "billing_period": "2026-03",
    "auto_send": true
  }'

This is the primary endpoint for the auto-billing workflow. It creates invoices for each active customer based on their plan pricing, applies tax rates, and optionally sends them immediately.

Create Invoice Manually

Create a custom invoice with specific line items.

curl -X POST https://api.nextroute.app/api/invoices \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_xyz789",
    "due_date": "2026-04-15",
    "line_items": [
      {
        "description": "One-time deep clean",
        "quantity": 1,
        "unit_price_cents": 15000
      }
    ],
    "notes": "Deep cleaning service requested by customer"
  }'

Update Invoice

Update a draft invoice's line items, due date, or notes.

curl -X PUT https://api.nextroute.app/api/invoices/inv_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "due_date": "2026-04-30",
    "notes": "Extended payment terms"
  }'

Send Invoice

Send an invoice to the customer via email. Changes status from draft to sent.

curl -X POST https://api.nextroute.app/api/invoices/inv_abc123/send \
  -H "Authorization: Bearer YOUR_TOKEN"

The email includes a link to pay online via the customer portal (if Stripe is configured).

Get Invoice PDF

Retrieve a printable HTML version of the invoice, suitable for rendering as a PDF.

curl https://api.nextroute.app/api/invoices/inv_abc123/pdf \
  -H "Authorization: Bearer YOUR_TOKEN"

Void Invoice

Void an invoice. This is a permanent action — voided invoices cannot be un-voided.

curl -X POST https://api.nextroute.app/api/invoices/inv_abc123/void \
  -H "Authorization: Bearer YOUR_TOKEN"

Mark Invoice as Paid

Manually mark an invoice as paid (for cash, check, or external payments).

curl -X POST https://api.nextroute.app/api/invoices/inv_abc123/mark-paid \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method": "cash",
    "notes": "Paid in cash at door"
  }'

Payments

List Payments

Retrieve payment records.

curl "https://api.nextroute.app/api/payments?customer_id=cus_xyz789" \
  -H "Authorization: Bearer YOUR_TOKEN"

Record a Payment

Manually record a payment against an invoice.

curl -X POST https://api.nextroute.app/api/payments/record \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_id": "inv_abc123",
    "customer_id": "cus_xyz789",
    "amount_cents": 8119,
    "payment_method": "check",
    "reference": "Check #4521"
  }'

Get Payment Details

curl https://api.nextroute.app/api/payments/pay_def456 \
  -H "Authorization: Bearer YOUR_TOKEN"

Quotes

Quotes let you send pricing proposals to prospective or existing customers before creating an invoice.

List Quotes

curl https://api.nextroute.app/api/quotes \
  -H "Authorization: Bearer YOUR_TOKEN"

Create Quote

curl -X POST https://api.nextroute.app/api/quotes \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_xyz789",
    "valid_until": "2026-04-30",
    "line_items": [
      { "description": "Weekly bin cleaning", "quantity": 4, "unit_price_cents": 7500 }
    ]
  }'

Send Quote

curl -X POST https://api.nextroute.app/api/quotes/qt_abc123/send \
  -H "Authorization: Bearer YOUR_TOKEN"

Accept Quote

When a customer accepts a quote, it can be automatically converted to an invoice.

curl -X PUT https://api.nextroute.app/api/quotes/qt_abc123/accept \
  -H "Authorization: Bearer YOUR_TOKEN"

Decline Quote

curl -X POST https://api.nextroute.app/api/quotes/qt_abc123/decline \
  -H "Authorization: Bearer YOUR_TOKEN"

Credit Notes

Credit notes represent refunds or credits applied to a customer's account.

List Credit Notes

curl https://api.nextroute.app/api/credit-notes \
  -H "Authorization: Bearer YOUR_TOKEN"

Create Credit Note

curl -X POST https://api.nextroute.app/api/credit-notes \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_xyz789",
    "amount_cents": 7500,
    "reason": "Missed service on March 15",
    "invoice_id": "inv_abc123"
  }'

Apply Credit Note

Apply a credit note to an outstanding invoice.

curl -X POST https://api.nextroute.app/api/credit-notes/cn_abc123/apply \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"invoice_id": "inv_def456"}'

Void Credit Note

curl -X POST https://api.nextroute.app/api/credit-notes/cn_abc123/void \
  -H "Authorization: Bearer YOUR_TOKEN"

Invoice Numbering

Invoices are automatically assigned sequential numbers in the format INV-XXXX (e.g., INV-1001, INV-1002). The next invoice number is tracked per tenant and increments with each invoice created.

Tax Calculation

Tax is calculated automatically based on:

Service plan tax rate — if the customer's plan has a specific tax rate configured
Tenant default tax rate — used as a fallback when no plan-specific rate exists

Tax is applied to the subtotal: tax_cents = subtotal_cents * (tax_rate / 100).

Auto-Billing — automated invoice generation workflow
Invoices — invoice concepts and lifecycle
Missed Service Credits — automatic credit notes for skipped services
API Authentication — obtaining JWT tokens

Billing API

On this page