Get potential invoice details

What are Potential Invoice Details? Returns the complete breakdown of a specific potential invoice, showing all billable items that make up the total amount. This is the detailed view you see when reviewing an invoice before finalizing it. You can see exactly what is being billed, adjust quantities or amounts, and configure additional settings.

What is included in the details:

Subscription billing rows: Recurring fees with quantities, unit prices, and payment types (fixed, per-unit, one-time)
Time-based tasks: Completed tickets with logged hours, estimated time, billed time, and hourly rates
Express quotations: Accepted quick quotes from tickets with items, quantities, and unit prices
Products: Items from the product catalog with options, quantities, discounts, and pricing
Components: Project components with time estimates, hourly rates, and nested items
Support contingent charges: Retainer plan charges for Support-type projects, based on allocated hours and pricing for billing periods
Manual positions: Custom billing items (third-party costs, flat fees, interim payments)
Leadtime fee settings: Configuration for adding the Leadtime service fee to the invoice

Invoice ID Format: The invoice ID follows the format: {type}::{projectId}::{dateFrom}::{dateTo}

Example: SingleProject::0e9d033a-ab41-4212-8637-66c4e3b01fe2::2025-10-01::2025-10-31
Type: One of Mixed, Subscription, TimeBased, ExpressQuotation, SingleProject, InterimPayment, SupportContingentCharge
ProjectId: UUID of the project
DateFrom/DateTo: Dates in YYYY-MM-DD format representing the billing period

What data is returned:

Complete invoice structure with all billable items organized by type
Billing period (periodFrom, periodTo) and custom billed dates (billedFrom, billedTo)
Tax calculations (tax amount, reverse charge settings)
Contact information (contactId for invoice recipient)
Leadtime fee settings (percentage, method, task distribution, custom title)
Lists of skipped tasks and express quotations (items excluded from billing)
All items include detailed pricing, discounts, descriptions (as HTML), and metadata
Product and component descriptions are converted from ProseMirror IDoc format to HTML

How to use:

Get the list of potential invoices to find the invoice ID
Use this endpoint to get full details of a specific invoice
Review all billable items and their amounts
Use the PATCH endpoint to adjust settings (billed dates, contact, etc.)
Use other endpoints to skip items, add manual positions, or configure fees
Once reviewed and adjusted, the invoice can be finalized into an actual invoice document

Permission requirements: Requires Invoices.manage permission and access to the project to view potential invoice details.

GET/billing/potential-invoices/{id}

Authorization

AuthorizationOAuth2 access token · headerrequired

Scopes:api:read

AuthorizationBearer token (JWT) · headerrequired

Path parameters

idstringrequired

Potential invoice ID in format: {type}::{projectId}::{dateFrom}::{dateTo}

Responses

200Potential invoice details retrieved successfully

addLeadtimeFeeMethodstringrequired

Method for how the Leadtime fee should be added to the invoice. See AddLeadtimeFeeMethod enum for options (e.g., SeparateRow, DistributedToTasks).

Allowed:SeparateRowTasksDistribution

addLeadtimeFeeTasksstring[]required

Array of task IDs (UUIDs) for distributing the Leadtime fee across specific tasks. Used when addLeadtimeFeeMethod is set to distribute the fee to tasks.

addLeadtimeFeeToInvoicebooleanrequired

Whether to add the Leadtime service fee as a separate line item on the invoice. If false, the fee is not shown on the invoice but may still be calculated separately.

addLeadtimeRowCustomTitleobject | nullrequired

Custom title for the Leadtime fee row on the invoice. If null, a default title is used. This allows you to customize how the fee appears on the invoice document.

applyReverseChargebooleanrequired

Whether reverse charge VAT is applied. Reverse charge is used for B2B transactions within the EU where the customer is responsible for VAT.

billedFromstring | nullrequired

Custom billed from date (ISO 8601 date string, YYYY-MM-DD format). This is the start date that will appear on the final invoice document. Can differ from periodFrom if you want to show a different date range. Null if using default periodFrom.

billedTostring | nullrequired

Custom billed to date (ISO 8601 date string, YYYY-MM-DD format). This is the end date that will appear on the final invoice document. Can differ from periodTo if you want to show a different date range. Null if using default periodTo.

componentspotentialInvoiceComponentDto[][]required

Array of project components with time estimates and hourly rates. Components are work packages from the project structure. Each component includes nested items, time frames, hourly rates, and amounts. Descriptions are returned as HTML.

contactIdobject<uuid> | nullrequired

Contact ID (UUID) of the organization member who will receive the invoice when it is sent via email. Null if no contact has been assigned yet.

expressQuotationspotentialInvoiceExpressQuotationDto[][]required

Array of accepted express quotations. Express quotations are quick quotes created directly from tickets that have been accepted by the customer. Each quotation includes items, quantities, unit prices, and acceptance details.

hasMetabooleanrequired

Whether this potential invoice has custom metadata or settings applied. If true, the invoice has been customized (custom dates, contact, skipped items, etc.). If false, it shows the default calculated values.

idstringrequired

Unique identifier for the potential invoice. Format: {type}::{projectId}::{dateFrom}::{dateTo}

includedTypesstring[]required

Array of all invoice types included in this potential invoice. For Mixed type invoices, this will contain multiple types (e.g., TimeBased, Subscription, Products).

leadtimeFeePercentnumberrequired

Leadtime service fee percentage. This is the percentage of the invoice total that will be charged as the Leadtime platform fee.

manualPositionspotentialInvoiceManualPositionDto[][]required

Array of manual positions (custom billing items). These are manually added items like third-party costs, flat fees, interim payments, or other custom charges. Can include project manual positions or custom positions added during invoice review.

orgHourlyRatenumberrequired

Hourly rate (in organization currency) used for calculating time-based billing. This rate is applied to logged hours on tasks.

organizationIdstring<uuid>required

Organization ID (UUID) of the customer organization that will be billed

periodFromstringrequired

Actual service period start date (ISO 8601 date string, YYYY-MM-DD format). This is when the billable work actually began.

periodTostringrequired

Actual service period end date (ISO 8601 date string, YYYY-MM-DD format). This is when the billable work actually ended.

productspotentialInvoiceProductDto[][]required

Array of products from the product catalog. These are standardized products or services with fixed prices, quantities, options, and discounts. Product descriptions are returned as HTML.

projectIdstring<uuid>required

Project ID (UUID) where the billable work was performed

skippedExpressQuotationTasksstring[]required

Array of express quotation task IDs (UUIDs) that have been excluded from billing. These are accepted express quotations that have been skipped and will not appear on the invoice.

skippedTasksstring[]required

Array of task IDs (UUIDs) that have been excluded from billing. These are tasks that would normally be billable but have been skipped (marked as "do not bill").

subscriptionspotentialSubscriptionBillingRowDto[][]required

Array of subscription billing rows. These are recurring fees (monthly or periodic) that are due for billing. Each row includes billing type, payment type, price, quantity, and optional manual title.

supportContingentChargespotentialSupportContingentChargeDto[][]required

Array of support contingent charges. These are retainer plan charges for Support-type projects, based on allocated hours and pricing for billing periods. Each charge includes the contingent title, period (start/end dates), frequency, hours included, price, hourly rate, and transferable flag.

taskspotentialInvoiceTaskDto[][]required

Array of time-based tasks (tickets) with logged hours. These are completed tasks that have time logged and are ready for billing. Each task includes logged time, estimated time, billed time, and billing information.

taxnumberrequired

Tax amount calculated for this invoice. The tax rate is configured in workspace settings.

typestringrequired

Primary invoice type indicating the main category of billable items. See InvoiceType enum for all possible values.

Allowed:MixedSubscriptionTimeBasedExpressQuotationSingleProjectInterimPaymentSupportContingentCharge

401Unauthorized - Invalid or missing authentication token

403User lacks Invoices.manage permission or project access

404Potential invoice not found

Request

curl -X GET "https://leadtime.app/api/public/billing/potential-invoices/SingleProject%3A%3A0e9d033a-ab41-4212-8637-66c4e3b01fe2%3A%3A2025-10-01%3A%3A2025-10-31" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

const response = await fetch("https://leadtime.app/api/public/billing/potential-invoices/SingleProject%3A%3A0e9d033a-ab41-4212-8637-66c4e3b01fe2%3A%3A2025-10-01%3A%3A2025-10-31", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"
  }
});

import requests

response = requests.get(
    "https://leadtime.app/api/public/billing/potential-invoices/SingleProject%3A%3A0e9d033a-ab41-4212-8637-66c4e3b01fe2%3A%3A2025-10-01%3A%3A2025-10-31",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    },
)

Response

{
  "addLeadtimeFeeMethod": "SeparateRow",
  "addLeadtimeFeeTasks": [
    "string"
  ],
  "addLeadtimeFeeToInvoice": false,
  "addLeadtimeRowCustomTitle": {},
  "applyReverseCharge": false,
  "billedFrom": "string",
  "billedTo": "string",
  "components": [
    [
      "string"
    ]
  ],
  "contactId": {},
  "expressQuotations": [
    [
      "string"
    ]
  ],
  "hasMeta": true,
  "id": "SingleProject::0e9d033a-ab41-4212-8637-66c4e3b01fe2::2025-10-01::2025-10-31",
  "includedTypes": [
    "Mixed"
  ],
  "leadtimeFeePercent": 0,
  "manualPositions": [
    [
      "string"
    ]
  ],
  "orgHourlyRate": 0,
  "organizationId": "<uuid>",
  "periodFrom": "2025-10-01",
  "periodTo": "2025-10-31",
  "products": [
    [
      "string"
    ]
  ],
  "projectId": "<uuid>",
  "skippedExpressQuotationTasks": [
    "string"
  ],
  "skippedTasks": [
    "string"
  ],
  "subscriptions": [
    [
      "string"
    ]
  ],
  "supportContingentCharges": [
    [
      "string"
    ]
  ],
  "tasks": [
    [
      "string"
    ]
  ],
  "tax": 0,
  "type": "Mixed"
}