# Retrieve an Invoice

`GET /v1/invoices/:id`

Returns one Invoice in the authenticated Organization. Requires `invoices.read`.

**Required API scopes:** `invoices.read`

## Parameters

- `id` (path, `string`) (required)

## Response `200`

The requested `Invoice`.

- `object`
  - `booking_ids` (`array`) - The Bookings associated with the Invoice.
    - `items` (`string`) - format: `uuid`
  - `clinician_id` (`string | null`) - format: `uuid`; The Clinician associated with the Invoice.
  - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `currency` (`string | null`) - The ISO 4217 currency code.
  - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - `invoice_notes` (`string | null`) - The sanitized HTML notes on the Invoice.
  - `invoice_number` (`string | null`) - The Invoice number, unique within the Organization.
  - `line_items` (`array`) - The charges included on the Invoice.
    - `items` (`object`)
      - `booking_id` (`string | null`) - format: `uuid`; The Booking associated with the line item.
      - `created_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
      - `currency` (`string | null`) - The ISO 4217 currency code.
      - `discount_amount` (`integer | null`) - The discount in minor currency units.
      - `gross_amount` (`integer | null`) - The gross amount in minor currency units.
      - `id` (`string`) - format: `uuid`; The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - `net_amount` (`integer | null`) - The net amount in minor currency units.
      - `object` (`any`) - Discriminator value emitted at `object`.
      - `quantity` (`number | null`) - The quantity charged.
      - `service_variant_id` (`string | null`) - format: `uuid`; The ServiceVariant associated with the charge.
      - `tax_amount` (`integer | null`) - The tax amount in minor currency units.
      - `tax_rate_id` (`string | null`) - format: `uuid`; The TaxRate applied to the line item.
      - `title` (`string | null`) - The line item description.
      - `total` (`integer | null`) - The line total in minor currency units.
      - `unit_price` (`integer | null`) - The unit price in minor currency units.
      - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.
  - `links` (`object`) - URLs to related resources.
    - `patient` (`string | null`) - format: `uri`; The full URL of a related resource.
  - `object` (`any`) - Discriminator value emitted at `object`.
  - `patient_id` (`string | null`) - format: `uuid`; The Patient associated with the Invoice.
  - `payment_url` (`string | null`) - format: `uri`; The Patient Portal URL where the Patient can pay this Invoice. Null when the Invoice has no invoice_number.
  - `payor_type` (`string | null`) - The type of party responsible for payment.
  - `status` (`string | null`) - enum: `awaiting_patient`, `being_processed`, `canceled`, `credited_error`, `credited_goodwill`, `credited_other`, `credited_overbilled`, `credited_service_not_delivered`, `draft`, `error`, `no_payment_required`, `overdue`, `overpaid`, `paid`, `partially_credited`, `partially_paid`, `partially_refunded`, `partially_written_off`, `payment_scheduled`, `refunded`, `scheduled_for_sending`, `sent_to_debt_collectors`, `sent_to_insurance_company`, `sent_to_other_recipient`, `unpaid`, `validated`, `written_off_nonpayer`, `written_off_other`, `null`; The Invoice's current status.
  - `subtotal` (`integer | null`) - The subtotal in minor currency units.
  - `supply_date` (`string | null`) - format: `date`; The date on which the invoiced services were supplied.
  - `tax_amount` (`integer | null`) - The tax amount in minor currency units.
  - `title` (`string | null`) - The Invoice title.
  - `total` (`integer`) - The total in minor currency units.
  - `total_discount_amount` (`integer | null`) - The total discount in minor currency units.
  - `total_outstanding` (`integer | null`) - The outstanding amount in minor currency units.
  - `total_paid` (`integer | null`) - The paid amount in minor currency units.
  - `updated_at` (`string`) - format: `date-time`; An ISO 8601 timestamp in UTC, with a `Z` suffix. For example, `2026-07-01T09:00:00Z`.

### Example

```json
{
  "id": "00000000-0000-4000-8000-000000000027",
  "object": "invoice",
  "booking_ids": [
    "00000000-0000-4000-8000-000000000001"
  ],
  "clinician_id": "00000000-0000-4000-8000-000000000002",
  "created_at": "2026-01-01T09:00:00Z",
  "currency": "GBP",
  "invoice_notes": "<p>Payment is due within 30 days.</p>",
  "invoice_number": "INV-1001",
  "line_items": [
    {
      "id": "1bf0a3b9-0974-4fd3-8bf6-817d28071309",
      "object": "invoice_line_item",
      "booking_id": "00000000-0000-4000-8000-000000000001",
      "created_at": "2026-01-01T09:00:00Z",
      "currency": "GBP",
      "discount_amount": 1,
      "gross_amount": 1,
      "net_amount": 1,
      "quantity": 1.5,
      "service_variant_id": "00000000-0000-4000-8000-000000000006",
      "tax_amount": 1,
      "tax_rate_id": "00000000-0000-4000-8000-000000000029",
      "title": "Dr",
      "total": 1,
      "unit_price": 1,
      "updated_at": "2026-01-01T09:00:00Z"
    }
  ],
  "links": {
    "patient": "https://api.carebit.co/v1/patients/00000000-0000-4000-8000-000000000004"
  },
  "patient_id": "00000000-0000-4000-8000-000000000004",
  "payment_url": "https://files.example.invalid/document.pdf?signature=test",
  "payor_type": "insurance_company",
  "status": "awaiting_patient",
  "subtotal": 1,
  "supply_date": "2026-01-01",
  "tax_amount": 1,
  "title": "Dr",
  "total": 1,
  "total_discount_amount": 1,
  "total_outstanding": 1,
  "total_paid": 1,
  "updated_at": "2026-01-01T09:00:00Z"
}
```

## Response `401`

The access token is missing, invalid, expired, or revoked.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `403`

The access token lacks the required scope, or the project is disabled.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `404`

The Invoice was not found in the Organization.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Response `429`

Too many requests. Retry after the delay indicated by `Retry-After`.

- `object`
  - `error` (`object`) - The structured details that describe why the request failed.
    - `code` (`string`) - The machine-readable error code.
    - `errors` (`array | null`) - Additional errors from a failed validation.
      - `items` (`object`)
        - `code` (`string`) - The machine-readable code for this validation error.
        - `message` (`string`) - A message that explains this validation error.
        - `param` (`string | null`) - The name of the parameter that caused this validation error, when known.
    - `message` (`string`) - A message that explains the error and how to resolve it.
    - `param` (`string | null`) - The name of the parameter that caused the error, when known.
    - `type` (`string`) - enum: `authentication_error`, `permission_error`, `invalid_request_error`, `rate_limit_error`, `api_error`; The high-level category of the error.

### Example

```json
{
  "error": {
    "code": "resource_missing",
    "errors": [
      {
        "code": "resource_missing",
        "message": "The requested resource was not found.",
        "param": "patient_id"
      }
    ],
    "message": "The requested resource was not found.",
    "param": "patient_id",
    "type": "authentication_error"
  }
}
```

## Code samples

```bash
curl -X GET "https://api.carebit.co/v1/invoices/00000000-0000-4000-8000-000000000027" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"
```

```javascript
const response = await fetch("https://api.carebit.co/v1/invoices/00000000-0000-4000-8000-000000000027", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CAREBIT_ACCESS_TOKEN}`,
  },
});

if (!response.ok) {
  throw new Error(`Carebit API error: ${response.status}`);
}

const data = await response.json();
```

```python
import os
import requests

response = requests.get(
    "https://api.carebit.co/v1/invoices/00000000-0000-4000-8000-000000000027",
    headers={
        "Authorization": f"Bearer {os.environ['CAREBIT_ACCESS_TOKEN']}",
    }
)
response.raise_for_status()
data = response.json()
```

```ruby
require "httparty"

response = HTTParty.get(
  "https://api.carebit.co/v1/invoices/00000000-0000-4000-8000-000000000027",
  headers: {
    "Authorization" => "Bearer #{ENV.fetch("CAREBIT_ACCESS_TOKEN")}"
  }
)
raise "Carebit API error: #{response.code}" unless response.success?
data = response.parsed_response
```

```php
<?php

$client = new GuzzleHttp\Client();

$response = $client->get("https://api.carebit.co/v1/invoices/00000000-0000-4000-8000-000000000027", [
    "headers" => [
      "Authorization" => "Bearer " . getenv("CAREBIT_ACCESS_TOKEN"),
    ]
]);
$data = json_decode((string) $response->getBody(), true, flags: JSON_THROW_ON_ERROR);
```