> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talescria.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoices

> Issue invoices your customers pay by card, once or on a schedule.

An invoice is a numbered document sent to one of your [customers](https://docs.talescria.com/guides/customers.md) with a link to pay it by card. Talescria works out the totals, numbers it (`INV-0001`, `INV-0002`, …), emails it with a PDF, sends reminders, and emails a receipt when it's paid.

Scopes: `invoices:write` to issue, send and void; `invoices:read` to read. Both cover recurring series too.

Before your first invoice, complete your business details in the dashboard: they're printed on every invoice (`409 PROFILE_INCOMPLETE` otherwise).

## Issue an invoice

```bash curl theme={null}
curl https://api.talescria.com/v1/invoices \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: invoice-acme-nov" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cus_…",
    "accountId": "acct_01M2P8GP7RSDXN81CXRFM2HFV7",
    "dueAt": 1765497600000,
    "lines": [
      { "description": "Design sprint", "quantity": 1, "unitPrice": "250000" },
      { "description": "Workshop seats", "quantity": 4, "unitPrice": "4500" }
    ],
    "tax": { "label": "VAT 20%", "rateBasisPoints": 2000 },
    "memo": "Thanks for your business.",
    "poNumber": "PO-7731"
  }'
```

```python Python theme={null}
resp = requests.post(
    "https://api.talescria.com/v1/invoices",
    headers={"Authorization": f"Bearer {token}", "Idempotency-Key": "invoice-acme-nov"},
    json={
        "customerId": customer_id,
        "accountId": account_id,
        "dueAt": 1765497600000,
        "lines": [
            {"description": "Design sprint", "quantity": 1, "unitPrice": "250000"},
            {"description": "Workshop seats", "quantity": 4, "unitPrice": "4500"},
        ],
        "tax": {"label": "VAT 20%", "rateBasisPoints": 2000},
        "memo": "Thanks for your business.",
        "poNumber": "PO-7731",
    },
    timeout=30,
)
body = resp.json()
invoice, emailed = body["invoice"], body["emailed"]
```

**You send lines; Talescria computes the figures.** Each line is `quantity × unitPrice`, the subtotal is their sum, tax is the subtotal × `rateBasisPoints` / 10,000 rounded half up, and the total is subtotal + tax. In the example: £2,500.00 + £180.00 = £2,680.00 subtotal, £536.00 VAT, **£3,216.00** total.

| Field | Notes |
| - | - |
| `accountId` | Where the payment lands: one of your USD, GBP or EUR accounts that can take card payments. The invoice is in that account's currency. |
| `dueAt` | Epoch milliseconds. |
| `lines` | 1 to 100 lines. `unitPrice` is an integer string in minor units. |
| `tax` | Optional. One tax line: a label and a rate in basis points (`2000` = 20%). |
| `issuedAt` | Optional invoice date, epoch milliseconds. Defaults to now. |
| `servicePeriod` | Optional `{ "from", "to" }`, printed on the invoice. |
| `memo`, `poNumber` | Printed on the invoice. |
| `internalNote` | For you only. Never on the invoice. |
| `cc` | Who to copy, from the customer's `additionalEmails`. Leave it out to copy all of them. |
| `notify` | `false` issues the invoice without emailing it. |

The response includes `url`, the page where the customer views and pays the invoice (`https://pay.talescria.com/i/…`), and `emailed`. If the email couldn't be sent, the invoice still exists: resend it with `POST /v1/invoices/{id}/send`.

## Status

| `status` | Meaning |
| - | - |
| `unpaid` | Issued and not yet paid. |
| `overdue` | Unpaid past `dueAt`. Still payable. |
| `paid` | Paid. `paidAt` says when. |
| `void` | Withdrawn. Its page no longer takes payment. |

Reminders go out before and after the due date, and a receipt is emailed when the invoice is paid, if you've switched them on in your invoice settings.

## Correcting an invoice

An issued invoice never changes: your customer's records must match yours. To correct one, void it and issue a new one.

```bash theme={null}
curl -X POST https://api.talescria.com/v1/invoices/$INVOICE_ID/void \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

## Recurring invoices

A **series** issues an invoice to the same customer on a schedule.

```bash theme={null}
curl https://api.talescria.com/v1/invoice-series \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: series-acme-retainer" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cus_…",
    "accountId": "acct_01M2P8GP7RSDXN81CXRFM2HFV7",
    "frequency": "monthly",
    "startDate": "2026-12-01",
    "dueDays": 14,
    "notify": true,
    "template": {
      "lines": [{ "description": "Monthly retainer", "quantity": 1, "unitPrice": "150000" }],
      "tax": { "label": "VAT 20%", "rateBasisPoints": 2000 }
    }
  }'
```

* `frequency` is `weekly`, `biweekly`, `monthly` or `quarterly`. Add `endDate` to stop after a date.
* Each invoice is issued at **09:00 UTC** on its day and is due `dueDays` later.
* Monthly and quarterly series keep the start date's day of the month, moved earlier in shorter months: a series starting on the 31st issues on the 30th in November and the 28th in February.
* A series starting today issues its first invoice immediately and returns it as `invoice`. If that first invoice fails, the series is cancelled and you get the error.
* `GET /v1/invoice-series/{id}` shows the series, its `nextIssueAt`, and `lastError` if the latest issue failed.
* `POST /v1/invoice-series/{id}/cancel` stops it. Invoices already issued are unaffected.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.