# Invoices

> Create, finalize, pay, void, and list invoices for customers.

An invoice collects line items and billing details for a customer, moving through a lifecycle from
draft to open to paid (or voided). VINR can advance invoices automatically or give you full manual
control over each transition.

> **Illustrative content.** Hand-authored to demonstrate the Standard/Advanced pattern; the production
> page will be generated from the VINR OpenAPI spec (roadmap item #1). Field names are representative.

## The invoice object

- **id** `string` — Unique identifier for the invoice, e.g. `inv_4Xk9b3Mw`.
- **customer** `object` (expandable) — The customer this invoice belongs to. Expand to retrieve the full object.
  - **id** `string` — Customer identifier, e.g. `cust_8aZ2`.
  - **email** `string` — Email address on the customer record.
- **status** `enum` — One of `draft`, `open`, `paid`, `void`, or `uncollectible`.
- **amount\_due** `integer` — Total amount due, in the smallest currency unit (e.g. cents).
- **amount\_paid** `integer` — Amount already collected, in the smallest currency unit.
- **currency** `string` — Three-letter [ISO currency code](/docs/payments/payment-methods), e.g. `EUR`.
- **due\_date** `integer` — Unix timestamp of when payment is due, if set.
- **lines** `array` — Array of line items included in the invoice. Each item has `id`, `description`, `amount`, and `quantity`.
- **created** `integer` — Unix timestamp of when the invoice was created.

## Create an invoice

Creates a draft invoice for a customer. Set `auto_advance: true` to let VINR automatically finalize
and attempt payment when the invoice is ready.

`POST /v1/invoices`

```bash
curl -X POST https://api.vinr.com/v1/invoices \
-H "X-Api-Key: $VINR_SECRET_KEY" \
-d customer=cust_8aZ2 \
-d auto_advance=true
```

```js
import { Vinr } from '@vinr/sdk';

const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

const invoice = await vinr.invoices.create({
customer: 'cust_8aZ2',
auto_advance: true,
});
```

```python
import vinr

invoice = vinr.Invoice.create(
  customer="cust_8aZ2",
  auto_advance=True,
)
```

```ruby
invoice = Vinr::Invoice.create(
customer: 'cust_8aZ2',
auto_advance: true,
)
```

```json
{
"id": "inv_4Xk9b3Mw",
"customer": "cust_8aZ2",
"status": "draft",
"amount_due": 0,
"amount_paid": 0,
"currency": "EUR",
"due_date": null,
"lines": [],
"created": 1716300000
}
```

## Retrieve an invoice

`GET /v1/invoices/{id}`

```bash
curl https://api.vinr.com/v1/invoices/inv_4Xk9b3Mw \
-H "X-Api-Key: $VINR_SECRET_KEY"
```

```js
const invoice = await vinr.invoices.retrieve('inv_4Xk9b3Mw');
```

```python
invoice = vinr.Invoice.retrieve("inv_4Xk9b3Mw")
```

```ruby
invoice = Vinr::Invoice.retrieve('inv_4Xk9b3Mw')
```

```json
{
"id": "inv_4Xk9b3Mw",
"customer": "cust_8aZ2",
"status": "open",
"amount_due": 5000,
"amount_paid": 0,
"currency": "EUR",
"due_date": 1716386400,
"lines": [
  {
    "id": "ii_7Yz1c4Nq",
    "description": "Consulting services — May 2026",
    "amount": 5000,
    "quantity": 1
  }
],
"created": 1716300000
}
```

## Update an invoice

Updates a draft invoice. Only `description` and `footer` may be modified after finalization.

`POST /v1/invoices/{id}`

```bash
curl -X POST https://api.vinr.com/v1/invoices/inv_4Xk9b3Mw \
-H "X-Api-Key: $VINR_SECRET_KEY" \
-d description="May 2026 services" \
-d footer="Thank you for your business."
```

```js
const invoice = await vinr.invoices.update('inv_4Xk9b3Mw', {
description: 'May 2026 services',
footer: 'Thank you for your business.',
});
```

```python
invoice = vinr.Invoice.modify(
  "inv_4Xk9b3Mw",
  description="May 2026 services",
  footer="Thank you for your business.",
)
```

```ruby
invoice = Vinr::Invoice.update(
'inv_4Xk9b3Mw',
description: 'May 2026 services',
footer: 'Thank you for your business.',
)
```

```json
{
"id": "inv_4Xk9b3Mw",
"status": "draft",
"description": "May 2026 services",
"footer": "Thank you for your business.",
"amount_due": 5000,
"currency": "EUR",
"created": 1716300000
}
```

## Finalize an invoice

Moves a draft invoice to `open`, making it ready for payment. Once finalized, line items are locked.

`POST /v1/invoices/{id}/finalize`

```bash
curl -X POST https://api.vinr.com/v1/invoices/inv_4Xk9b3Mw/finalize \
-H "X-Api-Key: $VINR_SECRET_KEY"
```

```js
const invoice = await vinr.invoices.finalize('inv_4Xk9b3Mw');
```

```python
invoice = vinr.Invoice.finalize("inv_4Xk9b3Mw")
```

```ruby
invoice = Vinr::Invoice.finalize('inv_4Xk9b3Mw')
```

```json
{
"id": "inv_4Xk9b3Mw",
"status": "open",
"amount_due": 5000,
"amount_paid": 0,
"currency": "EUR",
"created": 1716300000
}
```

## Pay an invoice

Charges the customer's default payment method and transitions the invoice to `paid`.

`POST /v1/invoices/{id}/pay`

```bash
curl -X POST https://api.vinr.com/v1/invoices/inv_4Xk9b3Mw/pay \
-H "X-Api-Key: $VINR_SECRET_KEY"
```

```js
const invoice = await vinr.invoices.pay('inv_4Xk9b3Mw');
```

```python
invoice = vinr.Invoice.pay("inv_4Xk9b3Mw")
```

```ruby
invoice = Vinr::Invoice.pay('inv_4Xk9b3Mw')
```

```json
{
"id": "inv_4Xk9b3Mw",
"status": "paid",
"amount_due": 5000,
"amount_paid": 5000,
"currency": "EUR",
"created": 1716300000
}
```

## Void an invoice

Cancels an open invoice. A voided invoice cannot be re-opened or paid.

`POST /v1/invoices/{id}/void`

```bash
curl -X POST https://api.vinr.com/v1/invoices/inv_4Xk9b3Mw/void \
-H "X-Api-Key: $VINR_SECRET_KEY"
```

```js
const invoice = await vinr.invoices.void('inv_4Xk9b3Mw');
```

```python
invoice = vinr.Invoice.void("inv_4Xk9b3Mw")
```

```ruby
invoice = Vinr::Invoice.void('inv_4Xk9b3Mw')
```

```json
{
"id": "inv_4Xk9b3Mw",
"status": "void",
"amount_due": 5000,
"amount_paid": 0,
"currency": "EUR",
"created": 1716300000
}
```

## List invoices

Returns invoices for your account, optionally filtered by customer or status.

`GET /v1/invoices`

```bash
curl "https://api.vinr.com/v1/invoices?customer=cust_8aZ2&status=open&limit=10" \
-H "X-Api-Key: $VINR_SECRET_KEY"
```

```js
const invoices = await vinr.invoices.list({
customer: 'cust_8aZ2',
status: 'open',
limit: 10,
});
```

```python
invoices = vinr.Invoice.list(
  customer="cust_8aZ2",
  status="open",
  limit=10,
)
```

```ruby
invoices = Vinr::Invoice.list(
customer: 'cust_8aZ2',
status: 'open',
limit: 10,
)
```

```json
{
"object": "list",
"data": [
  {
    "id": "inv_4Xk9b3Mw",
    "customer": "cust_8aZ2",
    "status": "open",
    "amount_due": 5000,
    "amount_paid": 0,
    "currency": "EUR",
    "created": 1716300000
  }
],
"has_more": false
}
```

## Related events

`invoice.created`, `invoice.finalized`, `invoice.payment_succeeded`, `invoice.payment_failed`, and
`invoice.voided`. See [Events](/docs/api-reference/events).