Receipts

The iClinic Integration API returns payment receipts together with their line items. Amounts of money are always integers, in Vietnamese dong (VND).

Description	HTTP request
List receipts	`GET /receipts`
Get a receipt	`GET /receipts/{id}`

Revenue = the sum of paidAmount over the receipts whose deletedAt is null and whose status is neither CANCELLED nor REFUNDED, selected by receiptDate within the date range you want to total. This matches Doanh thu (Revenue) in the clinic's Báo cáo (Reports). The sum of total under the same conditions is Doanh thu dự kiến (Expected revenue).
Cancelled and refunded receipts are still returned, with their status, so you can tell a cancelled receipt from one that has not synced yet. A refund is always for the full amount collected.

List receipts

GET/api/integration/v1/receipts

Returns receipts with their line items, ordered by last update, oldest first. Cancelled and refunded receipts are still returned, with their status. Requires the receipts:read scope.

Query parameters

Parameter	Description
`updatedSince`string · date-timeoptional	Returns only records whose `updatedAt` is at or after this time. Use an ISO 8601 date-time with a time zone, for example `2026-10-01T00:00:00.000Z`. For how to use it, see Incremental sync.
`cursor`stringoptional	The `nextCursor` value from the previous page, exactly as returned. Omit it on the first page. See Pagination.
`limit`integeroptional	From 1 to 500. Default `200`.

Response 200

A page of receipts: { requestId, receipts, nextCursor }. Each element of receipts has the fields of a receipt, or is a deleted record (tombstone). If nextCursor is not null, there is a next page.

Errors

Error code	When
`INVALID_UPDATED_SINCE`400	`updatedSince` is not an ISO 8601 date-time with a time zone, or appears more than once.
`INVALID_CURSOR`400	`cursor` is not valid, or was issued by a different endpoint.
`INVALID_LIMIT`400	`limit` is not an integer from 1 to 500.
`UNKNOWN_PARAMETER`400	A parameter that is not listed under “Query parameters”, including one with a misspelled name.
`INSUFFICIENT_SCOPE`403	The API key does not have the `receipts:read` scope.

Every endpoint can also return 401, 429 and 5xx. See Error codes.

curl

curl -sS "https://iclinic.phongkhamhieploi.vn/api/integration/v1/receipts?limit=200" \
  -H "Authorization: Bearer $ICLINIC_API_KEY"

200 GET /receipts?limit=2

{
  "requestId": "req_7c1f3a",
  "receipts": [
    {
      "id": "e7d3b1a4-52c8-4f19-a0b6-9c4d8e2f1a37",
      "code": "HD-20261004-002",
      "patientId": "5b0d6a38-3f5a-4a52-8f7c-1d2e9c4b7a10",
      "encounterId": "3f0c9a52-6d1b-4e7a-9b1e-2a4c8d5e7f10",
      "total": 350000,
      "paidAmount": 350000,
      "paymentMethod": "CASH",
      "status": "PAID",
      "receiptDate": "2026-10-04",
      "lines": [
        {
          "name": "Khám chuyên khoa",
          "quantity": 1,
          "unitPrice": 200000,
          "total": 200000,
          "sourceType": "SERVICE"
        },
        {
          "name": "Vitamin B1",
          "quantity": 10,
          "unitPrice": 15000,
          "total": 150000,
          "sourceType": "MEDICATION"
        }
      ],
      "createdAt": "2026-10-04T08:10:00.000Z",
      "updatedAt": "2026-10-04T08:10:00.000Z",
      "deletedAt": null
    }
  ],
  "nextCursor": null
}

Get a receipt

GET/api/integration/v1/receipts/{id}

Returns one receipt with its line items by id, or a tombstone if the receipt was deleted. Requires the receipts:read scope.

Path parameters

Parameter	Description
`id`stringrequired	The `id` of the receipt: the `id` field of an element returned by List receipts.

Response 200

{ requestId, receipt }. receipt is either a receipt, with the fields listed under “A receipt”, or a tombstone.

A receipt

Field	Meaning
`id`string	Stable ID of the receipt. It never changes. Use it as the deduplication key.
`code`string	The receipt number shown to users. For reference only.
`patientId`string \| null	The `id` of the patient in `/patients`; `null` if the receipt is not linked to a patient record.
`encounterId`string \| null	The `encounterUuid` of the encounter that the receipt collects payment for; `null` for a retail receipt or a receipt that collects payment for a therapy plan.
`total`integer	The total payable on the receipt after discounts, in VND.
`paidAmount`integer	The amount collected, in VND. It includes advance payments that were deducted and later payments of a balance owed. For a `REFUNDED` receipt, this is the amount collected before the refund.
`paymentMethod`string	The payment method at the time the receipt was created, in uppercase. Common values are `CASH` (cash) and `BANK_TRANSFER` (bank transfer). Other values are possible; do not assume this list is complete.
`status`enum	`PAID` paid in full `PARTIAL` a balance is still owed `UNPAID` not paid `CANCELLED` cancelled (nothing was collected) `REFUNDED` refunded in full
`receiptDate`date	The date of payment, in the clinic's local time, as `YYYY-MM-DD`. Revenue is counted on this date.
`lines`array	The line items of the receipt.
`createdAt`date-time	When the record was created, in Coordinated Universal Time (UTC).
`updatedAt`date-time	When the record last changed (UTC). Together with `id`, it is the sort key for sync.
`deletedAt`null	Always `null` for a record that still exists.

Deleted record (tombstone)

Field	Meaning
`id`string	The `id` of the deleted receipt.
`deletedAt`date-time	When the record was deleted or merged (UTC). If this field has a value, the record is a tombstone: delete this record on your side.
`updatedAt`date-time	When the record last changed (UTC). Together with `id`, it is the sort key for sync.

Errors

Error code	When
`UNKNOWN_PARAMETER`400	The request has a query parameter. This endpoint accepts only `id` in the path.
`INSUFFICIENT_SCOPE`403	The API key does not have the `receipts:read` scope.
`NOT_FOUND`404	No record has this `id`, or the record belongs to another clinic. Both cases return an identical response.

Every endpoint can also return 401, 429 and 5xx. See Error codes.

curl

curl -sS "https://iclinic.phongkhamhieploi.vn/api/integration/v1/receipts/$RECEIPT_ID" \
  -H "Authorization: Bearer $ICLINIC_API_KEY"

200 GET /receipts/{id}

{
  "requestId": "req_7c1f3a",
  "receipt": {
    "id": "e7d3b1a4-52c8-4f19-a0b6-9c4d8e2f1a37",
    "code": "HD-20261004-002",
    "patientId": "5b0d6a38-3f5a-4a52-8f7c-1d2e9c4b7a10",
    "encounterId": null,
    "total": 350000,
    "paidAmount": 100000,
    "paymentMethod": "BANK_TRANSFER",
    "status": "PARTIAL",
    "receiptDate": "2026-10-04",
    "lines": [
      {
        "name": "Liệu trình châm cứu",
        "quantity": 1,
        "unitPrice": 350000,
        "total": 350000,
        "sourceType": "MANUAL"
      }
    ],
    "createdAt": "2026-10-04T08:10:00.000Z",
    "updatedAt": "2026-10-06T03:00:00.000Z",
    "deletedAt": null
  }
}

200 Deleted receipt

{
  "requestId": "req_7c1f3a",
  "receipt": {
    "id": "f1c4a7d9-8e25-4b63-9d0a-5c2e7b1f3a86",
    "deletedAt": "2026-10-05T03:00:00.000Z",
    "updatedAt": "2026-10-05T03:00:00.000Z"
  }
}