Carebit API

Invoices

Invoices associated with Bookings and Patients.

Required API scopes: invoices.createinvoices.read

Endpoints

Scroll this page to read every Invoices endpoint, or jump to one below.

get/v1/invoicesList Invoicesinvoices.read
post/v1/invoicesCreate an Invoiceinvoices.create
get/v1/invoices/:idRetrieve an Invoiceinvoices.read

get/v1/invoices

List Invoices

Returns Invoices in the authenticated Organization. All filters are optional. When several filters are supplied, an Invoice must match every filter. Use status and a created_at window to list outstanding Invoices without querying one Patient at a time.

Required API scopes: invoices.read

Parameters

booking_id
query
string
Filter by a Booking in the Organization.
created_at_from
query
string
Inclusive lower bound for created_at in UTC ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
created_at_to
query
string
Inclusive upper bound for created_at in UTC ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ).
patient_id
query
string
Filter by a Patient with an active connection to the Organization.
status
query
string · 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
Filter by Invoice status. Use a documented status such as canceled, overdue, paid, or unpaid.
limit
query
integer
The maximum number of items to return. Defaults to 25; the maximum is 100.
starting_after
query
string
Return items after this resource ID. You cannot use this with cursor.
cursor
query
string
The next_cursor value from the previous page. You cannot use this with starting_after.

Responses

200

Paginated list of Invoice objects.

dataarrayrequired
- itemsobject
  - booking_idsarrayrequired
    The Bookings associated with the Invoice.
    - itemsstring · uuid
  - clinician_idstring | null · uuidrequired
    The Clinician associated with the Invoice.
  - created_atstring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - currencystring | nullrequired
    The ISO 4217 currency code.
  - idstring · uuidrequired
    The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - invoice_notesstring | nullrequired
    The sanitized HTML notes on the Invoice.
  - invoice_numberstring | nullrequired
    The Invoice number, unique within the Organization.
  - line_itemsarrayrequired
    The charges included on the Invoice.
    - itemsobject
      - booking_idstring | null · uuidrequired
        The Booking associated with the line item.
      - created_atstring · date-timerequired
        An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
      - currencystring | nullrequired
        The ISO 4217 currency code.
      - discount_amountinteger | nullrequired
        The discount in minor currency units.
      - gross_amountinteger | nullrequired
        The gross amount in minor currency units.
      - idstring · uuidrequired
        The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
      - net_amountinteger | nullrequired
        The net amount in minor currency units.
      - objectanyrequired
        Discriminator value emitted at object.
      - quantitynumber | nullrequired
        The quantity charged.
      - service_variant_idstring | null · uuidrequired
        The ServiceVariant associated with the charge.
      - tax_amountinteger | nullrequired
        The tax amount in minor currency units.
      - tax_rate_idstring | null · uuidrequired
        The TaxRate applied to the line item.
      - titlestring | nullrequired
        The line item description.
      - totalinteger | nullrequired
        The line total in minor currency units.
      - unit_priceinteger | nullrequired
        The unit price in minor currency units.
      - updated_atstring · date-timerequired
        An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - linksobjectrequired
    URLs to related resources.
    - patientstring | null · urirequired
      The full URL of a related resource.
  - objectanyrequired
    Discriminator value emitted at object.
  - patient_idstring | null · uuidrequired
    The Patient associated with the Invoice.
  - payment_urlstring | null · urirequired
    The Patient Portal URL where the Patient can pay this Invoice. Null when the Invoice has no invoice_number.
  - payor_typestring | nullrequired
    The type of party responsible for payment.
  - statusstring | nullrequired
    The Invoice's current status.
    Allowed values: 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
  - subtotalinteger | nullrequired
    The subtotal in minor currency units.
  - supply_datestring | null · daterequired
    The date on which the invoiced services were supplied.
  - tax_amountinteger | nullrequired
    The tax amount in minor currency units.
  - titlestring | nullrequired
    The Invoice title.
  - totalintegerrequired
    The total in minor currency units.
  - total_discount_amountinteger | nullrequired
    The total discount in minor currency units.
  - total_outstandinginteger | nullrequired
    The outstanding amount in minor currency units.
  - total_paidinteger | nullrequired
    The paid amount in minor currency units.
  - updated_atstring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
has_morebooleanrequired
Whether another page is available after next_cursor.
next_cursorstring | nullrequired
The value to pass as cursor for the next page. Null on the last page.
objectanyrequired
Always list.
urlstringrequired
The API path that returned this list.

Example

{
  "object": "list",
  "data":  … ]
     … }
      "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"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/invoices"
}

400

A filter or pagination parameter is invalid.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

401

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

403

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

404

The Booking or Patient was not found in the Organization.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

429

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

Request

curl -X GET "https://api.carebit.co/v1/invoices" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN"

200 response

{
  "object": "list",
  "data":  … ]
     … }
      "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"
    }
  ],
  "has_more": false,
  "next_cursor": "eyJzdGFydF90aW1lIjoiMjAyNi0wMS0wMVQwOTowMDowMFoifQ",
  "url": "/v1/invoices"
}

400 response

{
  "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"
  }
}

401 response

{
  "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"
  }
}

403 response

{
  "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"
  }
}

404 response

{
  "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"
  }
}

429 response

{
  "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"
  }
}

post/v1/invoices

Create an Invoice

Creates a self-pay Invoice for a Patient with an active connection to the Organization. payor_type must be patient. Each line item can set a TaxRate from the Organization. This endpoint does not set automated billing or insurance-submission attributes.

Required API scopes: invoices.create

Parameters

Idempotency-Key
header · required
string
Client-generated idempotency key. Required for every POST/PATCH write. Replay of the same key with the same body returns the stored response with an Idempotency-Replayed: true header. Same key + different body returns 422 idempotency_key_reused. A duplicate that arrives while the first request is still in flight returns 409 idempotency_conflict with Retry-After: 1.

Request body

application/json

booking_idsarray
Optional Bookings in the Organization that belong to the Invoice's Patient.
- itemsstring · uuid
clinician_idstring | null · uuid
The optional Clinician associated with the Invoice.
invoice_notesstring | null
HTML notes shown on the Invoice.
line_itemsarrayrequired
The charges to include on the Invoice. Amounts are minor currency units.
- itemsobject
  - booking_idstring | null · uuid
    The optional Booking associated with this line item. The Booking must belong to the Invoice's Patient.
  - quantitynumber
    The quantity charged. Defaults to 1.
  - service_variant_idstring | null · uuid
    The optional ServiceVariant associated with this charge.
  - tax_rate_idstring | null · uuid
    The optional TaxRate to apply. When set, Carebit calculates tax from this rate. When omitted, the line item is tax-exempt.
  - titlestringrequired
    The line item description.
  - unit_priceintegerrequired
    The unit price in minor currency units, excluding tax.
patient_idstring · uuidrequired
The Patient with an active connection to the Organization.
payor_typestring
The party responsible for payment. Currently only patient is supported.
Allowed values: patient
supply_datestring · date
The date on which the invoiced services were supplied. Defaults to today.
titlestringrequired
The Invoice title.

Responses

201

The requested Invoice.

booking_idsarrayrequired
The Bookings associated with the Invoice.
- itemsstring · uuid
clinician_idstring | null · uuidrequired
The Clinician associated with the Invoice.
created_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
currencystring | nullrequired
The ISO 4217 currency code.
idstring · uuidrequired
The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
invoice_notesstring | nullrequired
The sanitized HTML notes on the Invoice.
invoice_numberstring | nullrequired
The Invoice number, unique within the Organization.
line_itemsarrayrequired
The charges included on the Invoice.
- itemsobject
  - booking_idstring | null · uuidrequired
    The Booking associated with the line item.
  - created_atstring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - currencystring | nullrequired
    The ISO 4217 currency code.
  - discount_amountinteger | nullrequired
    The discount in minor currency units.
  - gross_amountinteger | nullrequired
    The gross amount in minor currency units.
  - idstring · uuidrequired
    The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - net_amountinteger | nullrequired
    The net amount in minor currency units.
  - objectanyrequired
    Discriminator value emitted at object.
  - quantitynumber | nullrequired
    The quantity charged.
  - service_variant_idstring | null · uuidrequired
    The ServiceVariant associated with the charge.
  - tax_amountinteger | nullrequired
    The tax amount in minor currency units.
  - tax_rate_idstring | null · uuidrequired
    The TaxRate applied to the line item.
  - titlestring | nullrequired
    The line item description.
  - totalinteger | nullrequired
    The line total in minor currency units.
  - unit_priceinteger | nullrequired
    The unit price in minor currency units.
  - updated_atstring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
linksobjectrequired
URLs to related resources.
- patientstring | null · urirequired
  The full URL of a related resource.
objectanyrequired
Discriminator value emitted at object.
patient_idstring | null · uuidrequired
The Patient associated with the Invoice.
payment_urlstring | null · urirequired
The Patient Portal URL where the Patient can pay this Invoice. Null when the Invoice has no invoice_number.
payor_typestring | nullrequired
The type of party responsible for payment.
statusstring | nullrequired
The Invoice's current status.
Allowed values: 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
subtotalinteger | nullrequired
The subtotal in minor currency units.
supply_datestring | null · daterequired
The date on which the invoiced services were supplied.
tax_amountinteger | nullrequired
The tax amount in minor currency units.
titlestring | nullrequired
The Invoice title.
totalintegerrequired
The total in minor currency units.
total_discount_amountinteger | nullrequired
The total discount in minor currency units.
total_outstandinginteger | nullrequired
The outstanding amount in minor currency units.
total_paidinteger | nullrequired
The paid amount in minor currency units.
updated_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.

Example

{
  "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"
}

400

The Idempotency-Key header is missing (idempotency_key_required) or exceeds 255 characters (idempotency_key_too_long).

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

401

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

403

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

404

The Patient, Clinician, Booking, ServiceVariant, or TaxRate was not found in the Organization.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

409

A concurrent request holds the idempotency lease (idempotency_conflict). Retry after the delay indicated by Retry-After.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

422

The Invoice cannot be created. payor_type must be patient, and each line item requires title and unit_price.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

429

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

Request

curl -X POST "https://api.carebit.co/v1/invoices" \
  -H "Authorization: Bearer $CAREBIT_ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "clinician_id": "00000000-0000-4000-8000-000000000002",
  "invoice_notes": "<p>Payment is due within 30 days.</p>",
  "line_items": [
    {
      "quantity": 1,
      "service_variant_id": "00000000-0000-4000-8000-000000000006",
      "tax_rate_id": "00000000-0000-4000-8000-000000000029",
      "title": "Initial consultation",
      "unit_price": 25000
    }
  ],
  "patient_id": "00000000-0000-4000-8000-000000000004",
  "payor_type": "patient",
  "supply_date": "2026-01-01",
  "title": "Initial consultation"
}'

201 response

{
  "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"
}

400 response

{
  "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"
  }
}

401 response

{
  "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"
  }
}

403 response

{
  "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"
  }
}

404 response

{
  "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"
  }
}

409 response

{
  "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"
  }
}

422 response

{
  "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"
  }
}

429 response

{
  "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"
  }
}

get/v1/invoices/:id

Retrieve an Invoice

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

Required API scopes: invoices.read

Parameters

id
path · required
string
-

Responses

200

The requested Invoice.

booking_idsarrayrequired
The Bookings associated with the Invoice.
- itemsstring · uuid
clinician_idstring | null · uuidrequired
The Clinician associated with the Invoice.
created_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
currencystring | nullrequired
The ISO 4217 currency code.
idstring · uuidrequired
The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
invoice_notesstring | nullrequired
The sanitized HTML notes on the Invoice.
invoice_numberstring | nullrequired
The Invoice number, unique within the Organization.
line_itemsarrayrequired
The charges included on the Invoice.
- itemsobject
  - booking_idstring | null · uuidrequired
    The Booking associated with the line item.
  - created_atstring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
  - currencystring | nullrequired
    The ISO 4217 currency code.
  - discount_amountinteger | nullrequired
    The discount in minor currency units.
  - gross_amountinteger | nullrequired
    The gross amount in minor currency units.
  - idstring · uuidrequired
    The resource's unique identifier, formatted as an RFC 4122 version 4 UUID.
  - net_amountinteger | nullrequired
    The net amount in minor currency units.
  - objectanyrequired
    Discriminator value emitted at object.
  - quantitynumber | nullrequired
    The quantity charged.
  - service_variant_idstring | null · uuidrequired
    The ServiceVariant associated with the charge.
  - tax_amountinteger | nullrequired
    The tax amount in minor currency units.
  - tax_rate_idstring | null · uuidrequired
    The TaxRate applied to the line item.
  - titlestring | nullrequired
    The line item description.
  - totalinteger | nullrequired
    The line total in minor currency units.
  - unit_priceinteger | nullrequired
    The unit price in minor currency units.
  - updated_atstring · date-timerequired
    An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.
linksobjectrequired
URLs to related resources.
- patientstring | null · urirequired
  The full URL of a related resource.
objectanyrequired
Discriminator value emitted at object.
patient_idstring | null · uuidrequired
The Patient associated with the Invoice.
payment_urlstring | null · urirequired
The Patient Portal URL where the Patient can pay this Invoice. Null when the Invoice has no invoice_number.
payor_typestring | nullrequired
The type of party responsible for payment.
statusstring | nullrequired
The Invoice's current status.
Allowed values: 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
subtotalinteger | nullrequired
The subtotal in minor currency units.
supply_datestring | null · daterequired
The date on which the invoiced services were supplied.
tax_amountinteger | nullrequired
The tax amount in minor currency units.
titlestring | nullrequired
The Invoice title.
totalintegerrequired
The total in minor currency units.
total_discount_amountinteger | nullrequired
The total discount in minor currency units.
total_outstandinginteger | nullrequired
The outstanding amount in minor currency units.
total_paidinteger | nullrequired
The paid amount in minor currency units.
updated_atstring · date-timerequired
An ISO 8601 timestamp in UTC, with a Z suffix. For example, 2026-07-01T09:00:00Z.

Example

{
  "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"
}

401

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

403

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

404

The Invoice was not found in the Organization.

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

429

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

errorobjectrequired
The structured details that describe why the request failed.
- codestringrequired
  The machine-readable error code.
- errorsarray | null
  Additional errors from a failed validation.
  - itemsobject
    - codestring
      The machine-readable code for this validation error.
    - messagestring
      A message that explains this validation error.
    - paramstring | null
      The name of the parameter that caused this validation error, when known.
- messagestringrequired
  A message that explains the error and how to resolve it.
- paramstring | null
  The name of the parameter that caused the error, when known.
- typestringrequired
  The high-level category of the error.
  Allowed values: authentication_error | permission_error | invalid_request_error | rate_limit_error | api_error

Example

{
  "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"
  }
}

Request

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

200 response

{
  "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"
}

401 response

{
  "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"
  }
}

403 response

{
  "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"
  }
}

404 response

{
  "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"
  }
}

429 response

{
  "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"
  }
}

Prefer plain text? Append ?format=md or send Accept: text/markdown to receive this page as raw Markdown.