Cancelling an order depends how far along in the process the order is in. If an order is early enough in its lifecycle, i.e.:

  1. Requisition form is not generated.
  2. Order wasn’t send.
  3. The phlebotomist is not on their way.

It’s possible to cancel it by making a request to the cancel endpoint.

For at-home phlebotomy, cancel the appointment first if it has been scheduled. You can cancel a phlebotomy appointment by making a request to the phlebotomy appointment cancellation endpoint.

When it comes to cancelling an order, to avoid the financial costs associated with late cancelling, we advise the following:

  • For test-kits, we recommend cancelling the order before it’s shipped. Kits are typically shipped within 24 hours after they are ordered.
  • For at-home phlebotomy, appointments can be cancelled without consequence with a notice of at least 24 hours. Cancelling an order with less than 24h notice may incur a financial cost.

​
Cancel appointment endpoint

curl --request PATCH \
     --url '{{BASE_URL}}/v3/order/<order_id>/phlebotomy/appointment/cancel' \
     --header 'accept: application/json' \
     --header 'x-vital-api-key: {YOUR_KEY}' \
     --data '{"cancellation_reason_id": "7dfd7da5-ed6e-40bb-a7e4-c8003f0c10a9"}'

You will receive a response specifying awhether the order was successfully cancelled or not.

Appointent Cancellation response
{
    "id": "413d7205-f8a9-42ed-aa4a-edb99e481ca0",
    "user_id": "202b2c2f-fb4c-44dc-a4f8-621186fde227",
    "address": {
        "first_line": "West Lincoln Street",
        "second_line": "",
        "city": "Phoenix",
        "state": "AZ",
        "zip_code": "85004",
        "unit": "14"
    },
    "location": {
        "lng": -112.0772235,
        "lat": 33.4421912
    },
    "start_at": "2023-05-17T20:00:00+00:00",
    "end_at": "2023-05-17T22:00:00+00:00",
    "iana_timezone": "America/Phoenix",
    "type": "phlebotomy",
    "provider": "getlabs",
    "status": "cancelled",
    "provider_id": "e89eb489-7382-4966-bb14-7ab4763eba6c",
    "can_reschedule": true
}

​
Cancel endpoint

curl --request DELETE \
     --url {{BASE_URL}}/v3/lab_test/<order_id>/cancel \
     --header 'Accept: application/json' \
     --header 'x-vital-api-key: <API_KEY>' \
     --header 'Content-Type: application/json' \

You will receive a response specifying whether the order was successfully cancelled or not.

Cancellation response
{
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"),
        "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "patient_details": {"dob": "2020-01-01", "gender": "male"},
        "patient_address": {
            "receiver_name": "John Doe",
            "first_line": "123 Main St.",
            "second_line": "Apt. 208",
            "city": "San Francisco",
            "state": "CA",
            "zip": "91189",
            "country": "United States",
            "phone_number": "+1123456789",
        },
        "details": {
            "type": "testkit",
            "data": {
                "id": "a655f0e4-6405-4a1d-80b7-66f06c2108a7",
                "shipment": {
                    "id": "d55210cc-3d9f-4115-8262-5013f700c7be",
                    "outbound_tracking_number": "<outbound_tracking_number>",
                    "outbound_tracking_url": "<outbound_tracking_url>",
                    "inbound_tracking_number": "<inbound_tracking_number>",
                    "inbound_tracking_url": "<inbound_tracking_url>",
                    "outbound_courier": "usps",
                    "inbound_courier": "usps",
                    "notes": "<notes>",
                    "created_at": "2020-01-01T00:00:00.000Z",
                    "updated_at": "2020-01-01T00:00:00.000Z",
                },
                "created_at": "2020-01-01T00:00:00Z",
                "updated_at": "2020-01-01T00:00:00Z",
            },
        },
        "diagnostic_lab_test": {
            "name": "Lipids Panel",
            "description": "Cholesterol test",
            "method": "testkit",
        },
        "sample_id": "123456789",
        "notes": "This is a note",
        "created_at": "2020-01-01T00:00:00Z",
        "updated_at": "2020-01-01T00:00:00Z",
        "status": "cancelled",
        "events": [
            {
                "id": 1,
                "created_at": "2022-01-01T00:00:00Z",
                "status": "received.testkit.ordered",
            },
            {
                "id": 2,
                "created_at": "2022-01-01T00:00:00Z",
                "status": "cancelled.testkit.cancelled",
            }
    ],
}