One-Off Invoices

A one-off invoice is an invoice you create yourself — through the API or the dashboard — for a charge that no subscription schedule produces: a setup fee, professional services, hardware, a correction. There is no separate invoice type; it is an ordinary invoice created with a customer_id, a currency, and your own line_items, and it follows the same lifecycle as every other invoice. Use this page for the create → edit → issue → void operations on an invoice. For subscription-generated invoices see Recurring Invoices; for delivery and payment collection see Invoicing Customers.

Create via API

POST /invoices creates the invoice and its line items in one call. See Create an invoice.

curl https://api.alguna.io/invoices \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_abc123",
    "currency": "USD",
    "description": "Consulting engagement - January 2026",
    "purchase_order_number": "PO-4471",
    "line_items": [
      {
        "description": "Implementation Services",
        "quantity": "1",
        "unit_price": "2500.00"
      },
      {
        "product_id": "prod_training",
        "description": "Training",
        "quantity": "8",
        "unit_price": "150.00"
      }
    ]
  }'

import os

import requests

response = requests.post(
    "https://api.alguna.io/invoices",
    headers={
        "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
        "Alguna-Version": "2026-04-01",
        "Content-Type": "application/json",
    },
    json={
        "customer_id": "cust_abc123",
        "currency": "USD",
        "description": "Consulting engagement - January 2026",
        "purchase_order_number": "PO-4471",
        "line_items": [
            {
                "description": "Implementation Services",
                "quantity": "1",
                "unit_price": "2500.00",
            },
            {
                "product_id": "prod_training",
                "description": "Training",
                "quantity": "8",
                "unit_price": "150.00",
            },
        ],
    },
    timeout=10,
)
response.raise_for_status()

invoice = response.json()
print(invoice["id"], invoice["status"], invoice["total"])

const invoice = await alguna.invoices.create({
  customer_id: "cust_abc123",
  currency: "USD",
  description: "Consulting engagement - January 2026",
  purchase_order_number: "PO-4471",
  line_items: [
    { description: "Implementation Services", quantity: "1", unit_price: "2500.00" },
    { product_id: "prod_training", description: "Training", quantity: "8", unit_price: "150.00" },
  ],
});

Request fields

Field	Description
`customer_id`	Customer to bill. See Customers.
`currency`	ISO 4217 code. Must match the customer’s currency; see Multi-Currency.
`description`	Invoice memo shown to the customer.
`line_items[]`	`quantity` and `unit_price` are required, as decimal strings. Optional `description`, `product_id`, and a service period (`billing_period_start`, `billing_period_end`).
`purchase_order_number`	Customer’s PO number, printed on the invoice.
`billing_period_start` / `billing_period_end`	Period the invoice covers. The end is exclusive: for a period through 31 January send `2026-02-01T00:00:00Z`.
`issue_date`	Date to issue the invoice.
`status`	Initial status: `draft` (default) or `issued`. `paid` is only valid on the tax-calculation path below.
`merchant_id`	Issue the invoice on behalf of a merchant (sub-merchant) while you remain seller of record.
`tax_calculation_id`	Build the invoice from a persisted tax calculation instead of inline line items.

unit_price excludes tax; tax is calculated on top of it by Alguna Tax or your external provider. Payment terms, numbering, and the default memo are organization settings, not request fields — the due date is derived from the configured terms. See Invoicing Configuration.

Issue on create

Invoices default to draft. Send "status": "issued" to release the invoice in the same call. Issuance is asynchronous: the response comes back in processing and settles to issued shortly after. Poll GET /invoices/{id} or listen for the invoice.issued webhook.

curl https://api.alguna.io/invoices \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_abc123",
    "currency": "USD",
    "status": "issued",
    "line_items": [
      { "description": "Implementation Services", "quantity": "1", "unit_price": "2500.00" }
    ]
  }'

import os
import time

import requests

headers = {
    "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
    "Alguna-Version": "2026-04-01",
    "Content-Type": "application/json",
}

created = requests.post(
    "https://api.alguna.io/invoices",
    headers=headers,
    json={
        "customer_id": "cust_abc123",
        "currency": "USD",
        "status": "issued",
        "line_items": [
            {"description": "Implementation Services", "quantity": "1", "unit_price": "2500.00"}
        ],
    },
    timeout=10,
)
created.raise_for_status()
invoice_id = created.json()["id"]

# Issuance is asynchronous; poll until it settles.
for _ in range(10):
    current = requests.get(f"https://api.alguna.io/invoices/{invoice_id}", headers=headers, timeout=10)
    current.raise_for_status()
    if current.json()["status"] != "processing":
        break
    time.sleep(1)

print(current.json()["status"], current.json().get("external_reference"))

A draft created earlier is issued from the dashboard with Issue Invoice; the API sets the initial status at creation time only.

Issue from a tax calculation

When you have already priced and taxed a basket with POST /tax/calculations — for example in your own checkout — pass its tax_calculation_id instead of line_items and currency. The stored line items, tax amounts, and buyer become the invoice, which is issued synchronously. Add "status": "paid" and a payment object (source, optional reference, paid_at, note) to record an already-settled payment in the same call. See Tax.

Create via dashboard

Open Invoices and click New Invoice

New Invoice form with the customer dropdown open, listing existing customers and a New Customer option

Select or create the customer

The invoice takes the customer’s currency and payment terms.

Set the due date and memo

New Invoice form with customer, currency, Net 30 due date and memo filled in and an empty line item

Add line items

Pick products from the catalog or add free-text lines, then set quantities.

New Invoice form with two line items with billing periods and the product dropdown open to add a third

Save, review, and issue

Save Invoice keeps it as a draft. Issue Invoice finalizes it and sends it to the customer.

Issued invoice detail page with status, header information, line items, totals and the Mark as Paid button

Edit a draft

Update invoice details

PATCH /invoices/{id} updates the memo and purchase order number. See Update an invoice.

curl -X PATCH https://api.alguna.io/invoices/inv_abc123 \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{ "description": "Updated memo", "purchase_order_number": "PO-4471" }'

import os

import requests

response = requests.patch(
    "https://api.alguna.io/invoices/inv_abc123",
    headers={
        "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
        "Alguna-Version": "2026-04-01",
        "Content-Type": "application/json",
    },
    json={"description": "Updated memo", "purchase_order_number": "PO-4471"},
    timeout=10,
)
response.raise_for_status()

await alguna.invoices.update("inv_abc123", {
  description: "Updated memo",
  purchase_order_number: "PO-4471",
});

Manage line items

Line items are editable while the invoice is a draft. Each line in a response carries is_editable.

# Add
curl -X POST https://api.alguna.io/invoices/inv_abc123/line-items \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{ "description": "Additional Hours", "quantity": "5", "unit_price": "150.00" }'

# Rename
curl -X PATCH https://api.alguna.io/invoices/inv_abc123/line-items/li_xyz789 \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{ "description": "Additional Hours - February" }'

# Remove
curl -X DELETE https://api.alguna.io/invoices/inv_abc123/line-items/li_xyz789 \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01"

import os

import requests

base = "https://api.alguna.io/invoices/inv_abc123/line-items"
headers = {
    "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
    "Alguna-Version": "2026-04-01",
    "Content-Type": "application/json",
}

added = requests.post(
    base,
    headers=headers,
    json={"description": "Additional Hours", "quantity": "5", "unit_price": "150.00"},
    timeout=10,
)
added.raise_for_status()
line_item_id = added.json()["id"]

requests.patch(
    f"{base}/{line_item_id}",
    headers=headers,
    json={"description": "Additional Hours - February"},
    timeout=10,
).raise_for_status()

requests.delete(f"{base}/{line_item_id}", headers=headers, timeout=10).raise_for_status()

await alguna.invoices.addLineItem("inv_abc123", {
  description: "Additional Hours",
  quantity: "5",
  unit_price: "150.00",
});

await alguna.invoices.updateLineItem("inv_abc123", "li_xyz789", {
  description: "Additional Hours - February",
});

await alguna.invoices.deleteLineItem("inv_abc123", "li_xyz789");

Reference: Create, Update, and Delete an invoice line item. Deleting a line fires the lineitem.deleted webhook.

Download the PDF

GET /invoices/{id}/pdf returns the rendered invoice as application/pdf. If a custom PDF was uploaded for the invoice it is served as-is; otherwise the standard template is rendered with your branding. See Generate an invoice PDF.

curl https://api.alguna.io/invoices/inv_abc123/pdf \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  --output invoice.pdf

import os

import requests

response = requests.get(
    "https://api.alguna.io/invoices/inv_abc123/pdf",
    headers={
        "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
        "Alguna-Version": "2026-04-01",
    },
    timeout=30,
)
response.raise_for_status()

with open("invoice.pdf", "wb") as f:
    f.write(response.content)

const pdf = await alguna.invoices.generatePdf("inv_abc123");

Void an issued invoice

POST /invoices/{id}/void withdraws an issued or overdue invoice. Voiding any other status returns 400. void_date defaults to today; it may be backdated but must not be in the future or before the issue date (422). See Void an invoice.

curl -X POST https://api.alguna.io/invoices/inv_abc123/void \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{ "void_date": "2026-02-01T00:00:00Z" }'

import os

import requests

response = requests.post(
    "https://api.alguna.io/invoices/inv_abc123/void",
    headers={
        "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
        "Alguna-Version": "2026-04-01",
        "Content-Type": "application/json",
    },
    json={"void_date": "2026-02-01T00:00:00Z"},
    timeout=10,
)
response.raise_for_status()
print(response.json()["status"])  # "void"

await alguna.invoices.void("inv_abc123", { void_date: "2026-02-01T00:00:00Z" });

A draft has never reached the customer — cancel it from the dashboard instead of voiding.
A paid invoice cannot be voided. Issue a credit note and, if money should go back, a refund.

Record an external payment

When a customer pays outside Alguna (wire, cheque, cash), record it with POST /invoices/{id}/mark-as-paid. That operation, together with AutoPay and payment methods, is covered in Invoicing Customers.

Webhooks

Event	Fires when
`invoice.issued`	Issuance completed and the invoice was delivered
`invoice.paid`	The balance reached zero
`lineitem.deleted`	A line item was removed

Payloads are camelCase. Shapes and delivery details are on Webhooks; a handler walkthrough is in the webhooks quick start.

Next steps

Invoicing Customers

Delivery, AutoPay, and recording payments.

Credit Notes

Correct an issued invoice without voiding it.

Tax

Calculate tax up front and issue from the result.

How Alguna Works

Where invoices sit in the quote-to-cash chain.

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

Create via API

Request fields

Issue on create

Issue from a tax calculation

Create via dashboard

Edit a draft

Update invoice details

Manage line items

Download the PDF

Void an issued invoice

Record an external payment

Webhooks

Next steps

Invoicing Customers

Credit Notes

Tax

How Alguna Works

​Create via API

​Request fields

​Issue on create

​Issue from a tax calculation

​Create via dashboard

​Edit a draft

​Update invoice details

​Manage line items

​Download the PDF

​Void an issued invoice

​Record an external payment

​Webhooks

​Next steps

Invoicing Customers

Credit Notes

Tax

How Alguna Works

Create via API

Request fields

Issue on create

Issue from a tax calculation

Create via dashboard

Edit a draft

Update invoice details

Manage line items

Download the PDF

Void an issued invoice

Record an external payment

Webhooks

Next steps