Cancelling an Order

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:

Mobile 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.
Test kits: Cancel before shipment to avoid fees. Test kits typically ship within the same business day if orders are placed before 1 PM ET.
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 test kits

❌ 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
Mobile Phlebotomy
Test Kits
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

❌ 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
collecting_sample.walk_in_test.redraw_available - Order marked as final but has missing results
failed.walk_in_test.sample_error - Sample error occurred

Cancelling a walk-in test order does not automatically cancel PSC appointments. Use the PSC appointment cancellation endpoint to cancel the appointment separately.

✅ Can cancel:

received.at_home_phlebotomy.ordered
received.at_home_phlebotomy.requisition_created
received.at_home_phlebotomy.requisition_bypassed
collecting_sample.at_home_phlebotomy.appointment_pending
collecting_sample.at_home_phlebotomy.appointment_scheduled
collecting_sample.at_home_phlebotomy.appointment_cancelled
collecting_sample.at_home_phlebotomy.draw_completed

❌ Cannot cancel once collection begins:

cancelled.at_home_phlebotomy.cancelled - Already cancelled
completed.at_home_phlebotomy.completed - Order completed
sample_with_lab.at_home_phlebotomy.partial_results - Has partial results
failed.at_home_phlebotomy.sample_error - Sample error occurred

You can cancel the order directly - the system will automatically cancel any scheduled mobile phlebotomy appointments. Appointments cancelled with less than 24 hours’ notice are non-refundable.

✅ Can cancel:

received.testkit.ordered
received.testkit.awaiting_registration
received.testkit.requisition_created
received.testkit.requisition_bypassed
received.testkit.testkit_registered

❌ Cannot cancel once shipped:

collecting_sample.testkit.out_for_delivery
collecting_sample.testkit.transit_customer
collecting_sample.testkit.with_customer
collecting_sample.testkit.transit_lab
sample_with_lab.testkit.delivered_to_lab

Test kits become non-cancellable once they enter the shipping phase to avoid logistics costs. Test kits typically ship within the same business day if orders are placed before 1 PM ET.

✅ Can cancel:

received.on_site_collection.ordered
received.on_site_collection.requisition_created
received.on_site_collection.requisition_bypassed
collecting_sample.on_site_collection.draw_completed

❌ Cannot cancel once collection begins:

cancelled.on_site_collection.cancelled - Already cancelled
completed.on_site_collection.completed - Order completed
sample_with_lab.on_site_collection.partial_results - Has partial results
failed.on_site_collection.sample_error - Sample error occurred

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 mobile 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:

Mobile phlebotomy: Appointment Cancellation endpoint
Walk-in tests (PSC): PSC Appointment Cancellation endpoint

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

from junction import Junction
from junction.environment import JunctionEnvironment

client = Junction(
    api_key="YOUR_API_KEY",
    environment=JunctionEnvironment.SANDBOX,
)

client.lab_tests.cancel_phlebotomy_appointment(
    "<order_id>",
    cancellation_reason_id="<cancellation_reason_id>",
)

import { JunctionClient, JunctionEnvironment } from "@junction-api/sdk";

const client = new JunctionClient({
    apiKey: "YOUR_API_KEY",
    environment: JunctionEnvironment.Sandbox,
});

const data = await client.labTests.cancelPhlebotomyAppointment({
    orderId: "<order_id>",
    cancellationReasonId: "<cancellation_reason_id>",
});

import com.junction.api.Junction;
import com.junction.api.core.Environment;
import com.junction.api.resources.labtests.requests.ApiApiV1EndpointsVitalApiLabTestingOrdersHelpersAppointmentCancelRequest;

Junction client = Junction.builder()
    .apiKey("YOUR_API_KEY")
    .environment(Environment.SANDBOX)
    .build();

var data = client.labTests().cancelPhlebotomyAppointment(
    "<order_id>",
    ApiApiV1EndpointsVitalApiLabTestingOrdersHelpersAppointmentCancelRequest.builder()
        .cancellationReasonId("<cancellation_reason_id>")
        .build()
);

import (
    "context"

    junction "github.com/junction-api/junction-go"
    "github.com/junction-api/junction-go/client"
    "github.com/junction-api/junction-go/option"
)

c := client.NewClient(
    option.WithApiKey("YOUR_API_KEY"),
    option.WithBaseURL(junction.Environments.Sandbox),
)

response, err := c.LabTests.CancelPhlebotomyAppointment(context.TODO(), &junction.ApiApiV1EndpointsVitalApiLabTestingOrdersHelpersAppointmentCancelRequest{
    OrderId:              "<order_id>",
    CancellationReasonId: "<cancellation_reason_id>",
})
if err != nil {
    return err
}
fmt.Printf("Received data %s\n", response)

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

from junction import Junction
from junction.environment import JunctionEnvironment

client = Junction(
    api_key="YOUR_API_KEY",
    environment=JunctionEnvironment.SANDBOX,
)

client.lab_tests.cancel_psc_appointment(
    "<order_id>",
    cancellation_reason_id="<cancellation_reason_id>",
)

import { JunctionClient, JunctionEnvironment } from "@junction-api/sdk";

const client = new JunctionClient({
    apiKey: "YOUR_API_KEY",
    environment: JunctionEnvironment.Sandbox,
});

const data = await client.labTests.cancelPscAppointment({
    orderId: "<order_id>",
    cancellationReasonId: "<cancellation_reason_id>",
});

import com.junction.api.Junction;
import com.junction.api.core.Environment;
import com.junction.api.resources.labtests.requests.VitalCoreClientsLabTestGetlabsSchemaAppointmentCancelRequest;

Junction client = Junction.builder()
    .apiKey("YOUR_API_KEY")
    .environment(Environment.SANDBOX)
    .build();

var data = client.labTests().cancelPscAppointment(
    "<order_id>",
    VitalCoreClientsLabTestGetlabsSchemaAppointmentCancelRequest.builder()
        .cancellationReasonId("<cancellation_reason_id>")
        .build()
);

import (
    "context"

    junction "github.com/junction-api/junction-go"
    "github.com/junction-api/junction-go/client"
    "github.com/junction-api/junction-go/option"
)

c := client.NewClient(
    option.WithApiKey("YOUR_API_KEY"),
    option.WithBaseURL(junction.Environments.Sandbox),
)

response, err := c.LabTests.CancelPscAppointment(context.TODO(), &junction.VitalCoreClientsLabTestGetlabsSchemaAppointmentCancelRequest{
    OrderId:              "<order_id>",
    CancellationReasonId: "<cancellation_reason_id>",
})
if err != nil {
    return err
}
fmt.Printf("Received data %s\n", response)

Cancel the Order

Use the order cancellation endpoint to cancel any lab test order.

Automatic Appointment Handling:

Mobile 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'

from junction import Junction
from junction.environment import JunctionEnvironment

client = Junction(
    api_key="YOUR_API_KEY",
    environment=JunctionEnvironment.SANDBOX,
)

data = client.lab_tests.cancel_order("<order_id>")

import { JunctionClient, JunctionEnvironment } from "@junction-api/sdk";

const client = new JunctionClient({
    apiKey: "YOUR_API_KEY",
    environment: JunctionEnvironment.Sandbox,
});

const data = await client.labTests.cancelOrder({ orderId: "<order_id>" });

import com.junction.api.Junction;
import com.junction.api.core.Environment;

Junction client = Junction.builder()
    .apiKey("YOUR_API_KEY")
    .environment(Environment.SANDBOX)
    .build();

var data = client.labTests().cancelOrder("<order_id>");

import (
    "context"

    junction "github.com/junction-api/junction-go"
    "github.com/junction-api/junction-go/client"
    "github.com/junction-api/junction-go/option"
)

c := client.NewClient(
    option.WithApiKey("YOUR_API_KEY"),
    option.WithBaseURL(junction.Environments.Sandbox),
)

response, err := c.LabTests.CancelOrder(context.TODO(), &junction.CancelOrderLabTestsRequest{
    OrderId: "<order_id>",
})
if err != nil {
    return err
}
fmt.Printf("Received data %s\n", response)

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)
Test kit 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 a specific cancellation scenario, contact Junction support.

Getting Started

Ordering Workflows

Walk-in (Patient Service Center) Orders

Mobile Phlebotomy Orders

At-Home Test Kit Orders

On-site Collection Orders

Results and Follow-up

Lab Report Parsing

Cancelling an Order

When Orders Can Be Cancelled

✅ Generally Cancellable States

❌ Never Cancellable (Terminal States)

Collection method-specific rules

How to Cancel

Cancel Appointment (Optional - For Reference Only)

Mobile Phlebotomy Appointment Cancellation

Walk-in Test (PSC) Appointment Cancellation

Cancel the Order

Error Handling

Checking Cancellation Eligibility

Response Examples

Successful Cancellation

Successful Appointment Cancellation

​When Orders Can Be Cancelled

​✅ Generally Cancellable States

​❌ Never Cancellable (Terminal States)

​Collection method-specific rules

​How to Cancel

​Cancel Appointment (Optional - For Reference Only)

​Mobile Phlebotomy Appointment Cancellation

​Walk-in Test (PSC) Appointment Cancellation

​Cancel the Order

​Error Handling

​Checking Cancellation Eligibility

​Response Examples

​Successful Cancellation

​Successful Appointment Cancellation

​Related Resources

When Orders Can Be Cancelled

✅ Generally Cancellable States

❌ Never Cancellable (Terminal States)

Collection method-specific rules

How to Cancel

Cancel Appointment (Optional - For Reference Only)

Mobile Phlebotomy Appointment Cancellation

Walk-in Test (PSC) Appointment Cancellation

Cancel the Order

Error Handling

Checking Cancellation Eligibility

Response Examples

Successful Cancellation

Successful Appointment Cancellation

Related Resources