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

# Invoices

> Create, retrieve, and manage invoices via the API

# Invoice Endpoints

Manage your invoices programmatically with these endpoints. All endpoints require authentication and the appropriate OAuth scope.

## List All Invoices

Retrieve a paginated list of all your invoices.

<ParamField header="Authorization" type="string" required>
  Bearer token with `billing.read` scope
</ParamField>

<ParamField query="per_page" type="integer" default="25">
  Number of invoices per page (max 100)
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number for pagination
</ParamField>

```bash theme={null}
GET /api/v1/invoices
```

### Request Example

```bash theme={null}
curl -X GET "https://payrequest.app/api/v1/invoices?per_page=10&page=1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
```

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "current_page": 1,
    "data": [
      {
        "id": 1234,
        "invoice_number": "INV-000042",
        "reference": "Project Alpha",
        "amount": 1250.00,
        "currency": "EUR",
        "status": "pending",
        "date": "2025-01-15",
        "due_date": "2025-01-30",
        "customer": {
          "id": 567,
          "name": "Acme Corp",
          "email": "billing@acme.com",
          "company": "Acme Corporation"
        },
        "invoice_items": [
          {
            "description": "Web Development Services",
            "quantity": 40,
            "unit_price": 25.00,
            "tax_rate": 21,
            "total": 1000.00
          }
        ]
      }
    ],
    "per_page": 10,
    "total": 150,
    "last_page": 15
  }
}
```

***

## Get Invoice Details

Retrieve detailed information about a specific invoice.

<ParamField path="invoice" type="integer" required>
  The invoice ID
</ParamField>

```bash theme={null}
GET /api/v1/invoices/{invoice}
```

### Request Example

```bash theme={null}
curl -X GET "https://payrequest.app/api/v1/invoices/1234" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
```

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "id": 1234,
    "invoice_number": "INV-000042",
    "reference": "Project Alpha",
    "amount": 1250.00,
    "currency": "EUR",
    "status": "pending",
    "date": "2025-01-15",
    "due_date": "2025-01-30",
    "notes": "Payment terms: Net 15",
    "customer": {
      "id": 567,
      "name": "Acme Corp",
      "email": "billing@acme.com",
      "company": "Acme Corporation",
      "phone": "+31 20 123 4567",
      "address": "123 Business Street",
      "city": "Amsterdam",
      "postal_code": "1012 AB",
      "country": "Netherlands"
    },
    "invoice_items": [...],
    "transactions": [...],
    "subscription": null
  }
}
```

***

## Get Invoice Statistics

Get aggregated statistics about your invoices.

```bash theme={null}
GET /api/v1/invoices/stats
```

### Request Example

```bash theme={null}
curl -X GET "https://payrequest.app/api/v1/invoices/stats" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
```

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "total_invoices": 150,
    "pending_invoices": 23,
    "paid_invoices": 120,
    "overdue_invoices": 7,
    "total_outstanding": 15750.00,
    "total_overdue": 4200.00,
    "currency": "EUR"
  }
}
```

### Response Fields

| Field               | Type    | Description                |
| ------------------- | ------- | -------------------------- |
| `total_invoices`    | integer | Total number of invoices   |
| `pending_invoices`  | integer | Invoices awaiting payment  |
| `paid_invoices`     | integer | Fully paid invoices        |
| `overdue_invoices`  | integer | Invoices past due date     |
| `total_outstanding` | decimal | Sum of all unpaid invoices |
| `total_overdue`     | decimal | Sum of overdue invoices    |

***

## Get Overdue Invoices

Retrieve all invoices that are past their due date. Ideal for payment follow-up automation and AI billing agents.

```bash theme={null}
GET /api/v1/invoices/overdue
```

### Request Example

```bash theme={null}
curl -X GET "https://payrequest.app/api/v1/invoices/overdue" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
```

### Response

```json theme={null}
{
  "success": true,
  "count": 7,
  "total_outstanding": 4200.00,
  "currency": "EUR",
  "data": [
    {
      "id": 1230,
      "invoice_number": "INV-000038",
      "reference": "Maintenance Q4",
      "amount": 600.00,
      "currency": "EUR",
      "status": "sent",
      "date": "2024-12-01",
      "due_date": "2024-12-15",
      "days_overdue": 45,
      "customer": {
        "id": 890,
        "name": "TechStart BV",
        "email": "finance@techstart.nl",
        "phone": "+31 20 987 6543"
      },
      "payment_link": "https://payrequest.me/yourshop/invoice/1230"
    }
  ]
}
```

<Tip>
  The `payment_link` field contains a direct link you can share with the customer. It's `null` if a payment has already been initiated.
</Tip>

***

## Create Invoice

Create a new invoice with line items.

<ParamField header="Authorization" type="string" required>
  Bearer token with `billing.write` scope
</ParamField>

```bash theme={null}
POST /api/v1/invoices
```

### Request Body

<ParamField body="customer_id" type="integer" required>
  The ID of an existing customer
</ParamField>

<ParamField body="invoice_number" type="string">
  Custom invoice number (auto-generated if not provided)
</ParamField>

<ParamField body="reference" type="string">
  Your internal reference (e.g., project name, PO number)
</ParamField>

<ParamField body="date" type="string" required>
  Invoice date in `YYYY-MM-DD` format
</ParamField>

<ParamField body="due_date" type="string" required>
  Due date in `YYYY-MM-DD` format (must be on or after invoice date)
</ParamField>

<ParamField body="notes" type="string">
  Additional notes to include on the invoice
</ParamField>

<ParamField body="items" type="array" required>
  Array of invoice line items (minimum 1 item)
</ParamField>

### Request Example

```bash theme={null}
curl -X POST "https://payrequest.app/api/v1/invoices" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": 567,
    "reference": "Project Beta",
    "date": "2025-01-29",
    "due_date": "2025-02-13",
    "notes": "Thank you for your business!",
    "items": [
      {
        "description": "Consulting Services",
        "quantity": 8,
        "unit_price": 150.00,
        "tax_rate": 21
      },
      {
        "description": "Software License",
        "quantity": 1,
        "unit_price": 500.00,
        "tax_rate": 21
      }
    ]
  }'
```

### Response

```json theme={null}
{
  "success": true,
  "message": "Invoice created successfully",
  "data": {
    "id": 1235,
    "invoice_number": "INV-000043",
    "reference": "Project Beta",
    "amount": 1700.00,
    "currency": "EUR",
    "status": "pending",
    "date": "2025-01-29",
    "due_date": "2025-02-13",
    "customer": {...},
    "invoice_items": [...]
  }
}
```

**HTTP Status**: `201 Created`

### Item Structure

Each item in the `items` array should have:

| Field         | Type    | Required | Description                 |
| ------------- | ------- | -------- | --------------------------- |
| `description` | string  | Yes      | Line item description       |
| `quantity`    | decimal | Yes      | Quantity (min: 0.01)        |
| `unit_price`  | decimal | Yes      | Price per unit              |
| `tax_rate`    | decimal | No       | Tax percentage (default: 0) |

***

## Send Payment Reminder

Send a payment reminder email for an unpaid invoice.

<ParamField header="Authorization" type="string" required>
  Bearer token with `billing.write` scope
</ParamField>

<ParamField path="invoice" type="integer" required>
  The invoice ID
</ParamField>

```bash theme={null}
POST /api/v1/invoices/{invoice}/reminder
```

### Request Example

```bash theme={null}
curl -X POST "https://payrequest.app/api/v1/invoices/1230/reminder" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
```

### Response

```json theme={null}
{
  "success": true,
  "message": "Invoice reminder sent successfully"
}
```

### Error Responses

**Invoice already paid:**

```json theme={null}
{
  "success": false,
  "error": "Invoice is already paid"
}
```

**HTTP Status**: `400 Bad Request`

**Invoice not found:**

```json theme={null}
{
  "success": false,
  "error": "Invoice not found"
}
```

**HTTP Status**: `404 Not Found`

***

## Invoice Statuses

| Status      | Description                       |
| ----------- | --------------------------------- |
| `draft`     | Invoice created but not finalized |
| `pending`   | Invoice created, awaiting payment |
| `sent`      | Invoice emailed to customer       |
| `viewed`    | Customer has viewed the invoice   |
| `paid`      | Invoice fully paid                |
| `partial`   | Invoice partially paid            |
| `overdue`   | Payment past due date             |
| `cancelled` | Invoice cancelled                 |

***

## MCP Integration Example

Here's how to use the invoice API with an MCP billing agent:

```typescript theme={null}
// MCP Server Tool Definition
{
  name: "get_overdue_invoices",
  description: "Get all overdue invoices that need follow-up",
  inputSchema: {
    type: "object",
    properties: {}
  }
}

// Tool Implementation
async function getOverdueInvoices() {
  const response = await fetch(
    'https://payrequest.app/api/v1/invoices/overdue',
    {
      headers: {
        'Authorization': `Bearer ${process.env.PAYREQUEST_TOKEN}`,
        'Accept': 'application/json'
      }
    }
  );

  const data = await response.json();

  return {
    content: [{
      type: 'text',
      text: `Found ${data.count} overdue invoices totaling €${data.total_outstanding}`
    }],
    invoices: data.data
  };
}
```