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 automatically, instead of waiting for them to pay. By default the charge happens when the invoice is issued; Autopay Timing can move it to the due date. 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: open Customers → [Customer] → Profile, edit the Business Information section to select Auto Pay, and choose Set to default on a saved payment method in the Stored Payment Methods section; 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.

Charge timing

Autopay Timing decides when AutoPay charges an invoice:

Value	Charge
`on_issue` (default)	The first AutoPay run after the invoice is issued.
`on_due_date`	The first AutoPay run on the invoice’s due date (UTC), before the invoice becomes overdue.

The value is copied at creation and resolved when the invoice is issued:

Organization: the default for new customers, under Settings → Workflows → Billing → Invoicing (see Invoicing Configuration).
Customer: autopay_timing on the customer (POST /customers, PATCH /customers/{id}). Always set; a new customer copies the organization value unless the request sets one.
Subscription: billing.autopay_timing on the subscription. A subscription created from a plan copies the plan’s value. Send billing.clear_autopay_timing: true to inherit the customer’s value again.
Invoice: autopay_timing on the invoice (POST /invoices, PATCH /invoices/{id}). Send clear_autopay_timing: true before issue to inherit the customer’s value at issue. Clearing it after issue makes the invoice eligible for the next AutoPay run, even if the customer uses on_due_date. It can change while the invoice is draft, upcoming, pending approval, issued, or overdue.

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 '{ "autopay_timing": "on_due_date" }'

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",
    },
    json={"autopay_timing": "on_due_date"},
    timeout=10,
)
response.raise_for_status()

Rules:

Before issue, autopay_timing is null when no invoice override is saved. A subscription copies its value to each new invoice; at issue, an invoice without a value uses the customer’s value.
When an invoice is issued, Alguna saves the resolved value on the invoice, and the invoice’s autopay_timing returns it. A later change on the customer, plan, or subscription does not move invoices that are already issued. A change on the invoice itself applies to the next AutoPay run.
The charge follows the due date. If you change the payment terms or the due date of an issued invoice, the charge moves with it.
An invoice with no due date (indefinite payment terms) and an invoice due on issue are charged when they are issued.
Wallet credits apply when the invoice is issued, in both modes.
Invoices issued before Autopay Timing existed have no value and are charged when they are issued.

While an on_due_date invoice waits for its charge, the customer sees it as scheduled:

The hosted invoice page shows Automatic payment scheduled with the card and the charge date. If the card has expired, or expires before the charge date, the page says so.
Pay now lets the customer pay before the charge date: Charge the card on file, or Use a different payment method in the checkout, where they can save the new method. After the customer pays, the automatic payment does not run.
The customer portal shows the invoice as Scheduled with its charge date.
The Invoices Due Reminders automation skips invoices that have an automatic payment scheduled.

If the charge fails, the usual dunning applies; its retries run after the invoice becomes overdue.

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. Invoices Due Reminders skips invoices that have an automatic payment scheduled. 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

Charge timing

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

​Charge timing

​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

Charge timing

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