Single Invoice

Retrieve one invoice in full — line items, totals, public payment link, QR code, statistics and event timeline.

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

Description

This endpoint returns everything about a single invoice in one call: the recipient, every line item, the computed totals, payment details, the public payment link, a ready-to-use QR code, view statistics, the event timeline and the modifications log. It intentionally replaces what would otherwise be three separate round trips.

Authentication

This endpoint requires Bearer token authentication via the Authorization header.

Request Body

Field	Type	Required	Description
`InvoiceToken`	String	Yes	UUID v4 of the invoice to read
`IncludeEvents`	Boolean	No	Include the event timeline (default: true)
`IncludeQrCode`	Boolean	No	Include the QR code as a data URL (default: true)

Code Examples

curl -X POST "https://api-v3.sweeppea.com/invoices/single" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "InvoiceToken": "uuid-v4-string",
        "IncludeEvents": true,
        "IncludeQrCode": true
    }'

const response = await fetch('https://api-v3.sweeppea.com/invoices/single', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    InvoiceToken: "uuid-v4-string",
    IncludeEvents: true,
    IncludeQrCode: true
})
});

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

import requests

url = "https://api-v3.sweeppea.com/invoices/single"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "InvoiceToken": "uuid-v4-string",
    "IncludeEvents": True,
    "IncludeQrCode": True
}

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

Response

{
  "Response": true,
  "Telemetry": {
    "DataConsumed": 0,
    "APICalls": 149,
    "MaxAPICalls": 1500000
  },
  "Data": {
    "Invoice": {
      "InvoiceToken": "uuid-v4-string",
      "PublicToken": "uuid-v4-string",
      "InvoiceNumber": "INV-2026-00042",
      "Title": "August retainer",
      "CreationDate": "2026-08-01T14:02:11.000Z",
      "UpdatedAt": "2026-08-02T10:00:00.000Z",
      "IssueDate": "2026-08-01T00:00:00.000Z",
      "DueDate": "2026-08-16T00:00:00.000Z",
      "Currency": "USD",
      "BillTo": {
        "Name": "Acme Corporation",
        "Email": "billing@acme.example",
        "Phone": "3055551234",
        "Company": "Acme Corp",
        "Address": "1 Main St",
        "City": "Miami",
        "State": "Florida",
        "ZipCode": "33101",
        "Country": "United States",
        "TaxId": "12-3456789"
      },
      "Items": [
        {
          "Id": "",
          "Description": "Consulting",
          "Quantity": 10,
          "Rate": 450,
          "Amount": 4500
        }
      ],
      "Subtotal": 4500,
      "DiscountAmount": 0,
      "TaxEnabled": true,
      "TaxLabel": "Sales Tax",
      "TaxRate": 8.5,
      "TaxAmount": 382.5,
      "Total": 4882.5,
      "Status": "pending",
      "PaymentMethod": "card",
      "PaymentInstructions": null,
      "NotesToRecipient": "Thank you for your business.",
      "Terms": "Net 15.",
      "ProcessingFeePercentage": 3,
      "MerchantFeePercentage": 3,
      "IsSandboxInvoice": false,
      "Archived": false
    },
    "Payment": {
      "IsPaid": false,
      "IsManualPayment": false,
      "PaidDate": null,
      "Method": null,
      "PayerName": null,
      "PayerEmail": null,
      "CCType": null,
      "CCLastFourDigits": null,
      "GrossAmount": null,
      "ProcessingFee": null,
      "NetAmount": null,
      "Reference": null
    },
    "PublicLink": "https://app.sweeppea.com/invoice?t=uuid-v4-string",
    "QrCode": "data:image/png;base64,...",
    "Stats": {
      "Views": 2,
      "UniqueViews": 1,
      "FirstViewDate": "2026-08-02T09:00:00.000Z",
      "LastViewDate": "2026-08-03T09:41:00.000Z",
      "Notifications": 1,
      "LastNotificationDate": "2026-08-01T14:05:00.000Z",
      "PaymentAttempts": 0,
      "FailedAttempts": 0
    },
    "Derived": {
      "IsOverdue": false,
      "DaysSinceIssued": 3,
      "DaysOverdue": 0,
      "DaysToPayment": null
    },
    "Events": {
      "Totals": {
        "created": 1,
        "viewed": 2,
        "notified": 1
      },
      "Timeline": [
        {
          "EventType": "viewed",
          "Description": "Invoice viewed by the recipient",
          "CreationDate": "2026-08-03T09:41:00.000Z",
          "IpAddress": "203.0.113.10",
          "Browser": "Chrome",
          "DeviceType": "desktop",
          "OperatingSystem": "macOS",
          "Referrer": ""
        }
      ]
    },
    "ModificationsLog": []
  },
  "Message": "Invoice fetched successfully."
}

Error Responses

{
  "Response": false,
  "Message": "Missing required parameter: InvoiceToken",
  "Code": 400,
  "Help": {
    "ExpectedBody": {
      "InvoiceToken": "string (required) \u2014 UUID v4 of the invoice to read",
      "IncludeEvents": "boolean (optional) \u2014 Include the event timeline, defaults to true",
      "IncludeQrCode": "boolean (optional) \u2014 Include the QR code as a data URL, defaults to true"
    }
  }
}

{
  "Response": false,
  "Message": "Invalid InvoiceToken. It must be a valid UUID v4 string.",
  "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": "Invoice not found.",
  "Code": 404
}

{
  "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
🔗 Public Link: PublicLink is the payment page you hand to the recipient. This API never emails it for you
📱 QR Code: Returned as a PNG data URL. If rendering fails the field comes back null and the rest of the payload is unaffected
🪶 Trim The Payload: Set IncludeEvents or IncludeQrCode to false when you do not need them
🧾 Timeline Cap: The event timeline returns the 200 newest events
🔐 Ownership: An invoice belonging to another account returns 404, never its contents