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

# Invoices

> Create and manage invoices for your account. Invoices represent billing documents sent to customers with line items for products and services.

This API allows you to create and manage invoices for your account. Invoices represent billing documents sent to customers with line items for products and services.

## The invoice object

<ResponseField name="id" type="string">
  Unique identifier with `inv_` prefix (e.g., `inv_abc123def456`).
</ResponseField>

<ResponseField name="customer_id" type="string">
  The customer's ID associated with this invoice.
</ResponseField>

<ResponseField name="subscription_id" type="string">
  The associated subscription ID. `null` for standalone invoices.
</ResponseField>

<ResponseField name="status" type="string">
  Invoice status: `pending`, `paid`, `overdue`, or `canceled`.
</ResponseField>

<ResponseField name="due_date" type="string">
  The invoice due date (format: `YYYY-MM-DD`).
</ResponseField>

<ResponseField name="total_amount" type="string">
  Total amount for the invoice.
</ResponseField>

<ResponseField name="line_items" type="array">
  Array of line items on the invoice.

  <Expandable title="line item properties">
    <ResponseField name="line_items[].id" type="string">
      Unique identifier for the line item.
    </ResponseField>

    <ResponseField name="line_items[].price_id" type="string">
      The price ID referenced by this line item.
    </ResponseField>

    <ResponseField name="line_items[].product_id" type="string">
      The product ID for this line item.
    </ResponseField>

    <ResponseField name="line_items[].product_name" type="string">
      The product name.
    </ResponseField>

    <ResponseField name="line_items[].quantity" type="integer">
      Quantity of this item.
    </ResponseField>

    <ResponseField name="line_items[].unit_amount" type="string">
      Price per unit.
    </ResponseField>

    <ResponseField name="line_items[].amount" type="string">
      Total amount for this line item (unit\_amount x quantity).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string">
  When the invoice was created (ISO 8601).
</ResponseField>

<ResponseField name="updated_at" type="string">
  When the invoice was last updated (ISO 8601).
</ResponseField>

## List invoices

```
GET /v1/invoices
```

Retrieves a paginated list of all invoices in your account.

<ParamField query="page" type="integer" default="1">
  Page number for pagination. Results are returned 25 items per page.
</ParamField>

```bash theme={null}
curl https://api.gettrxn.com/v1/invoices \
  -H "Authorization: Bearer $TRXN_TOKEN"
```

```json Response theme={null}
{
  "invoices": [
    {
      "id": "inv_abc123def456",
      "customer_id": "cus_xyz789",
      "subscription_id": null,
      "status": "pending",
      "due_date": "2025-02-28",
      "total_amount": "199.98",
      "created_at": "2025-01-15T12:00:00Z",
      "updated_at": "2025-01-15T12:00:00Z",
      "line_items": [
        {
          "id": "li_item123",
          "price_id": "pri_abc123",
          "product_id": "pro_xyz789",
          "product_name": "Premium Plan",
          "quantity": 2,
          "unit_amount": "99.99",
          "amount": "199.98"
        }
      ]
    }
  ],
  "pagination": {
    "page": 1,
    "pages": 3,
    "count": 67
  }
}
```

## Get invoice

```
GET /v1/invoices/:id
```

Retrieves a specific invoice by ID with all line items.

<ParamField path="id" type="string" required>
  The invoice's ID (e.g., `inv_abc123def456`).
</ParamField>

```bash theme={null}
curl https://api.gettrxn.com/v1/invoices/inv_abc123def456 \
  -H "Authorization: Bearer $TRXN_TOKEN"
```

```json Response theme={null}
{
  "id": "inv_abc123def456",
  "customer_id": "cus_xyz789",
  "subscription_id": "sub_def456",
  "status": "pending",
  "due_date": "2025-02-28",
  "total_amount": "99.99",
  "created_at": "2025-01-15T12:00:00Z",
  "updated_at": "2025-01-15T12:00:00Z",
  "line_items": [
    {
      "id": "li_item123",
      "price_id": "pri_abc123",
      "product_id": "pro_xyz789",
      "product_name": "Premium Plan",
      "quantity": 1,
      "unit_amount": "99.99",
      "amount": "99.99"
    }
  ]
}
```

## Create invoice

```
POST /v1/invoices
```

Creates a new invoice with optional line items.

<ParamField body="customer_id" type="string" required>
  The customer's ID (e.g., `cus_xyz789`). Must belong to your account.
</ParamField>

<ParamField body="due_date" type="string" required>
  The invoice due date (format: `YYYY-MM-DD`).
</ParamField>

<ParamField body="status" type="string" default="pending">
  Invoice status. One of: `pending`, `paid`, `overdue`, `canceled`.
</ParamField>

<ParamField body="subscription_id" type="string">
  Associated subscription ID.
</ParamField>

<ParamField body="line_items" type="array">
  Array of line item objects.

  <Expandable title="line item properties">
    <ParamField body="line_items[].price_id" type="string" required>
      The price ID for the line item. Must belong to your account.
    </ParamField>

    <ParamField body="line_items[].quantity" type="integer" default="1">
      Quantity for this line item.
    </ParamField>

    <ParamField body="line_items[].amount" type="string">
      Override amount for the line item.
    </ParamField>
  </Expandable>
</ParamField>

```bash theme={null}
curl -X POST https://api.gettrxn.com/v1/invoices \
  -H "Authorization: Bearer $TRXN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_xyz789",
    "due_date": "2025-02-28",
    "line_items": [
      {"price_id": "pri_abc123", "quantity": 2}
    ]
  }'
```

```json Response theme={null}
{
  "id": "inv_new123invoice456",
  "customer_id": "cus_xyz789",
  "subscription_id": null,
  "status": "pending",
  "due_date": "2025-02-28",
  "total_amount": "199.98",
  "created_at": "2025-01-15T14:30:00Z",
  "updated_at": "2025-01-15T14:30:00Z",
  "line_items": [
    {
      "id": "li_new123",
      "price_id": "pri_abc123",
      "product_id": "pro_xyz789",
      "product_name": "Premium Plan",
      "quantity": 2,
      "unit_amount": "99.99",
      "amount": "199.98"
    }
  ]
}
```

### Error responses

```json Customer not found theme={null}
{
  "error": "Customer not found"
}
```

```json Price not found theme={null}
{
  "error": "Price not found: pri_invalid123"
}
```

## Update invoice

```
PATCH /v1/invoices/:id
```

Updates an existing invoice's status or due date.

<ParamField path="id" type="string" required>
  The invoice's ID.
</ParamField>

<ParamField body="status" type="string">
  Invoice status. One of: `pending`, `paid`, `overdue`, `canceled`.
</ParamField>

<ParamField body="due_date" type="string">
  The invoice due date (format: `YYYY-MM-DD`).
</ParamField>

```bash theme={null}
curl -X PATCH https://api.gettrxn.com/v1/invoices/inv_abc123def456 \
  -H "Authorization: Bearer $TRXN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "paid"
  }'
```

```json Response theme={null}
{
  "id": "inv_abc123def456",
  "customer_id": "cus_xyz789",
  "status": "paid",
  "due_date": "2025-02-28",
  "total_amount": "99.99",
  "created_at": "2025-01-15T12:00:00Z",
  "updated_at": "2025-01-16T10:00:00Z",
  "line_items": [...]
}
```

## Delete invoice

```
DELETE /v1/invoices/:id
```

Deletes an invoice from your account.

<ParamField path="id" type="string" required>
  The invoice's ID.
</ParamField>

```bash theme={null}
curl -X DELETE https://api.gettrxn.com/v1/invoices/inv_abc123def456 \
  -H "Authorization: Bearer $TRXN_TOKEN"
```

Returns `204 No Content` on successful deletion.

## Invoice status values

| Status     | Description                                |
| ---------- | ------------------------------------------ |
| `pending`  | Invoice has been created but not yet paid. |
| `paid`     | Invoice has been fully paid.               |
| `overdue`  | Invoice is past its due date.              |
| `canceled` | Invoice has been canceled.                 |

## Usage flow

1. **Create a customer** using the Customers API.
2. **Create products and prices** using the Products and Prices APIs.
3. **Create an invoice** with line items referencing your prices.
4. **Send the invoice** to your customer (via your application).
5. **Update status to paid** when payment is received.
6. **Track overdue invoices** and follow up as needed.

## Integration example

```bash theme={null}
# 1. Create a customer
curl -X POST https://api.gettrxn.com/v1/customers \
  -H "Authorization: Bearer $TRXN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "customer@example.com"}'

# Response: {"id": "cus_abc123", ...}

# 2. Create an invoice for the customer
curl -X POST https://api.gettrxn.com/v1/invoices \
  -H "Authorization: Bearer $TRXN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cus_abc123",
    "due_date": "2025-02-28",
    "line_items": [
      {"price_id": "pri_monthly_plan", "quantity": 1}
    ]
  }'

# 3. Mark invoice as paid when payment received
curl -X PATCH https://api.gettrxn.com/v1/invoices/inv_xyz789 \
  -H "Authorization: Bearer $TRXN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "paid"}'
```

## Sandbox support

<Note>
  The API respects sandbox scoping. If your API token is associated with a sandbox, you can only access invoices created in that sandbox. Invoices created in sandbox mode will be isolated from production data.
</Note>