Invoicing Customers

Once an invoice is issued, the remaining job is collection: getting it in front of the customer and getting it paid. This page covers that half of the invoice lifecycle — email delivery, the hosted invoice page, automatic charging (AutoPay), saving payment methods, the self-service portal, recording payments made outside Alguna, and reading payments back through the API. Use it when you are deciding how a customer will pay, or wiring your own systems to payment outcomes. Creating invoices is covered in Recurring Invoices and One-Off Invoices. What happens when payment fails or is late is in Dunning and Collections. Alguna is not a payment processor: it decides what is owed and when, and a connected processor such as Stripe moves the money. See How Alguna Works.

What the customer sees

Invoice email

When an invoice is issued, the customer’s contacts receive an email with the amount, due date, and a link to the hosted invoice. If AutoPay is on, the email says so and no action is needed. Delivery can be turned off for subscriptions created from a plan with the plan’s invoice_settings.send_invoices_to_customer.

Hosted invoice page

Review Invoice opens the hosted page: itemised charges, tax breakdown, terms and due date, and the PDF.

Payment

AutoPay customers are charged automatically. Everyone else pays from the hosted page with a method your processor supports, or offline by bank transfer.

Receipt

On success the customer receives a receipt email and PDF. Turn this off with the plan’s invoice_settings.send_receipts_to_customer.

Who receives invoices

Invoices go to the customer’s contacts. Set them on the customer record; contacts replaces all existing contacts when provided.

curl -X PATCH https://api.alguna.io/customers/cust_abc123 \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "email": "billing@customer.com", "is_primary": true },
      { "email": "finance@customer.com", "is_primary": false }
    ]
  }'

import os

import requests

response = requests.patch(
    "https://api.alguna.io/customers/cust_abc123",
    headers={
        "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
        "Alguna-Version": "2026-04-01",
        "Content-Type": "application/json",
    },
    json={
        "contacts": [
            {"email": "billing@customer.com", "is_primary": True},
            {"email": "finance@customer.com", "is_primary": False},
        ]
    },
    timeout=10,
)
response.raise_for_status()

await alguna.customers.update("cust_abc123", {
  contacts: [
    { email: "billing@customer.com", is_primary: true },
    { email: "finance@customer.com", is_primary: false },
  ],
});

PATCH /customers/{id} also accepts name, currency, aliases, and billing_address. See Update a customer and Customer Contacts.

AutoPay

AutoPay charges the customer’s default saved payment method when an invoice is issued, instead of waiting for them to pay. It is the subscription’s billing.auto_pay_invoices flag, with a plan-level default in invoice_settings.auto_pay_invoices; the dashboard also exposes it on the customer’s billing settings. Set it through the API on the subscription:

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_pay_invoices": true } }'

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_pay_invoices": True}},
    timeout=10,
)
response.raise_for_status()

In the dashboard: Customers → [Customer] → Billing Settings, toggle AutoPay and pick the default payment method; or override per subscription in its Invoicing Settings. Customers can manage it themselves in the customer portal when you allow allow_autopay_edit. AutoPay needs a saved payment method. GET /invoices?autopay=true lists the invoices that will be collected this way.

Payment methods

A customer’s saved payment methods are held by your payment processor and referenced by Alguna. The kinds Alguna recognises are:

Kind	Auto-collect	Notes
`payment_card`	Yes	Credit and debit cards
`bank_transfer`	Depends on the rail	Bank debit rails supported by your processor, such as ACH; see ACH
`stripe_link`	Yes	Stripe Link
`wallet`	Yes	A prepaid wallet in the invoice currency
`offline_payment`	No	Wire, cheque, or cash recorded after the fact

Save a payment method without charging

Create a checkout session with checkout_intent: "vault" and no plan_id, line_items, or amount. The customer enters their details on the hosted page (or embedded in your product); the method is vaulted against the customer and becomes available for AutoPay.

curl https://api.alguna.io/checkout-sessions \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_abc123",
    "checkout_intent": "vault",
    "success_url": "https://yourapp.com/billing"
  }'

import os

import requests

response = requests.post(
    "https://api.alguna.io/checkout-sessions",
    headers={
        "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
        "Alguna-Version": "2026-04-01",
        "Content-Type": "application/json",
    },
    json={
        "customer_id": "cust_abc123",
        "checkout_intent": "vault",
        "success_url": "https://yourapp.com/billing",
    },
    timeout=10,
)
response.raise_for_status()
print(response.json()["url"])  # send the customer here

const session = await alguna.checkoutSessions.create({
  customer_id: "cust_abc123",
  checkout_intent: "vault",
  success_url: "https://yourapp.com/billing",
});

See Create a checkout session.

Customer portal

The hosted portal lets customers see their invoices, download PDFs, pay outstanding balances, and update billing details and payment methods. Mint a session and redirect the customer to its url. Sessions expire — check expires_at and create a fresh one rather than storing the URL.

curl https://api.alguna.io/customer-portal-sessions \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{ "customer_id": "cust_abc123" }'

import os

import requests

response = requests.post(
    "https://api.alguna.io/customer-portal-sessions",
    headers={
        "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
        "Alguna-Version": "2026-04-01",
        "Content-Type": "application/json",
    },
    json={"customer_id": "cust_abc123"},
    timeout=10,
)
response.raise_for_status()

session = response.json()
print(session["url"], session["expires_at"])

const session = await alguna.portal.createSession({ customer_id: "cust_abc123" });
console.log(session.url);

Pass customer_alias instead of customer_id to address the customer by your own ID. Each section — plan overview, invoice list, billing details — can be shown or hidden per session. See Customer Portal and Create a customer portal session.

Record an external payment

When a customer pays outside Alguna, mark the invoice paid so the balance, status, and revenue reporting stay right. external_payment_source is required; amount_paid defaults to the full total and paid_date to today. The invoice becomes paid when the balance reaches zero.

curl -X POST https://api.alguna.io/invoices/inv_abc123/mark-as-paid \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_paid": "1500.00",
    "paid_date": "2026-01-20T00:00:00Z",
    "external_payment_source": "bank_transfer",
    "external_payment_note": "Wire ref: 12345"
  }'

import os

import requests

response = requests.post(
    "https://api.alguna.io/invoices/inv_abc123/mark-as-paid",
    headers={
        "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
        "Alguna-Version": "2026-04-01",
        "Content-Type": "application/json",
    },
    json={
        "amount_paid": "1500.00",
        "paid_date": "2026-01-20T00:00:00Z",
        "external_payment_source": "bank_transfer",
        "external_payment_note": "Wire ref: 12345",
    },
    timeout=10,
)
response.raise_for_status()
print(response.json()["status"], response.json()["amount_remaining"])

await alguna.invoices.markAsPaid("inv_abc123", {
  amount_paid: "1500.00",
  paid_date: "2026-01-20T00:00:00Z",
  external_payment_source: "bank_transfer",
  external_payment_note: "Wire ref: 12345",
});

external_payment_source accepts bank_transfer, cheque, payment_card, cash, or other. See Mark an invoice as paid.

Reading payments

Payments are read-only in the public API. Each payment carries amount, amount_received, amount_refunded, status, processor references (external_id, external_url), and allocations — the per-invoice split of the money, with reversed set when an invoice was reopened. Filter by customer_id or invoice_id.

curl "https://api.alguna.io/payments?invoice_id=inv_abc123&limit=20&offset=0" \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01"

import os

import requests

response = requests.get(
    "https://api.alguna.io/payments",
    headers={
        "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
        "Alguna-Version": "2026-04-01",
    },
    params={"invoice_id": "inv_abc123", "limit": 20, "offset": 0},
    timeout=10,
)
response.raise_for_status()

for payment in response.json()["data"]:
    print(payment["id"], payment["status"], payment["amount"], payment["allocations"])

const payments = await alguna.payments.list({ invoice_id: "inv_abc123", limit: 20, offset: 0 });

Payment status values are pending_client_action, pending_authorization, processing, completed, failed, and voided. See List payments and Get a payment. Money going the other way is a refund. On the invoice itself, amount_paid and amount_remaining track collection against total, and GET /invoices filters on paid_date_gte / paid_date_lte.

Webhooks

Event	Fires when
`invoice.issued`	The invoice was finalized and delivered
`invoice.paid`	The invoice balance reached zero
`payment.created`	A payment attempt started
`payment.updated`	A payment changed status — including `failed`
`refund.updated`	A refund changed status

Payloads are camelCase. See Webhooks for shapes and the webhooks quick start for a handler.

When payment fails or is late

A failed charge emits a payment_failed automation trigger. The built-in Failed Payment Notification automation emails the customer a link to update their payment method; you can add retries and reminders. See Dunning.
An issued invoice past its due date becomes overdue and the Overdue Invoice Reminder automation sends reminders. See Collections.
Reminders before the due date come from the Invoices Due Reminders automation, and one-off reminders from the send_invoice_reminder action. See Automations.

None of this is configurable through the public API; it is set up on the Automations page.

Next steps

Dunning

Recover failed payments automatically.

Refunds

Return money against a payment.

Wallets

Let customers prepay and settle invoices from a balance.

Customer Portal

Configure the self-service portal.

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 customer sees

Who receives invoices

AutoPay

Payment methods

Save a payment method without charging

Customer portal

Record an external payment

Reading payments

Webhooks

When payment fails or is late

Next steps

Dunning

Refunds

Wallets

Customer Portal

​What the customer sees

​Who receives invoices

​AutoPay

​Payment methods

​Save a payment method without charging

​Customer portal

​Record an external payment

​Reading payments

​Webhooks

​When payment fails or is late

​Next steps

Dunning

Refunds

Wallets

Customer Portal

What the customer sees

Who receives invoices

AutoPay

Payment methods

Save a payment method without charging

Customer portal

Record an external payment

Reading payments

Webhooks

When payment fails or is late

Next steps