Skip to main content
Order cancellation depends on the current status of your order and its collection method. Orders follow a finite state machine (FSM) pattern with specific rules governing when cancellation is permitted.
Important timing considerations to avoid financial costs:
  • At-home phlebotomy: Appointments cancelled more than 24 hours in advance will be fully refunded. Cancellations made less than 24 hours before the scheduled appointment are non-refundable.
  • Testkits: Cancel before shipment to avoid fees. Testkits typically ship within the same business day if orders are placed before 1pm EST.
  • Walk-in tests: Can generally be cancelled until sample collection begins
  • On-site collection: Cancel before the collection event

​
When Orders Can Be Cancelled

​
✅ Generally Cancellable States

All collection methods allow cancellation during these early phases:
  • ordered - Initial order placement
  • requisition_created - After requisition form is generated
  • requisition_bypassed - When requisition is bypassed
  • awaiting_registration - For registrable testkits

​
❌ Never Cancellable (Terminal States)

Orders cannot be cancelled once they reach these states:
  • Already cancelled: cancelled, do_not_process
  • Completed: completed, partial_results
  • Failed: lost, sample_error, failure_to_deliver_to_customer, failure_to_deliver_to_lab

​
Collection Method Specific Rules

  • Walk-In Tests
  • At-Home Phlebotomy
  • Testkits
  • On-Site Collection
✅ Can cancel:
  • received.walk_in_test.ordered
  • received.walk_in_test.requisition_created
  • received.walk_in_test.requisition_bypassed
  • collecting_sample.walk_in_test.appointment_scheduled
  • collecting_sample.walk_in_test.appointment_cancelled
  • collecting_sample.walk_in_test.appointment_pending
  • collecting_sample.walk_in_test.redraw_available
❌ Cannot cancel once collection begins:
  • cancelled.walk_in_test.cancelled - Already cancelled
  • completed.walk_in_test.completed - Order completed
  • sample_with_lab.walk_in_test.partial_results - Has partial results
  • failed.walk_in_test.sample_error - Sample error occurred
Cancelling a walk-in test order does not automatically cancel PSC appointments to prevent a poor patient experience, as it could lead to a patient arriving and their appointment being cancelled. Use the PSC appointment cancellation endpoint if you need to cancel the appointment separately. Orders can be reinstated by our support team if a patient shows up for an appointment related to a cancelled order.

​
How to Cancel

​
Cancel Appointment (Optional - For Reference Only)

Note: You can skip this step and go directly to cancelling the order. The system will automatically cancel at-home phlebotomy appointments when you cancel the order, but will not automatically cancel walk-in PSC appointments to avoid a poor patient experience where they arrive and their appointment is cancelled.
If you need to cancel only the appointment (without cancelling the entire order), use the appropriate endpoint for your collection method:

​
At-Home Phlebotomy Appointment Cancellation

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

​
Walk-In Test (PSC) Appointment Cancellation

For walk-in tests scheduled at Patient Service Centers, use the PSC appointment cancellation endpoint: 
curl --request DELETE \
     --url '{{BASE_URL}}/v3/order/<order_id>/appointment/psc/cancel' \
     --header 'accept: application/json' \
     --header 'x-vital-api-key: {YOUR_KEY}'

​
Cancel the Order

Use the order cancellation endpoint to cancel any lab test order.
Automatic Appointment Handling:
  • At-home phlebotomy: Appointments are automatically cancelled when you cancel the order
  • Walk-in PSC: Appointments are not automatically cancelled to prevent poor patient experience if they show up. Orders can be reinstated if needed.
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' \

​
Error Handling

When attempting to cancel an order that cannot be cancelled, you’ll receive an error response:
Error Response
{
  "error": "Bad Request",
  "message": "Transition from current_status to cancelled is not allowed",
  "status_code": 400
}
Common reasons for cancellation failure:
  • Order is already in a terminal state (completed, failed, or cancelled)
  • Testkit has already shipped
  • Sample has been collected or is with the lab
  • Results are already available (partial or complete)

​
Checking Cancellation Eligibility

Before attempting cancellation, check the order’s current status using the get order endpoint:
Check Order Status
curl --request GET \
     --url {{BASE_URL}}/v3/order/<order_id> \
     --header 'x-vital-api-key: <API_KEY>'
Look for these indicators in the response:
  • status field shows the current high-level status
  • events array shows the detailed state progression
  • Orders in early states (ordered, requisition_created) are typically cancellable
  • Orders with cancelled, completed, or failed status cannot be cancelled

​
Response Examples

​
Successful Cancellation

Cancellation Success 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",
            }
    ],
}

​
Successful Appointment Cancellation

Appointment 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
}
For questions about specific cancellation scenarios, please contact support at support@junction.com