Invoicing Configuration

​

Invoice statuses

​

Typical transitions

Subscription-generated:  upcoming → pending_approval → scheduled → processing → issued → paid
                                                                                       ↘ overdue → paid
Ad hoc:                  draft → processing → issued → paid
Exits:                   draft | upcoming | pending_approval | scheduled → canceled
                         issued | overdue → void

​

Reading statuses from the API

curl "https://api.alguna.io/invoices?status=pending_approval,scheduled&limit=50&offset=0&sort=created_at:desc" \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01"

import os

import requests

response = requests.get(
    "https://api.alguna.io/invoices",
    headers={
        "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
        "Alguna-Version": "2026-04-01",
    },
    params={
        "status": "pending_approval,scheduled",
        "limit": 50,
        "offset": 0,
        "sort": "created_at:desc",
    },
    timeout=10,
)
response.raise_for_status()

for invoice in response.json()["data"]:
    print(invoice["id"], invoice["status"], invoice["total"], invoice["currency"])

​

Organization settings

​

Approving and sending invoices

• Default invoice issuer: the system that issues invoices. Alguna issues and delivers them itself, or hands them to a connected invoicing integration — Stripe Invoicing, QuickBooks, or Xero. See the integrations marketplace.
• Automatic approval: when on, an invoice moves from upcoming straight to scheduled when its period closes, and is issued on its issue date without review. Use this when usage is metered continuously and the numbers need no human check.
• Manual approval: when off, closed-period invoices stop at pending_approval. Approve them from the invoice page with Approve Invoice, or in bulk from the invoices list. Use this when you upload usage by CSV or want a review step before anything reaches a customer.

​

Invoice numbering

• Numbering method: one sequence for the whole organization (INV-0001, INV-0002, …) or a separate sequence per customer.
• Custom prefix: the text before the number, for example INV.

​

Default options

• Memo: the default text for the invoice memo. Supported variables:
  • {BillingPeriodStart} — first day of the billed period, e.g. August 1, 2026.
  • {BillingPeriodEnd} — last day of the billed period, e.g. August 31, 2026.
  • {BillingPeriod} — both ends in one variable, e.g. August 1, 2026 – August 31, 2026. A single-day period renders as that date.
  • {CustomerName} — the customer being billed. On a roll-up invoice this is the parent.
  • Any other text, including placeholders in other spellings such as {{billing_period}}, is printed exactly as written.
• Payment terms: how long after the issue date payment is due. Values are on_issue, net_7, net_15, net_21, net_30, net_45, net_60, net_90, net_120, or indefinite (no due date, so the invoice never becomes overdue). The due date is computed when the invoice is issued.
• Automatically release invoices to customers when using 3rd-party invoicing flows: when issuing through an external invoicing integration, send the invoice on without a second confirmation.
• Send $0 invoices to customers: deliver invoices whose total is zero. Off by default.

​

Next steps