Invoices

Requests that relate to viewing invoice information. Access to the requests is controlled by the invoice reading permission (Billing & Invoices section in Security Policies in the Designer).

Get invoices

get

Request for all invoices on an instance.

Authorizations

AuthorizationstringRequired

Bearer token obtained from POST /{tenantName}/admin/api_clients/{clientName}. Valid for 60 minutes.

Path parameters

tenantNamestringRequired

Your organization (tenant) name, e.g. acme-health

Example: acme-health

instanceNamestringRequired

Your environment name: live, sandbox, or a custom name

Example: live

Query parameters

sizeinteger · min: 1 · max: 1000Optional

Number of results per page

Default: 20

sortstringOptional

List sorting

Example: dueDate,desc

pageintegerOptional

Page number, numbering starts at 0

Default: 0Example: 0

Responses

200

Paginated list of invoices.

⚠️ Unverified: no backing REST controller for this exact path could be found in the backend source — invoicing is handled by a separate invoice-service, and this repo only contains a thin outbound HTTP client. The schema is inferred from that client's response deserialization and has not been directly confirmed against a live controller.

application/json

Standard paginated response wrapper.

totalElementsintegerOptional

Total number of matching records

totalPagesintegerOptional

Total number of pages

lastbooleanOptional

firstbooleanOptional

numberintegerOptional

Current page number (zero-based)

sizeintegerOptional

Page size

numberOfElementsintegerOptional

Number of elements on the current page

emptybooleanOptional

400

Bad request — the request could not be understood or was missing required parameters.

401

Unauthorized — the Bearer token is missing, expired, or invalid.

403

Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin.

404

Not found — the requested resource does not exist.

429

Too many requests — rate limit exceeded. Implement exponential backoff.

500

Internal server error.

get/{tenantName}/{instanceName}/invoice/invoices

GET /{tenantName}/{instanceName}/invoice/invoices HTTP/1.1
Host: api.live.welkincloud.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "content": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "customInvoiceId": "text",
      "status": "text",
      "paymentTypeInfo": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "billingType": "SELF_PAY",
      "dueDate": "2026-01-01T00:00:00.000Z",
      "invoiceDate": "2026-01-01T00:00:00.000Z",
      "invoiceItems": [
        {
          "id": "text",
          "description": "text",
          "quantity": 1,
          "unitAmount": 1,
          "serviceCode": "text",
          "serviceModifiers": [
            "text"
          ]
        }
      ],
      "careMember": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text"
      },
      "patient": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text"
      },
      "amount": 1,
      "amountPaid": 1,
      "relatedEncounters": [
        "123e4567-e89b-12d3-a456-426614174000"
      ]
    }
  ],
  "pageable": {
    "sort": {
      "sorted": true,
      "unsorted": true,
      "empty": true
    },
    "pageSize": 1,
    "pageNumber": 1,
    "offset": 1,
    "unpaged": true,
    "paged": true
  },
  "totalElements": 1,
  "totalPages": 1,
  "last": true,
  "first": true,
  "number": 1,
  "size": 1,
  "numberOfElements": 1,
  "empty": true,
  "sort": {
    "sorted": true,
    "unsorted": true,
    "empty": true
  }
}

Get invoice By ID

get

A request to get a specific invoice. invoice_id is the internal invoice id (not customInvoiceId, which is displayed on the UI).

The invoice_id can be taken from other get requests

Authorizations

AuthorizationstringRequired

Bearer token obtained from POST /{tenantName}/admin/api_clients/{clientName}. Valid for 60 minutes.

Path parameters

tenantNamestringRequired

Your organization (tenant) name, e.g. acme-health

Example: acme-health

instanceNamestringRequired

Your environment name: live, sandbox, or a custom name

Example: live

invoiceIdstring · uuidRequired

UUID of the invoice

Responses

200

Invoice.

Schema confirmed against the backend's outbound client to the invoice-service (InvoiceServiceApiClientImpl).

application/json

idstring · uuidOptional

customInvoiceIdstring · nullableOptional

statusstringOptional

Commonly one of: DRAFT, PENDING, VOIDED, PAID, PARTIALLY_PAID, OVERDUE, DELETED, PREAUTHORIZED.

billingTypestring · enumOptionalPossible values:

dueDatestring · date-time · nullableOptional

invoiceDatestring · date-time · nullableOptional

amountintegerOptional

Total in cents.

amountPaidintegerOptional

Amount paid in cents.

relatedEncountersstring · uuid[]Optional

400

Bad request — the request could not be understood or was missing required parameters.

401

Unauthorized — the Bearer token is missing, expired, or invalid.

403

Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin.

404

Not found — the requested resource does not exist.

429

Too many requests — rate limit exceeded. Implement exponential backoff.

500

Internal server error.

get/{tenantName}/{instanceName}/invoice/invoices/{invoiceId}

GET /{tenantName}/{instanceName}/invoice/invoices/{invoiceId} HTTP/1.1
Host: api.live.welkincloud.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "customInvoiceId": "text",
  "status": "text",
  "paymentTypeInfo": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "billingType": "SELF_PAY",
  "dueDate": "2026-01-01T00:00:00.000Z",
  "invoiceDate": "2026-01-01T00:00:00.000Z",
  "invoiceItems": [
    {
      "id": "text",
      "description": "text",
      "quantity": 1,
      "unitAmount": 1,
      "serviceCode": "text",
      "serviceModifiers": [
        "text"
      ]
    }
  ],
  "careMember": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text"
  },
  "patient": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text"
  },
  "amount": 1,
  "amountPaid": 1,
  "relatedEncounters": [
    "123e4567-e89b-12d3-a456-426614174000"
  ]
}

Get Invoices By Patient ID

get

Request to get all invoices for the patient.

Authorizations

AuthorizationstringRequired

Bearer token obtained from POST /{tenantName}/admin/api_clients/{clientName}. Valid for 60 minutes.

Path parameters

tenantNamestringRequired

Your organization (tenant) name, e.g. acme-health

Example: acme-health

instanceNamestringRequired

Your environment name: live, sandbox, or a custom name

Example: live

patientIdstring · uuidRequired

UUID of the patient record

Responses

200

Paginated list of invoices for this patient.

⚠️ Unverified: no backing REST controller for this exact path could be found in the backend source — invoicing is handled by a separate invoice-service, and this repo only contains a thin outbound HTTP client. The schema is inferred from that client's response deserialization and has not been directly confirmed against a live controller.

application/json

Standard paginated response wrapper.

totalElementsintegerOptional

Total number of matching records

totalPagesintegerOptional

Total number of pages

lastbooleanOptional

firstbooleanOptional

numberintegerOptional

Current page number (zero-based)

sizeintegerOptional

Page size

numberOfElementsintegerOptional

Number of elements on the current page

emptybooleanOptional

400

Bad request — the request could not be understood or was missing required parameters.

401

Unauthorized — the Bearer token is missing, expired, or invalid.

403

Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin.

404

Not found — the requested resource does not exist.

429

Too many requests — rate limit exceeded. Implement exponential backoff.

500

Internal server error.

get/{tenantName}/{instanceName}/invoice/patients/{patientId}/invoices

GET /{tenantName}/{instanceName}/invoice/patients/{patientId}/invoices HTTP/1.1
Host: api.live.welkincloud.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "content": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "customInvoiceId": "text",
      "status": "text",
      "paymentTypeInfo": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "billingType": "SELF_PAY",
      "dueDate": "2026-01-01T00:00:00.000Z",
      "invoiceDate": "2026-01-01T00:00:00.000Z",
      "invoiceItems": [
        {
          "id": "text",
          "description": "text",
          "quantity": 1,
          "unitAmount": 1,
          "serviceCode": "text",
          "serviceModifiers": [
            "text"
          ]
        }
      ],
      "careMember": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text"
      },
      "patient": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text"
      },
      "amount": 1,
      "amountPaid": 1,
      "relatedEncounters": [
        "123e4567-e89b-12d3-a456-426614174000"
      ]
    }
  ],
  "pageable": {
    "sort": {
      "sorted": true,
      "unsorted": true,
      "empty": true
    },
    "pageSize": 1,
    "pageNumber": 1,
    "offset": 1,
    "unpaged": true,
    "paged": true
  },
  "totalElements": 1,
  "totalPages": 1,
  "last": true,
  "first": true,
  "number": 1,
  "size": 1,
  "numberOfElements": 1,
  "empty": true,
  "sort": {
    "sorted": true,
    "unsorted": true,
    "empty": true
  }
}

Get Invoices By Encounter ID

get

Request to get all invoices for a specific encounter

Authorizations

AuthorizationstringRequired

Bearer token obtained from POST /{tenantName}/admin/api_clients/{clientName}. Valid for 60 minutes.

Path parameters

tenantNamestringRequired

Your organization (tenant) name, e.g. acme-health

Example: acme-health

instanceNamestringRequired

Your environment name: live, sandbox, or a custom name

Example: live

patientIdstring · uuidRequired

UUID of the patient record

encounterIdstring · uuidRequired

UUID of the encounter

Responses

200

Paginated list of invoices for this encounter.

Schema confirmed against the backend's outbound client to the invoice-service (InvoiceServiceApiClientImpl).

application/json

Standard paginated response wrapper.

totalElementsintegerOptional

Total number of matching records

totalPagesintegerOptional

Total number of pages

lastbooleanOptional

firstbooleanOptional

numberintegerOptional

Current page number (zero-based)

sizeintegerOptional

Page size

numberOfElementsintegerOptional

Number of elements on the current page

emptybooleanOptional

400

Bad request — the request could not be understood or was missing required parameters.

401

Unauthorized — the Bearer token is missing, expired, or invalid.

403

Forbidden — the API client role does not have permission for this resource. Check the role and security policy in Admin.

404

Not found — the requested resource does not exist.

429

Too many requests — rate limit exceeded. Implement exponential backoff.

500

Internal server error.

get/{tenantName}/{instanceName}/invoice/patients/{patientId}/encounters/{encounterId}/invoices

GET /{tenantName}/{instanceName}/invoice/patients/{patientId}/encounters/{encounterId}/invoices HTTP/1.1
Host: api.live.welkincloud.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "content": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "customInvoiceId": "text",
      "status": "text",
      "paymentTypeInfo": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "billingType": "SELF_PAY",
      "dueDate": "2026-01-01T00:00:00.000Z",
      "invoiceDate": "2026-01-01T00:00:00.000Z",
      "invoiceItems": [
        {
          "id": "text",
          "description": "text",
          "quantity": 1,
          "unitAmount": 1,
          "serviceCode": "text",
          "serviceModifiers": [
            "text"
          ]
        }
      ],
      "careMember": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text"
      },
      "patient": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text"
      },
      "amount": 1,
      "amountPaid": 1,
      "relatedEncounters": [
        "123e4567-e89b-12d3-a456-426614174000"
      ]
    }
  ],
  "pageable": {
    "sort": {
      "sorted": true,
      "unsorted": true,
      "empty": true
    },
    "pageSize": 1,
    "pageNumber": 1,
    "offset": 1,
    "unpaged": true,
    "paged": true
  },
  "totalElements": 1,
  "totalPages": 1,
  "last": true,
  "first": true,
  "number": 1,
  "size": 1,
  "numberOfElements": 1,
  "empty": true,
  "sort": {
    "sorted": true,
    "unsorted": true,
    "empty": true
  }
}