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.

string

required

Bearer token with billing.read scope

integer

default:"25"

Number of invoices per page (max 100)

integer

default:"1"

Page number for pagination

GET /api/v1/invoices

Request Example

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

{
  "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.

integer

required

The invoice ID

GET /api/v1/invoices/{invoice}

Request Example

curl -X GET "https://payrequest.app/api/v1/invoices/1234" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Response

{
  "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.

GET /api/v1/invoices/stats

Request Example

curl -X GET "https://payrequest.app/api/v1/invoices/stats" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Response

{
  "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.

GET /api/v1/invoices/overdue

Request Example

curl -X GET "https://payrequest.app/api/v1/invoices/overdue" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Response

{
  "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"
    }
  ]
}

The payment_link field contains a direct link you can share with the customer. It’s null if a payment has already been initiated.

Create Invoice

Create a new invoice with line items.

string

required

Bearer token with billing.write scope

POST /api/v1/invoices

Request Body

integer

required

The ID of an existing customer

string

Custom invoice number (auto-generated if not provided)

string

Your internal reference (e.g., project name, PO number)

string

required

Invoice date in YYYY-MM-DD format

string

required

Due date in YYYY-MM-DD format (must be on or after invoice date)

string

Additional notes to include on the invoice

array

required

Array of invoice line items (minimum 1 item)

Request Example

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

{
  "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.

string

required

Bearer token with billing.write scope

integer

required

The invoice ID

POST /api/v1/invoices/{invoice}/reminder

Request Example

curl -X POST "https://payrequest.app/api/v1/invoices/1230/reminder" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

Response

{
  "success": true,
  "message": "Invoice reminder sent successfully"
}

Error Responses

Invoice already paid:

{
  "success": false,
  "error": "Invoice is already paid"
}

HTTP Status: 400 Bad Request Invoice not found:

{
  "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:

// 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
  };
}

​Invoice Endpoints

​List All Invoices

​Request Example

​Response

​Get Invoice Details

​Request Example

​Response

​Get Invoice Statistics

​Request Example

​Response

​Response Fields

​Get Overdue Invoices

​Request Example

​Response

​Create Invoice

​Request Body

​Request Example

​Response

​Item Structure

​Send Payment Reminder

​Request Example

​Response

​Error Responses

​Invoice Statuses

​MCP Integration Example

Invoice Endpoints

List All Invoices

Request Example

Response

Get Invoice Details

Request Example

Response

Get Invoice Statistics

Request Example

Response

Response Fields

Get Overdue Invoices

Request Example

Response

Create Invoice

Request Body

Request Example

Response

Item Structure

Send Payment Reminder

Request Example

Response

Error Responses

Invoice Statuses

MCP Integration Example