/invoicing

name: "Alternative Payments Invoicing"
description: >
  Alternative Payments invoices and hosted payment requests: invoice status
  and line-item fields, hosted payment links and signed PDF links,
  archiving, and payment-request creation and retrieval. Hosted links let
  the customer choose to pay; the integration never moves money on the
  customer's behalf.
when_to_use: >-
  When creating, listing, retrieving, or archiving Alternative Payments invoices, or generating
  hosted payment links and payment requests. Use when: alternative payments invoice, create
  invoice, list invoices, archive invoice, payment link, payment request, hosted payment link,
  invoice pdf, line items, or alternativepayments invoice.

Alternative Payments Invoicing

Overview

Invoices are the billing records in Alternative Payments. Each invoice belongs to a customer, carries one or more line items, and has a due date. Once an invoice exists you can fetch a **hosted payment link** (a URL the customer visits to pay) and a **PDF link** (a signed download of the invoice document).

Separately, **payment requests** are standalone hosted payment links that are not tied to a stored invoice — useful for ad-hoc charges and follow-ups.

The key posture: hosted payment links and payment requests let the **customer** choose to pay. Generating a link does **not** charge a card or move money — it simply produces a URL. This integration never executes a direct charge. See [Alternative Payments API Patterns](../api-patterns/SKILL.md) for why `POST /payments` (direct charge) is excluded by design.

Anti-triggers

• **The invoice as an accounting document** — these invoices are collection

artefacts with no GL coding, tax treatment, or aging; use `xero-invoices` or `qbo-invoices`.

• **Whether the invoice was paid and where the money settled** — use

`alternative-payments-payments`.

• **Charging a card or bank account directly** — no such tool exists here by

design; a hosted link is the only collection mechanism, and the reasoning is in `alternative-payments-api-patterns`.

Core Concepts

Invoice Status

| Status | Description | Payable | |--------|-------------|---------| | `open` | Issued and awaiting payment | Yes | | `paid` | Fully paid | No | | `overdue` | Past `due_date` and still unpaid | Yes | | `archived` | Removed from default lists (destructive) | No |

Archiving uses `DELETE /invoices/{id}` and is destructive — confirm before running.

Hosted Links vs. Direct Charges

| Mechanism | What it does | Money movement | |-----------|--------------|----------------| | Payment link (`GET /invoices/{id}/payment-link`) | URL for an existing invoice | Customer pays — not the integration | | Payment request (`POST /payments/request`) | Standalone hosted link | Customer pays — not the integration | | Direct charge (`POST /payments`) | Charges a card/bank | **Not exposed** |

Field Reference

Invoice Fields

| Field | Type | Required | Description | |-------|------|----------|-------------| | `id` | string | System | Auto-generated unique identifier | | `customer_id` | string | Yes | Customer the invoice belongs to | | `currency` | string | Yes | ISO currency code (e.g. `USD`) | | `due_date` | string | Yes | Payment due date (`YYYY-MM-DD`) | | `line_items` | array | Yes | One or more line items (see below) | | `reference` | string | No | Reference text (PO number, billing period) | | `status` | string | Read-only | `open`, `paid`, `overdue`, `archived` | | `amount_due` | number | Read-only | Remaining unpaid amount | | `created_at` | datetime | Read-only | Creation timestamp |

Line Item Fields

| Field | Type | Required | Description | |-------|------|----------|-------------| | `description` | string | Yes | Line item description | | `quantity` | number | Yes | Quantity | | `unit_amount` | number | Yes | Price per unit |

Payment Request Fields

| Field | Type | Required | Description | |-------|------|----------|-------------| | `amount` | number | Yes | Amount to request | | `currency` | string | Yes | ISO currency code (e.g. `USD`) | | `redirect_url` | string | Yes | Where to send the customer after paying | | `reference_id` | string | No | Your reference for reconciliation |

API Patterns

All requests carry a bearer token (`Authorization: Bearer <token>`). See [Alternative Payments API Patterns](../api-patterns/SKILL.md) for the OAuth2 token flow, the 5 req/sec rate limit, and cursor pagination.

List Invoices

curl -s "https://public-api.alternativepayments.io/invoices?limit=100" \
  -H "Authorization: Bearer ${TOKEN}"

Responses are cursor-paginated — items in `data[]`, with `next_cursor` / `has_more`. Pass `after=<cursor>` for the next page.

Get a Single Invoice

curl -s "https://public-api.alternativepayments.io/invoices/${INVOICE_ID}" \
  -H "Authorization: Bearer ${TOKEN}"

Create an Invoice

Required: `customer_id`, `currency`, `due_date`, and a non-empty `line_items[]`.

curl -s -X POST "https://public-api.alternativepayments.io/invoices" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "'${CUSTOMER_ID}'",
    "currency": "USD",
    "due_date": "2026-07-05",
    "reference": "June 2026 Managed Services",
    "line_items": [
      {
        "description": "Monthly Managed Services - Acme Corp (25 endpoints)",
        "quantity": 1,
        "unit_amount": 2500.00
      },
      {
        "description": "Microsoft 365 Business Premium (25 users)",
        "quantity": 25,
        "unit_amount": 22.00
      }
    ]
  }'

Get a Hosted Payment Link

Returns a URL the customer visits to pay the invoice. No charge occurs until the customer completes payment.

curl -s "https://public-api.alternativepayments.io/invoices/${INVOICE_ID}/payment-link" \
  -H "Authorization: Bearer ${TOKEN}"

Get a Signed PDF Link

curl -s "https://public-api.al