> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nexudus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Invoice Details

# Get Invoice Details

Retrieves a single invoice for the current customer. Invoices are created during checkout flows for bookings, products, plans, and more. This endpoint returns the full invoice breakdown, including lines, taxes, totals, currency, and metadata for the location.

## Authentication

This endpoint requires an authenticated customer session. The invoice must belong to the current customer or to a team the customer manages.

## Path Parameters

<ParamField path="invoiceId" type="number" required>
  The unique identifier of the invoice you want to retrieve.
</ParamField>

## Query Parameters

<ParamField query="_shape" type="string">
  Comma-separated list of field paths to include in the response. When provided, only the
  specified fields are returned — useful for reducing payload size. Supports nested paths
  using dot notation. Example: `_shape=InvoiceNumber,TotalAmount,DueAmount,Paid,Lines`.
</ParamField>

## Response

The response shape follows the `InvoicePreview` contract used across checkout and payments. Below is a summary of the most-used fields.

### Identification and Status

<ResponseField name="Id" type="number">
  Unique identifier for the invoice
</ResponseField>

<ResponseField name="UniqueId" type="string">
  Globally unique identifier for the invoice
</ResponseField>

<ResponseField name="InvoiceNumber" type="string">
  Human-friendly invoice number as visible to the customer
</ResponseField>

<ResponseField name="Draft" type="boolean">
  Whether the invoice is a draft
</ResponseField>

<ResponseField name="Paid" type="boolean">
  Whether the invoice is fully paid
</ResponseField>

<ResponseField name="PaidOn" type="string">
  ISO 8601 datetime when the invoice was paid (if paid)
</ResponseField>

<ResponseField name="DueDate" type="string">
  ISO 8601 date the invoice is due
</ResponseField>

<ResponseField name="CreditNote" type="boolean">
  Whether the document is a credit note
</ResponseField>

<ResponseField name="Refunded" type="boolean">
  Whether the invoice has been refunded
</ResponseField>

### Customer and Location

<ResponseField name="CoworkerId" type="number">
  Customer id the invoice belongs to
</ResponseField>

<ResponseField name="BusinessId" type="number">
  Location id where this invoice was issued
</ResponseField>

<ResponseField name="BusinessWebAddress" type="number">
  Web address id for the issuing location
</ResponseField>

### Billing To

<ResponseField name="BillToName" type="string">
  Billing contact or company name (can be null)
</ResponseField>

<ResponseField name="BillToAddress" type="string">
  Billing address line (can be null)
</ResponseField>

<ResponseField name="BillToCity" type="string">
  Billing city (can be null)
</ResponseField>

<ResponseField name="BillToState" type="string">
  Billing state/region (can be null)
</ResponseField>

<ResponseField name="BillToPostCode" type="string">
  Billing postal/ZIP code (can be null)
</ResponseField>

<ResponseField name="BillToCountry" type="object">
  Country object for the billing address
</ResponseField>

<ResponseField name="TaxIDNumber" type="string">
  Tax/VAT registration number (can be null)
</ResponseField>

### Amounts and Currency

<ResponseField name="TotalAmount" type="number">
  Grand total amount of the invoice (in invoice currency)
</ResponseField>

<ResponseField name="DueAmount" type="number">
  Amount still due
</ResponseField>

<ResponseField name="PaidAmount" type="number">
  Amount paid so far
</ResponseField>

<ResponseField name="TaxAmount" type="number">
  Total tax amount across all lines
</ResponseField>

<ResponseField name="DiscountAmount" type="number">
  Total discount applied to the invoice
</ResponseField>

<ResponseField name="Currency" type="object">
  Invoice currency object with fields: `Name`, `Code`, `Format`, etc.
</ResponseField>

<ResponseField name="TransactionCurrency" type="object">
  Transaction currency used by the payment gateway (if different)
</ResponseField>

<ResponseField name="TotalFormated" type="string">
  Pre-formatted total, e.g. "\$123.45"
</ResponseField>

<ResponseField name="DueAmountFormated" type="string">
  Pre-formatted due amount
</ResponseField>

### Lines and Taxes

<ResponseField name="Lines" type="array">
  Array of line items. Each item includes fields such as `Description`, `Quantity`, `UnitPrice`, `SubTotal`, `TaxAmount`, `TaxPercentage`, and
  optional `DiscountCode`.
</ResponseField>

<ResponseField name="TaxCategories" type="array">
  Breakdown of totals by tax rate, including `Rate`, `TaxSubTotal`, `SubTotal`, and `Lines`.
</ResponseField>

### Usage of Credits (if applicable)

<ResponseField name="UsedExtraServices" type="array">
  Applied extra service credits with `Amount`, `ChargePeriod`, `ExpiresOn`.
</ResponseField>

<ResponseField name="UsedBookingCredits" type="array">
  Applied booking credits with `Amount`, `ChargePeriod`, `ExpiresOn`.
</ResponseField>

### System Fields

<ResponseField name="CreatedOn" type="string">
  ISO 8601 datetime when the invoice was created (local time)
</ResponseField>

<ResponseField name="CreatedOnUtc" type="string">
  ISO 8601 datetime when the invoice was created (UTC)
</ResponseField>

<ResponseField name="UpdatedOn" type="string">
  ISO 8601 datetime when the invoice was last updated (local time)
</ResponseField>

<ResponseField name="UpdatedOnUtc" type="string">
  ISO 8601 datetime when the invoice was last updated (UTC)
</ResponseField>

## Example Response

```json theme={null}
{
  "Id": 12345,
  "IdString": "12345",
  "UniqueId": "e9a3a3b8-8d3e-4b54-9f2d-0c82b2a8b9a1",
  "InvoiceNumber": "INV-2025-000123",
  "CoworkerId": 987,
  "BusinessId": 42,
  "DueDate": "2025-09-30",
  "Paid": false,
  "Draft": false,
  "Currency": { "Code": "USD", "Name": "US Dollar", "Format": "$0,0.00" },
  "TotalAmount": 199.0,
  "DueAmount": 199.0,
  "TaxAmount": 33.17,
  "DiscountAmount": 0,
  "Lines": [
    {
      "Id": 1,
      "Description": "Meeting room booking",
      "Quantity": 1,
      "UnitPrice": 165.83,
      "SubTotal": 165.83,
      "TaxAmount": 33.17,
      "TaxPercentage": 20,
      "SubTotalFormatted": "$165.83",
      "TaxAmountFormatted": "$33.17",
      "UnitPriceFormatted": "$165.83"
    }
  ],
  "TaxCategories": [{ "Rate": 20, "TaxSubTotal": 33.17, "SubTotal": 165.83, "Name": "VAT 20%", "Lines": [] }],
  "TotalFormated": "$199.00",
  "DueAmountFormated": "$199.00",
  "CreatedOn": "2025-09-28T10:15:00",
  "CreatedOnUtc": "2025-09-28T09:15:00Z"
}
```

## Usage in Portal

This endpoint is used during checkout and payment flows whenever an existing invoice id is present (e.g., resuming payment or redirecting back from a payment provider). Key usages include:

1. Checkout flow controller – decides steps when an `invoice_id` is present
   * File: `src/views/checkout/CheckoutLayoutPage.tsx`
2. Payment selection and processing (uses invoice data to start payment sessions)
   * Files:
     * `src/views/checkout/SignupPaymentPage.tsx`
     * `src/views/public/checkout/booking/components/StripeCheckoutForm.tsx`
     * `src/views/public/checkout/booking/components/SpreedlyCheckoutForm.tsx`
3. Completion step context
   * File: `src/views/checkout/SignupCompletePage.tsx`
4. Invoice fetching and basket state orchestration
   * File: `src/states/useBasketData.tsx` (calls `endpoints.billing.invoices.one` when `invoice_id` is in the URL)
5. Discount code summary UI (reads invoice lines and currency)
   * File: `src/views/public/checkout/booking/components/DiscountCodeForm.tsx`

### Typical integration pattern

```ts theme={null}
// From src/api/endpoints.ts
// const endpoints.billing.invoices.one = (invoiceId: number) => ({
//   url: `/api/public/billing/invoices/${invoiceId}`,
//   type: null as unknown as InvoicePreview,
// })

// Usage in React
const endpoint = endpoints.billing.invoices.one(Number(invoiceId))
const { resource: invoice } = useData<typeof endpoint.type>(httpClient, invoiceId ? endpoint.url : null)
```

## Related Endpoints

* `POST /en/basket/CreateInvoice` – Create an invoice from the current basket
* `POST /api/public/payments/stripe/createGuestSession` – Start a Stripe checkout session
* `POST /api/public/payments/spreedly/createGuestSession` – Start a Spreedly payment session

## Error Responses

<ResponseField name="401 Unauthorized" type="error">
  The current user is not authenticated or The invoice is not accessible to the current user
</ResponseField>

<ResponseField name="404 Not Found" type="error">
  Invoice with the specified id does not exist or is not accessible
</ResponseField>