Skip to main content

​
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.
​
Authorization
string
required
Bearer token with billing.read scope
​
per_page
integer
default:"25"
Number of invoices per page (max 100)
​
page
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": "[email protected]",
          "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.
​
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": "[email protected]",
      "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

FieldTypeDescription
total_invoicesintegerTotal number of invoices
pending_invoicesintegerInvoices awaiting payment
paid_invoicesintegerFully paid invoices
overdue_invoicesintegerInvoices past due date
total_outstandingdecimalSum of all unpaid invoices
total_overduedecimalSum 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": "[email protected]",
        "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.
​
Authorization
string
required
Bearer token with billing.write scope
POST /api/v1/invoices

​
Request Body

​
customer_id
integer
required
The ID of an existing customer
​
invoice_number
string
Custom invoice number (auto-generated if not provided)
​
reference
string
Your internal reference (e.g., project name, PO number)
​
date
string
required
Invoice date in YYYY-MM-DD format
​
due_date
string
required
Due date in YYYY-MM-DD format (must be on or after invoice date)
​
notes
string
Additional notes to include on the invoice
​
items
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:
FieldTypeRequiredDescription
descriptionstringYesLine item description
quantitydecimalYesQuantity (min: 0.01)
unit_pricedecimalYesPrice per unit
tax_ratedecimalNoTax percentage (default: 0)

​
Send Payment Reminder

Send a payment reminder email for an unpaid invoice.
​
Authorization
string
required
Bearer token with billing.write scope
​
invoice
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

StatusDescription
draftInvoice created but not finalized
pendingInvoice created, awaiting payment
sentInvoice emailed to customer
viewedCustomer has viewed the invoice
paidInvoice fully paid
partialInvoice partially paid
overduePayment past due date
cancelledInvoice 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
  };
}