Invoice

Invoices can be used to collect payments from patients. Invoices can be directly sent to the patient's email for a patient to complete or can be automatically collected if the patient's billing information is on file.

The invoice model

Name
id
Type
string
Description
Unique identifier for the invoice.
Name
object
Type
string
Description
Always 'invoice'.
Name
name
Type
string
Description
Name of the invoice
Name
patient
Type
string
Description
Patient invoice is associated with.
Name
service_facility
Type
string
Description
Service facility where the invoice services were provided.
Name
rendering_provider
Type
string
Description
Provider who rendered the services on this invoice.
Name
payment_id
Type
string
Description
Payment associated with this invoice.
Name
share_with_patient
Type
boolean
Description
Whether this invoice should be shared with the patient.
Name
coupons
Type
array of strings
Description
Coupons applied to this invoice.
Name
collection_method
Type
string
Description
Collection method for invoice.
Possible values:
charge_automatically
Name
comments
Type
array of strings
Description
Comments on this invoice.
Name
reviews
Type
array of objects
Description
Review history of the invoice.
Name
status_history
Type
array of objects
Description
Status history of the invoice.
Name
created_by
Type
string
Description
Creator of the invoice.
Name
created_at
Type
number
Description
Timestamp (in ISO 8601 format) of when the invoice was created.
Name
last_updated_at
Type
number
Description
Timestamp (in ISO 8601 format) of when this invoice was last updated.

Response

{
    "id": "invc_LNIRgmClsk0Oq6yMz6nQ",
    "object": "invoice",
    "name": "Physical Health Checkup — May 30, 2023",
    "patient": "user_Z1zXZKvqrpwxbznuW6lJ",
    "service_facility": "fac_8xK2pLm9QwNr5Tz4VbYh",
    "rendering_provider": "prov_3Hj7sKn2RxMt6Qz9WcVf",
    "payment_id": "pay_5SR7xXuPb45mtLZUKHtf",
    "share_with_patient": true,
    
    "line_items": [
        {
            "id": "li_9Zm4nKp2QxRt8Vz3WcYf",
            "service_type": "charge",
            "amount": 15000,
            "product": null,
            "quantity": 1,
            "name": "Office Visit - Established Patient"
        },
        {
            "id": "li_2Bp7sLm9RxNt5Qz4WcVh",
            "service_type": "product",
            "amount": 0,
            "product": "prdt_8Kj2pLn5QwMr3Vz6YbTf",
            "quantity": 2,
            "name": "Medical Supplies"
        }
    ],
    "coupons": ["coup_7Xm4nKp2QwRt8Vz3YcWf"],
    "collection_method": "charge_automatically",

    "comments": [
        "cmmt_18Efdm5UBJduDbioH1kp"
    ],
    "reviews": [
        {
            "status": "needs_review",
            "requested_by": "user_idjkvxZTqfJD734feQHa",
            "reviewer": "user_QtD0YaeDw4VyS9UPBpX4",
            "requested_at": "2024-04-03T04:12:01.781Z",
            "review_deadline": "2024-04-03T04:12:01.781Z",
            "reviewed_at": "2024-04-03T04:12:01.781Z"
        }
    ],
    "status_history": [
        {
            "status": "draft",
            "changed_by": "user_idjkvxZTqfJD734feQHa",
            "changed_at": "2024-04-03T04:12:01.781Z"
        },
        {
            "status": "paid",
            "changed_by": "user_idjkvxZTqfJD734feQHa",
            "changed_at": "2024-04-03T04:12:01.781Z"
        }
    ],
    "created_by": "user_Z1zXZKvqrpwxbznuW6lJ",
    "created_at": "2024-04-03T04:12:01.781Z",
    "last_updated_at": "2024-04-03T04:12:01.781Z"
}

POST/v2/invoices

Create an invoice

Creates a new invoice.

Required attributes

Name
name
Type
string
Description
Name of the invoice
Name
patient
Type
string
Description
Patient invoice is associated with.
Name
service_facility
Type
string
Description
Service facility where the invoice services were provided.
Name
rendering_provider
Type
string
Description
Provider who rendered the services on this invoice.
Name
collection_method
Type
string
Description
Collection method for invoice. Can only use 'charge_automatically' if patient has billing information on file.
Possible values:
charge_automatically
Name
created_by
Type
string
Description
Creator of the invoice.

Optional attributes

Name
payment_id
Type
string
Description
Payment associated with this invoice.
Name
share_with_patient
Type
boolean
Description
Whether this invoice should be shared with the patient. Defaults to false.
Name
coupons
Type
array of strings
Description
Coupons to apply to this invoice.
Name
status
Type
string
Description
Status of the invoice. Defaults to 'draft'.
Possible values:
draft
paid
uncollectible
void
refunded
Name
comments
Type
array of strings
Description
Comments on this invoice.
Name
reviews
Type
array of objects
Description
Review history of the invoice.

Response

  {
    "id": "invc_LNIRgmClsk0Oq6yMz6nQ",
    "object": "invoice",
    "name": "Physical Health Checkup — May 30, 2023",
    "patient": "user_Z1zXZKvqrpwxbznuW6lJ",
    "service_facility": "fac_8xK2pLm9QwNr5Tz4VbYh",
    "rendering_provider": "prov_3Hj7sKn2RxMt6Qz9WcVf",
    "payment_id": "pay_5SR7xXuPb45mtLZUKHtf",
    "share_with_patient": true,
    
    "line_items": [
        {
            "id": "li_9Zm4nKp2QxRt8Vz3WcYf",
            "service_type": "charge",
            "amount": 15000,
            "product": null,
            "quantity": 1,
            "name": "Office Visit - Established Patient"
        }
    ],
    "coupons": [],
    "collection_method": "charge_automatically",

    "comments": [{
        "id": "cmmt_op0jVVAdR23DgkQPpdX8",
        "object": "comment",
        "note": "note_2UxtAULYUrX7GVsTKePy",
        "comment": "This is a comment.",
        "created_by": "user_xeDpGyt67wTor93qKtS7",
        "created_at": "2024-04-10T13:20:21.724Z",
    }],
    "reviews": [
        {
            "status": "needs_review",
            "requested_by": "user_idjkvxZTqfJD734feQHa",
            "reviewer": "user_QtD0YaeDw4VyS9UPBpX4",
            "requested_at": "2024-04-03T04:12:01.781Z",
            "review_deadline": "2024-04-03T04:12:01.781Z",
            "reviewed_at": "2024-04-03T04:12:01.781Z"
        }
    ],
    "status_history": [
        {
            "status": "draft",
            "changed_by": "user_idjkvxZTqfJD734feQHa",
            "changed_at": "2024-04-03T04:12:01.781Z"
        },
        {
            "status": "paid",
            "changed_by": "user_idjkvxZTqfJD734feQHa",
            "changed_at": "2024-04-03T04:12:01.781Z"
        }
    ],
    "created_by": "user_Z1zXZKvqrpwxbznuW6lJ",
    "created_at": "2024-04-03T04:12:01.781Z",
    "last_updated_at": "2024-04-03T04:12:01.781Z"
}

GET/v2/invoices/:id

Retrieve an invoice

Retrieves the specified invoice.

Response

{
    "id": "invc_LNIRgmClsk0Oq6yMz6nQ",
    "object": "invoice",
    "name": "Physical Health Checkup — May 30, 2023",
    "patient": "user_Z1zXZKvqrpwxbznuW6lJ",
    "service_facility": "fac_8xK2pLm9QwNr5Tz4VbYh",
    "rendering_provider": "prov_3Hj7sKn2RxMt6Qz9WcVf",
    "payment_id": "pay_5SR7xXuPb45mtLZUKHtf",
    "share_with_patient": true,
    
    "line_items": [
        {
            "id": "li_9Zm4nKp2QxRt8Vz3WcYf",
            "service_type": "charge",
            "amount": 15000,
            "product": null,
            "quantity": 1,
            "name": "Office Visit - Established Patient"
        }
    ],
    "coupons": ["coup_7Xm4nKp2QwRt8Vz3YcWf"],
    "collection_method": "charge_automatically",

    "comments": [{
        "id": "cmmt_op0jVVAdR23DgkQPpdX8",
        "object": "comment",
        "note": "note_2UxtAULYUrX7GVsTKePy",
        "comment": "This is a comment.",
        "created_by": "user_xeDpGyt67wTor93qKtS7",
        "created_at": "2024-04-10T13:20:21.724Z",
    }],
    "reviews": [
        {
            "status": "needs_review",
            "requested_by": "user_idjkvxZTqfJD734feQHa",
            "reviewer": "user_QtD0YaeDw4VyS9UPBpX4",
            "requested_at": "2024-04-03T04:12:01.781Z",
            "review_deadline": "2024-04-03T04:12:01.781Z",
            "reviewed_at": "2024-04-03T04:12:01.781Z"
        }
    ],
    "status_history": [
        {
            "status": "draft",
            "changed_by": "user_idjkvxZTqfJD734feQHa",
            "changed_at": "2024-04-03T04:12:01.781Z"
        },
        {
            "status": "paid",
            "changed_by": "user_idjkvxZTqfJD734feQHa",
            "changed_at": "2024-04-03T04:12:01.781Z"
        }
    ],
    "created_by": "user_Z1zXZKvqrpwxbznuW6lJ",
    "created_at": "2024-04-03T04:12:01.781Z",
    "last_updated_at": "2024-04-03T04:12:01.781Z"
}

POST/v2/invoices/:id

Update an invoice

Updates the specified invoice object by setting the values of the parameters passed. Any other parameters not provided will not be modified. The invoice can only be updated if it's in the 'draft' status.

Required attributes

Optional attributes

Name
name
Type
string
Description
Name of the invoice
Name
patient
Type
string
Description
Patient invoice is associated with.
Name
service_facility
Type
string
Description
Service facility where the invoice services were provided.
Name
rendering_provider
Type
string
Description
Provider who rendered the services on this invoice.
Name
payment_id
Type
string
Description
Payment associated with this invoice.
Name
share_with_patient
Type
boolean
Description
Whether this invoice should be shared with the patient.
Name
line_items
Type
array of objects
Description
Line items on this invoice.
Name
coupons
Type
array of strings
Description
Coupons applied to this invoice.
Name
collection_method
Type
string
Description
Collection method for invoice. Can only use 'charge_automatically' if patient has billing information on file.
Possible values:
charge_automatically
Name
status
Type
string
Description
Status of the invoice.
Possible values:
draft
paid
uncollectible
void
refunded
Name
comments
Type
array of strings
Description
Comments on this invoice.
Name
reviews
Type
array of objects
Description
Review history of the invoice.

Response

{
    "id": "invc_LNIRgmClsk0Oq6yMz6nQ",
    "object": "invoice",
    "name": "Physical Health Checkup — May 30, 2023",
    "patient": "user_Z1zXZKvqrpwxbznuW6lJ",
    "service_facility": "fac_8xK2pLm9QwNr5Tz4VbYh",
    "rendering_provider": "prov_3Hj7sKn2RxMt6Qz9WcVf",
    "payment_id": "pay_5SR7xXuPb45mtLZUKHtf",
    "share_with_patient": true,
    
    "line_items": [
        {
            "id": "li_9Zm4nKp2QxRt8Vz3WcYf",
            "service_type": "charge",
            "amount": 15000,
            "product": null,
            "quantity": 1,
            "name": "Office Visit - Established Patient"
        }
    ],
    "coupons": ["coup_7Xm4nKp2QwRt8Vz3YcWf"],
    "collection_method": "charge_automatically",

    "comments": [{
        "id": "cmmt_op0jVVAdR23DgkQPpdX8",
        "object": "comment",
        "note": "note_2UxtAULYUrX7GVsTKePy",
        "comment": "This is a comment.",
        "created_by": "user_xeDpGyt67wTor93qKtS7",
        "created_at": "2024-04-10T13:20:21.724Z",
    }],
    "reviews": [
        {
            "status": "needs_review",
            "requested_by": "user_idjkvxZTqfJD734feQHa",
            "reviewer": "user_QtD0YaeDw4VyS9UPBpX4",
            "requested_at": "2024-04-03T04:12:01.781Z",
            "review_deadline": "2024-04-03T04:12:01.781Z",
            "reviewed_at": "2024-04-03T04:12:01.781Z"
        }
    ],
    "status_history": [
        {
            "status": "draft",
            "changed_by": "user_idjkvxZTqfJD734feQHa",
            "changed_at": "2024-04-03T04:12:01.781Z"
        },
        {
            "status": "paid",
            "changed_by": "user_Z1zXZKvqrpwxbznuW6lJ",
            "changed_at": "2024-04-03T04:12:01.781Z"
        }
    ],
    "created_by": "user_Z1zXZKvqrpwxbznuW6lJ",
    "created_at": "2024-04-03T04:12:01.781Z",
    "last_updated_at": "2024-04-03T04:12:01.781Z"
}

GET/v2/invoices

List all invoices

Returns a list of all invoices.

Response

{
  "object": "list",
  "data": [
    {
        "id": "invc_LNIRgmClsk0Oq6yMz6nQ",
        "object": "invoice",
        "name": "Physical Health Checkup — May 30, 2023",
        "patient": "user_Z1zXZKvqrpwxbznuW6lJ",
        "service_facility": "fac_8xK2pLm9QwNr5Tz4VbYh",
        "rendering_provider": "prov_3Hj7sKn2RxMt6Qz9WcVf",
        "payment_id": "pay_5SR7xXuPb45mtLZUKHtf",
        "share_with_patient": true,
        
        "line_items": [
            {
                "id": "li_9Zm4nKp2QxRt8Vz3WcYf",
                "service_type": "charge",
                "amount": 15000,
                "product": null,
                "quantity": 1,
                "name": "Office Visit - Established Patient"
            }
        ],
        "coupons": [],
        "collection_method": "charge_automatically",

        "comments": [
            "cmmt_18Efdm5UBJduDbioH1kp"
        ],
        "reviews": [
            {
                "status": "needs_review",
                "requested_by": "user_idjkvxZTqfJD734feQHa",
                "reviewer": "user_QtD0YaeDw4VyS9UPBpX4",
                "requested_at": 1684220332000,
                "review_deadline": 1686220332000,
                "reviewed_at": 1684220992000
            }
        ],
        "status_history": [
            {
                "status": "draft",
                "changed_by": "user_idjkvxZTqfJD734feQHa",
                "changed_at": "2024-04-03T04:12:01.781Z"
            },
            {
                "status": "paid",
                "changed_by": "user_idjkvxZTqfJD734feQHa",
                "changed_at": 2024-04-03T04:12:01.781Z
            }
        ],
        "created_by": "user_Z1zXZKvqrpwxbznuW6lJ",
        "created_at": "2024-04-03T04:12:01.781Z",
        "last_updated_at": "2024-04-03T04:12:01.781Z"
    },
  ]
}

DELETE/v2/invoices/:id

Delete an invoice

Deletes the specified invoice. An invoice can only be deleted if it's in the 'draft' status.

Response

{
    "id": "invc_LNIRgmClsk0Oq6yMz6nQ",
    "object": "invoice",
    "deleted": true
}