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

200

Potential 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.

Show properties

Array of PotentialInvoiceComponentDto

amountnumberrequired

Amount (price) after discount

amountWithoutDiscountnumberrequired

Amount without discount

descriptionstringrequired

Component description (HTML format, converted from ProseMirror IDoc)

discountAmountnumberrequired

Discount amount

discountTypestringrequired

Discount type

Allowed:FixedPercentage

hourRatenumberrequired

Hourly rate

iconobject | nullrequired

Component icon

idstring<uuid>required

Component ID

itemsPotentialInvoiceComponentItemDto[]required

Component items

Show properties

Array of PotentialInvoiceComponentItemDto

amountnumberrequired

Amount (price)

childrenPotentialInvoiceComponentItemDto[]required

Child items (nested structure)

Show properties

Array of PotentialInvoiceComponentItemDto

Circular reference to PotentialInvoiceComponentItemDto.

descriptionstringrequired

Item description (HTML format, converted from ProseMirror IDoc)

hourRatenumberrequired

Hourly rate

iconobject | nullrequired

Item icon

idstring<uuid>required

Component item ID

namestringrequired

Item name

originalItemIdobject<uuid> | nullrequired

Original item ID from project component

parentIdobject<uuid> | nullrequired

Parent item ID (for nested items)

sortnumberrequired

Sort order

timeFramenumber | nullrequired

Time frame in hours

totalEstimatenumber | nullrequired

Total estimate in hours

typestringrequired

Item type

Allowed:EpicWorkPackageTodoListTestSuite

namestringrequired

Component name

originalComponentIdobject<uuid> | nullrequired

Original component ID from project

sortnumberrequired

Sort order

totalTimeFramenumberrequired

Total time frame in hours

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.

Show properties

Array of PotentialInvoiceExpressQuotationDto

acceptedAtstringrequired

Accepted at timestamp

acceptedByNamestringrequired

Name of person who accepted the quotation

amountnumberrequired

Total amount

fullNumberstringrequired

Full quotation number

idstring<uuid>required

Express quotation ID

itemsPotentialInvoiceExpressQuotationItemDto[]required

Quotation items

Show properties

Array of PotentialInvoiceExpressQuotationItemDto

descriptionstringrequired

Item description (HTML format, converted from ProseMirror IDoc)

optionsPotentialInvoiceExpressQuotationOptionDto[]required

Item options

Show properties

Array of PotentialInvoiceExpressQuotationOptionDto

titlestringrequired

Option title

totalPricenumberrequired

Total price for this option

unitPricenumberrequired

Unit price for this option

ordernumberrequired

Sort order

quantitynumberrequired

Quantity

titlestringrequired

Item title

totalPricenumberrequired

Total price

unitstringrequired

Unit type

Allowed:PieceHour

unitPricenumberrequired

Unit price

quotationIdstring<uuid>required

Quotation ID

quotationShortNumbernumberrequired

Quotation short number

taskShortNumbernumberrequired

Task short number

titlestringrequired

Quotation title

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.

Show properties

Array of PotentialInvoiceManualPositionDto

categoryNameobject | nullrequired

Category name

descriptionobject | nullrequired

Position description (HTML format, converted from ProseMirror IDoc)

discountAmountnumber | nullrequired

Discount amount

discountTypestring | nullrequired

Discount type

Allowed:FixedPercentage

discountValuenumber | nullrequired

Discount value

idstring<uuid>required

Manual position ID

interimPaymentIdobject<uuid> | nullrequired

Interim payment ID (if this is an interim payment)

pricenumberrequired

Position price

projectManualPositionIdobject<uuid> | nullrequired

Project manual position ID (if linked to project manual position)

titlestringrequired

Position title

typestring | nullrequired

Manual position type

Allowed:manualprojectinterimPaymentinterimPaymentDiscount

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.

Show properties

Array of PotentialInvoiceProductDto

basePriceFixednumberrequired

Base fixed price (before discounts)

categoryIdstring<uuid>required

Product category ID

descriptionobject | nullrequired

Product description (HTML format, converted from ProseMirror IDoc)

fixedDiscountAmountnumberrequired

Fixed discount amount

fixedDiscountTypestringrequired

Fixed discount type

Allowed:FixedPercentage

fixedDiscountValuenumberrequired

Fixed discount value

idstring<uuid>required

Product ID

namestringrequired

Product name

optionsInvoiceProductOptionDto[]required

Product options

Show properties

Array of InvoiceProductOptionDto

idstringrequired

Option ID

namestringrequired

Option name

originalOptionIdobject

Original option ID from catalog

sortnumberrequired

Sort order

valuesInvoiceProductOptionValueDto[]required

Available option values

Show properties

Array of InvoiceProductOptionValueDto

extraPriceFixedobject

Extra price for this option value

idstringrequired

Option value ID

namestringrequired

Option value name

originalValueIdobject

Original option value ID from catalog

sortnumberrequired

Sort order

originalProductIdobject<uuid> | nullrequired

Original product ID from catalog

priceFixednumberrequired

Fixed price

quantitynumberrequired

Quantity

sortnumberrequired

Sort order

totalPricenumberrequired

Total price (after discounts)

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.

Show properties

Array of PotentialSubscriptionBillingRowDto

billingIdstring<uuid>required

Subscription billing ID

idstring<uuid>required

Billing row ID

manualTitlestring | nullrequired

Manual title for this billing row

paymentstringrequired

Payment type

Allowed:fixedperUnitoneTime

pricenumberrequired

Price per unit

quantitynumber | nullrequired

Quantity (for per-unit pricing)

typestringrequired

Subscription billing type

Allowed:manualproduct

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.

Show properties

Array of PotentialSupportContingentChargeDto

frequencynumberrequired

Billing frequency in months. Determines how often this contingent is charged (e.g., 1 = monthly, 3 = quarterly)

hourRatenumberrequired

Hourly rate used for calculating the price (in organization currency)

hoursIncludednumberrequired

Number of hours included in this billing period

idstring<uuid>required

Unique identifier for this charge (same as supportContingentId for potential invoices)

periodEndstringrequired

Billing period end date (ISO 8601 date string, YYYY-MM-DD format)

periodStartstringrequired

Billing period start date (ISO 8601 date string, YYYY-MM-DD format)

pricenumberrequired

Total price for this billing period (in organization currency)

supportContingentIdstring<uuid>required

Support contingent ID (UUID) that this charge is based on

titlestringrequired

Title of the support contingent

transferablebooleanrequired

Whether unused hours from this period can be transferred to future periods

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.

Show properties

Array of PotentialInvoiceTaskDto

billedTimenumber | nullrequired

Billed time in hours (if different from spent time)

billedTitleobject | nullrequired

Custom billed title (if different from task title)

estimatedTimenumberrequired

Estimated time in hours

idstring<uuid>required

Task ID

shortNumbernumberrequired

Task short number

spentTimenumberrequired

Spent time in hours

titlestringrequired

Task title

typeIdstring<uuid>required

Task type ID

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

401

Unauthorized - Invalid or missing authentication token

403

User lacks Invoices.manage permission or project access

404

Potential invoice not found

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

OAuth2 access tokenRemember on this deviceInclude my values in samples

Parameters

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

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": [
    {
      "amount": 0,
      "amountWithoutDiscount": 0,
      "description": "string",
      "discountAmount": 0,
      "discountType": "Fixed",
      "hourRate": 0,
      "icon": {},
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "items": [
        {
          "amount": 0,
          "children": [
            {}
          ],
          "description": "string",
          "hourRate": 0,
          "icon": {},
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "name": "string",
          "originalItemId": {},
          "parentId": {},
          "sort": 0,
          "timeFrame": 0,
          "totalEstimate": 0,
          "type": "Epic"
        }
      ],
      "name": "string",
      "originalComponentId": {},
      "sort": 0,
      "totalTimeFrame": 0
    }
  ],
  "contactId": {},
  "expressQuotations": [
    {
      "acceptedAt": "string",
      "acceptedByName": "string",
      "amount": 0,
      "fullNumber": "string",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "items": [
        {
          "description": "string",
          "options": [
            {
              "title": "string",
              "totalPrice": 0,
              "unitPrice": 0
            }
          ],
          "order": 0,
          "quantity": 0,
          "title": "string",
          "totalPrice": 0,
          "unit": "Piece",
          "unitPrice": 0
        }
      ],
      "quotationId": "98c8afab-b1d9-462f-9483-5a2dbf34985f",
      "quotationShortNumber": 0,
      "taskShortNumber": 0,
      "title": "string"
    }
  ],
  "hasMeta": true,
  "id": "SingleProject::0e9d033a-ab41-4212-8637-66c4e3b01fe2::2025-10-01::2025-10-31",
  "includedTypes": [
    "Mixed"
  ],
  "leadtimeFeePercent": 0,
  "manualPositions": [
    {
      "categoryName": {},
      "description": {},
      "discountAmount": 0,
      "discountType": "Fixed",
      "discountValue": 0,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "interimPaymentId": {},
      "price": 0,
      "projectManualPositionId": {},
      "title": "string",
      "type": "manual"
    }
  ],
  "orgHourlyRate": 0,
  "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
  "periodFrom": "2025-10-01",
  "periodTo": "2025-10-31",
  "products": [
    {
      "basePriceFixed": 0,
      "categoryId": "337f5e5d-288b-40d5-be14-901cc3acacc0",
      "description": {},
      "fixedDiscountAmount": 0,
      "fixedDiscountType": "Fixed",
      "fixedDiscountValue": 0,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "options": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "name": "Size",
          "originalOptionId": "123e4567-e89b-12d3-a456-426614174000",
          "sort": 1,
          "values": [
            {
              "extraPriceFixed": 50,
              "id": "123e4567-e89b-12d3-a456-426614174000",
              "name": "Large",
              "originalValueId": "123e4567-e89b-12d3-a456-426614174000",
              "sort": 1
            }
          ]
        }
      ],
      "originalProductId": {},
      "priceFixed": 0,
      "quantity": 0,
      "sort": 0,
      "totalPrice": 0
    }
  ],
  "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",
  "skippedExpressQuotationTasks": [
    "string"
  ],
  "skippedTasks": [
    "string"
  ],
  "subscriptions": [
    {
      "billingId": "58e5f4cf-05a5-41d8-885e-4e713ed57628",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "manualTitle": "string",
      "payment": "fixed",
      "price": 0,
      "quantity": 0,
      "type": "manual"
    }
  ],
  "supportContingentCharges": [
    {
      "frequency": 1,
      "hourRate": 10,
      "hoursIncluded": 50,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "periodEnd": "2025-08-31",
      "periodStart": "2025-08-01",
      "price": 500,
      "supportContingentId": "cb4c3118-77d4-43d5-bf41-9eb6ce838600",
      "title": "Monthly Support Retainer",
      "transferable": true
    }
  ],
  "tasks": [
    {
      "billedTime": 0,
      "billedTitle": {},
      "estimatedTime": 0,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "shortNumber": 123,
      "spentTime": 0,
      "title": "string",
      "typeId": "caab7c42-4ce7-4bd5-bbab-6017cec730b7"
    }
  ],
  "tax": 0,
  "type": "Mixed"
}