Fetch Invoices

List the invoices of the authenticated account with the summary tiles — pending, paid and overdue totals.

POST https://api-v3.sweeppea.com/invoices/fetch

Description

This endpoint returns a paginated list of invoices together with the summary totals rendered above the Invoices dashboard. The summary always describes the whole filtered set, not just the page being returned: filtering by pending status and asking for page 3 still reports the total pending amount across every matching invoice. The IsOverdue flag is derived at read time and never stored — an invoice is overdue when it is still pending and its due date has passed.

Authentication

This endpoint requires Bearer token authentication via the Authorization header.

Request Body

Field	Type	Required	Description
`Status`	String	No	Filter by status: `draft`, `pending`, `paid` or `cancelled`
`FromDate`	String	No	ISO date (YYYY-MM-DD). Only invoices created on or after this day
`ToDate`	String	No	ISO date (YYYY-MM-DD). Only invoices created on or before this day
`Page`	Number	No	Page number (default: 1)
`Limit`	Number	No	Results per page (default: 50, maximum: 200)

Code Examples

curl -X POST "https://api-v3.sweeppea.com/invoices/fetch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "Status": "pending",
        "FromDate": "2026-01-01",
        "Page": 1,
        "Limit": 25
    }'

const response = await fetch('https://api-v3.sweeppea.com/invoices/fetch', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    Status: "pending",
    FromDate: "2026-01-01",
    Page: 1,
    Limit: 25
})
});

const data = await response.json();
console.log(data);

import requests

url = "https://api-v3.sweeppea.com/invoices/fetch"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "Status": "pending",
    "FromDate": "2026-01-01",
    "Page": 1,
    "Limit": 25
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Response

{
  "Response": true,
  "Telemetry": {
    "DataConsumed": 0,
    "APICalls": 149,
    "MaxAPICalls": 1500000
  },
  "Data": {
    "Invoices": [
      {
        "InvoiceToken": "uuid-v4-string",
        "PublicToken": "uuid-v4-string",
        "InvoiceNumber": "INV-2026-00042",
        "Title": "August retainer",
        "CreationDate": "2026-08-01T14:02:11.000Z",
        "IssueDate": "2026-08-01T00:00:00.000Z",
        "DueDate": "2026-08-16T00:00:00.000Z",
        "RecipientName": "Acme Corporation",
        "RecipientEmail": "billing@acme.example",
        "Currency": "USD",
        "Subtotal": 4500,
        "DiscountAmount": 0,
        "TaxEnabled": true,
        "TaxAmount": 382.5,
        "Total": 4882.5,
        "Status": "pending",
        "PaymentMethod": "card",
        "IsManualPayment": false,
        "IsOverdue": false,
        "DaysElapsed": 3,
        "DaysOverdue": 0,
        "Views": 2,
        "Notifications": 1,
        "LastViewDate": "2026-08-03T09:41:00.000Z",
        "LastNotificationDate": "2026-08-01T14:05:00.000Z",
        "PaidDate": null,
        "Archived": false,
        "ProcessingFeePercentage": 3,
        "MerchantFeePercentage": 3
      }
    ],
    "Summary": {
      "TotalPending": 12480.75,
      "TotalPaid": 38210,
      "CountPending": 4,
      "CountPaid": 11,
      "CountDraft": 2,
      "CountOverdue": 1,
      "CountTotal": 17
    },
    "Pagination": {
      "Page": 1,
      "Limit": 25,
      "TotalInvoices": 17,
      "TotalPages": 1
    }
  },
  "Message": "Invoices fetched successfully."
}

Error Responses

{
  "Response": false,
  "Message": "Invalid Status. Accepted values: draft, pending, paid, cancelled",
  "Code": 400,
  "Help": {
    "ExpectedBody": {
      "Status": "string (optional) \u2014 Filter by status: draft | pending | paid | cancelled"
    }
  }
}

{
  "Response": false,
  "Message": "Invalid FromDate. Use an ISO date such as 2026-01-31.",
  "Code": 400
}

{
  "Response": false,
  "Message": "Missing or invalid Bearer token. Send your API token in the Authorization header as: Authorization: Bearer YOUR_API_TOKEN",
  "Code": 401
}

{
  "Response": false,
  "Message": "Invalid API token. It does not match any account.",
  "Code": 403
}

{
  "Response": false,
  "Message": "Internal server error. Please try again; if it persists, contact support with the time of this request.",
  "Code": 500
}

Important Notes

🔒 Module Access: The Invoices module is disabled by default. An administrator must enable it for your account before any of these endpoints will respond
📊 Summary Scope: The summary totals cover the entire filtered set, never just the current page
⏰ Overdue Is Derived: IsOverdue is computed at read time from the due date — the stored status stays pending
🗂️ Archived Included: Archived invoices are returned with an Archived: true flag so you can filter them client-side
📄 Full Document: Line items, notes, terms, the event timeline and the QR code come from /invoices/single