Recurring Invoices

A recurring invoice is one Alguna generates from a subscription’s billing schedule rather than one you create by hand. Once a customer has an active subscription, each billing period produces an upcoming invoice that accrues fixed charges and rated usage until the period closes, then moves through approval and issuance without anyone re-keying amounts. Use this page to understand what the schedule does on its own, which settings on the subscription control it, and how to review an invoice before it goes out. The status vocabulary (upcoming, pending_approval, scheduled, …) is defined in Invoicing Configuration. For the subscription object itself, see How Alguna Works and Subscriptions.

What the schedule does

Activation creates the billing schedule. The first period starts on the subscription’s first_billing_date (or its start date), and the cadence follows the prices on the subscription — monthly, annual, in advance or in arrears per product.
During the period the invoice is upcoming. Fixed charges are present from the start; metered lines are re-rated as usage events arrive; credits are applied as pending ledger entries. Editing a subscription version, changing the customer’s parent for roll-up billing, or granting credit all recalculate it.
When the period closes the invoice either becomes scheduled (automatic approval) or stops at pending_approval for review, depending on the organization setting and the subscription’s auto_issue_invoices flag.
On the issue date it is issued asynchronously (processing → issued), delivered to the customer, and — if auto_pay_invoices is on and a payment method is saved — charged. See Invoicing Customers.

Issued invoices are immutable. Later corrections go through credit notes, never by editing the issued document.

Subscription billing settings

The per-subscription controls are on the subscription’s billing object, set at creation and updatable through PATCH /subscriptions/{id}:

Field	Meaning
`auto_issue_invoices`	Issue closed-period invoices without a manual approval step
`auto_pay_invoices`	Charge the customer’s default payment method when the invoice is issued
`payment_terms`	Days from issue to due date, e.g. `net_30`; falls back to the organization default
`first_billing_date`	First period start (`YYYY-MM-DD`)

curl -X PATCH https://api.alguna.io/subscriptions/sub_abc123 \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "billing": {
      "auto_issue_invoices": false,
      "auto_pay_invoices": true,
      "payment_terms": "net_30"
    }
  }'

import os

import requests

response = requests.patch(
    "https://api.alguna.io/subscriptions/sub_abc123",
    headers={
        "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
        "Alguna-Version": "2026-04-01",
        "Content-Type": "application/json",
    },
    json={
        "billing": {
            "auto_issue_invoices": False,
            "auto_pay_invoices": True,
            "payment_terms": "net_30",
        }
    },
    timeout=10,
)
response.raise_for_status()
print(response.json()["billing"])

See Update a subscription. Plans carry the same settings as defaults under invoice_settings, so every subscription created from a plan starts with them. GET /subscriptions/{id}/billing-dates returns the valid billing dates for a subscription — useful when you want to align a start date to the schedule. See Get valid billing dates.

Finding a subscription’s invoices

Filter the invoice list by subscription_id. The upcoming invoice for the current period is included, so you can show a customer what they are accruing before it is billed.

curl "https://api.alguna.io/invoices?subscription_id=sub_abc123&limit=20&offset=0&sort=issue_date: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={
        "subscription_id": "sub_abc123",
        "limit": 20,
        "offset": 0,
        "sort": "issue_date:desc",
    },
    timeout=10,
)
response.raise_for_status()

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

GET /invoices/{id} returns the full invoice, including line_items, subtotal, tax, total, amount_paid, amount_remaining, due_date, and external_reference (the customer-facing number). See Get an invoice.

Reviewing an invoice in the dashboard

Open the invoice from Invoices. The header shows the total, the current status, and the actions available in that status.

To — the billed customer. Hover to check or edit the billing address.
From — the legal entity issuing the invoice.
Currency — the subscription’s currency; see Multi-Currency.
Payment method — the customer’s default, used when auto_pay_invoices is on.
Invoice date — when the invoice became ready for approval.
Due date — computed from the payment terms when the invoice is issued.

Actions

Approve Invoice — moves a pending_approval invoice to scheduled; it is issued on its issue date. Approve several at once from the invoices list.
Copy Invoice Link — a link to the hosted invoice page.
Cancel Invoice — withdraws the invoice before issuance (canceled). Charges for that period are not re-billed.

Line items

The Details section lists each charge with its service period, quantity, unit price, and tax.

Add Item adds a line from the product catalog or a free-text line.
Edit Item changes description, quantity, or unit price, then Confirm.
Delete Item removes a line, with a confirmation step.

Invoice Details section with a line item showing quantity, unit price, tax rate and amount, edit and delete icons, and Add Item

Whether a line can be changed is reported as is_editable on the line item in the API. Lines generated from a subscription’s prices are re-rated by the schedule; manual lines are yours. The same operations are available on POST, PATCH, and DELETE /invoices/{id}/line-items — see One-Off Invoices.

Totals

Subtotal — the sum of line amounts before tax.
Tax — computed by Alguna Tax or an external provider.
Total — subtotal plus tax.
Amount paid and Amount due — collection against the total.

Invoice pending approval with header information, line item, subtotal, tax, total, amount paid and amount due, and the Approve Invoice button

Next steps

Invoicing Configuration

Statuses, numbering, memo variables, and approval settings.

Invoicing Customers

Delivery, AutoPay, and payment collection.

Roll-Up Billing

Bill a parent customer for its subsidiaries’ subscriptions.

Revenue Recognition

How issued invoices become revenue schedules.

Overview

Guides

Getting Started

Customers

Pricing & Packaging

Quotes (CPQ)

Subscriptions

Entitlements

Invoices

Credits & Wallets

Usage Metering

Approval Workflows

Automations

Collections

Tax Management

Hosted Pages

Revenue & Accounting

Multi-Currency

Data & Exports

AI

What the schedule does

Subscription billing settings

Finding a subscription’s invoices

Reviewing an invoice in the dashboard

Header

Actions

Line items

Totals

Next steps

Invoicing Configuration

Invoicing Customers

Roll-Up Billing

Revenue Recognition

​What the schedule does

​Subscription billing settings

​Finding a subscription’s invoices

​Reviewing an invoice in the dashboard

​Header

​Actions

​Line items

​Totals

​Next steps

Invoicing Configuration

Invoicing Customers

Roll-Up Billing

Revenue Recognition

What the schedule does

Subscription billing settings

Finding a subscription’s invoices

Reviewing an invoice in the dashboard

Header

Actions

Line items

Totals

Next steps