Create a consult-first request
curl --request POST \
--url https://vitarelay.com/api/public/v1/consult-requests \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"items": [
{
"product_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"quantity": 2
}
],
"shipping": {
"line1": "<string>",
"city": "<string>",
"state": "<string>",
"postal_code": "<string>",
"line2": "<string>",
"country": "<string>"
},
"patient_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"external_patient_id": "<string>",
"external_request_id": "<string>",
"shipping_method": "<string>",
"authorize_auto_charge": true
}
'import requests
url = "https://vitarelay.com/api/public/v1/consult-requests"
payload = {
"items": [
{
"product_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"quantity": 2
}
],
"shipping": {
"line1": "<string>",
"city": "<string>",
"state": "<string>",
"postal_code": "<string>",
"line2": "<string>",
"country": "<string>"
},
"patient_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"external_patient_id": "<string>",
"external_request_id": "<string>",
"shipping_method": "<string>",
"authorize_auto_charge": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
items: [{product_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a', quantity: 2}],
shipping: {
line1: '<string>',
city: '<string>',
state: '<string>',
postal_code: '<string>',
line2: '<string>',
country: '<string>'
},
patient_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
external_patient_id: '<string>',
external_request_id: '<string>',
shipping_method: '<string>',
authorize_auto_charge: true
})
};
fetch('https://vitarelay.com/api/public/v1/consult-requests', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://vitarelay.com/api/public/v1/consult-requests",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'items' => [
[
'product_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'quantity' => 2
]
],
'shipping' => [
'line1' => '<string>',
'city' => '<string>',
'state' => '<string>',
'postal_code' => '<string>',
'line2' => '<string>',
'country' => '<string>'
],
'patient_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'external_patient_id' => '<string>',
'external_request_id' => '<string>',
'shipping_method' => '<string>',
'authorize_auto_charge' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://vitarelay.com/api/public/v1/consult-requests"
payload := strings.NewReader("{\n \"items\": [\n {\n \"product_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"quantity\": 2\n }\n ],\n \"shipping\": {\n \"line1\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"postal_code\": \"<string>\",\n \"line2\": \"<string>\",\n \"country\": \"<string>\"\n },\n \"patient_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"external_patient_id\": \"<string>\",\n \"external_request_id\": \"<string>\",\n \"shipping_method\": \"<string>\",\n \"authorize_auto_charge\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://vitarelay.com/api/public/v1/consult-requests")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"items\": [\n {\n \"product_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"quantity\": 2\n }\n ],\n \"shipping\": {\n \"line1\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"postal_code\": \"<string>\",\n \"line2\": \"<string>\",\n \"country\": \"<string>\"\n },\n \"patient_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"external_patient_id\": \"<string>\",\n \"external_request_id\": \"<string>\",\n \"shipping_method\": \"<string>\",\n \"authorize_auto_charge\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://vitarelay.com/api/public/v1/consult-requests")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"items\": [\n {\n \"product_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"quantity\": 2\n }\n ],\n \"shipping\": {\n \"line1\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"postal_code\": \"<string>\",\n \"line2\": \"<string>\",\n \"country\": \"<string>\"\n },\n \"patient_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"external_patient_id\": \"<string>\",\n \"external_request_id\": \"<string>\",\n \"shipping_method\": \"<string>\",\n \"authorize_auto_charge\": true\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"external_request_id": "<string>",
"patient_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "awaiting_consult_payment",
"billing_mode": "patient",
"estimate": {
"medication_cents": 123,
"shipping_cents": 123,
"total_cents": 123
},
"auto_charge_authorized": true,
"consult_order_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"medication_order_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"proposal": {
"lines": [
{
"product_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"quantity": 123,
"unit_price_cents": 123
}
],
"shipping_cents": 123,
"total_cents": 123,
"needs_approval_reasons": [
"not_authorized"
]
},
"failure_reason": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"consult": {
"order_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"amount_cents": 123,
"paid": true
},
"authorization_text": "<string>",
"checkout": {}
}
}{
"error": {
"code": "validation_failed",
"message": "One or more fields are invalid"
}
}{
"error": {
"code": "validation_failed",
"message": "One or more fields are invalid"
}
}{
"error": {
"code": "validation_failed",
"message": "One or more fields are invalid"
}
}{
"error": {
"code": "validation_failed",
"message": "One or more fields are invalid"
}
}Orders
Create a consult-first request
Vita Clinic only. Requires the orders:write scope, and the clinic must have consult-first checkout switched on (otherwise 409 consult_first_not_available).
Consult first, medication after. The patient pays only the doctor consult now and is shown an estimate for the medication and shipping. The doctor network then reviews the request. When the doctor approves, one medication order is built from the script the doctor actually signed:
- If it is the same medication (any dose), the total is within the estimate, the request has
authorize_auto_charge: true, and the patient has a saved card, the card is charged automatically and the order is placed. - Otherwise nothing is charged: the request moves to
awaiting_patient_checkoutwith aproposal, and you callPOST /consult-requests/{id}/approveonce the patient agrees. - If the doctor declines, the request ends as
declined, no medication order is ever created, and nothing more is charged. The consult fee is not refundable.
A proposal never expires. Prices come from the clinic’s patient shop, never from the body. Prescription items only: order anything else with POST /orders.
Who pays the consult (billing_mode):
patient_checkout(default): the response carries acheckoutobject. Tokenize the patient’s card with Accept.js and send it toPOST /orders/{consult.order_id}/pay. The card is always saved to the patient, because the medication is charged to it later.card_on_file: the clinic’s card on file pays the consult immediately. The medication is still the patient’s to pay (a saved card, or a new one at approval).
Status changes are delivered as consult_request.updated webhooks. Send external_request_id to make the call idempotent: a repeat returns the same request.
POST
/
consult-requests
Create a consult-first request
curl --request POST \
--url https://vitarelay.com/api/public/v1/consult-requests \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"items": [
{
"product_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"quantity": 2
}
],
"shipping": {
"line1": "<string>",
"city": "<string>",
"state": "<string>",
"postal_code": "<string>",
"line2": "<string>",
"country": "<string>"
},
"patient_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"external_patient_id": "<string>",
"external_request_id": "<string>",
"shipping_method": "<string>",
"authorize_auto_charge": true
}
'import requests
url = "https://vitarelay.com/api/public/v1/consult-requests"
payload = {
"items": [
{
"product_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"quantity": 2
}
],
"shipping": {
"line1": "<string>",
"city": "<string>",
"state": "<string>",
"postal_code": "<string>",
"line2": "<string>",
"country": "<string>"
},
"patient_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"external_patient_id": "<string>",
"external_request_id": "<string>",
"shipping_method": "<string>",
"authorize_auto_charge": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
items: [{product_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a', quantity: 2}],
shipping: {
line1: '<string>',
city: '<string>',
state: '<string>',
postal_code: '<string>',
line2: '<string>',
country: '<string>'
},
patient_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
external_patient_id: '<string>',
external_request_id: '<string>',
shipping_method: '<string>',
authorize_auto_charge: true
})
};
fetch('https://vitarelay.com/api/public/v1/consult-requests', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://vitarelay.com/api/public/v1/consult-requests",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'items' => [
[
'product_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'quantity' => 2
]
],
'shipping' => [
'line1' => '<string>',
'city' => '<string>',
'state' => '<string>',
'postal_code' => '<string>',
'line2' => '<string>',
'country' => '<string>'
],
'patient_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'external_patient_id' => '<string>',
'external_request_id' => '<string>',
'shipping_method' => '<string>',
'authorize_auto_charge' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://vitarelay.com/api/public/v1/consult-requests"
payload := strings.NewReader("{\n \"items\": [\n {\n \"product_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"quantity\": 2\n }\n ],\n \"shipping\": {\n \"line1\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"postal_code\": \"<string>\",\n \"line2\": \"<string>\",\n \"country\": \"<string>\"\n },\n \"patient_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"external_patient_id\": \"<string>\",\n \"external_request_id\": \"<string>\",\n \"shipping_method\": \"<string>\",\n \"authorize_auto_charge\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://vitarelay.com/api/public/v1/consult-requests")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"items\": [\n {\n \"product_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"quantity\": 2\n }\n ],\n \"shipping\": {\n \"line1\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"postal_code\": \"<string>\",\n \"line2\": \"<string>\",\n \"country\": \"<string>\"\n },\n \"patient_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"external_patient_id\": \"<string>\",\n \"external_request_id\": \"<string>\",\n \"shipping_method\": \"<string>\",\n \"authorize_auto_charge\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://vitarelay.com/api/public/v1/consult-requests")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"items\": [\n {\n \"product_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"quantity\": 2\n }\n ],\n \"shipping\": {\n \"line1\": \"<string>\",\n \"city\": \"<string>\",\n \"state\": \"<string>\",\n \"postal_code\": \"<string>\",\n \"line2\": \"<string>\",\n \"country\": \"<string>\"\n },\n \"patient_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"external_patient_id\": \"<string>\",\n \"external_request_id\": \"<string>\",\n \"shipping_method\": \"<string>\",\n \"authorize_auto_charge\": true\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"external_request_id": "<string>",
"patient_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "awaiting_consult_payment",
"billing_mode": "patient",
"estimate": {
"medication_cents": 123,
"shipping_cents": 123,
"total_cents": 123
},
"auto_charge_authorized": true,
"consult_order_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"medication_order_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"proposal": {
"lines": [
{
"product_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"quantity": 123,
"unit_price_cents": 123
}
],
"shipping_cents": 123,
"total_cents": 123,
"needs_approval_reasons": [
"not_authorized"
]
},
"failure_reason": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"consult": {
"order_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"amount_cents": 123,
"paid": true
},
"authorization_text": "<string>",
"checkout": {}
}
}{
"error": {
"code": "validation_failed",
"message": "One or more fields are invalid"
}
}{
"error": {
"code": "validation_failed",
"message": "One or more fields are invalid"
}
}{
"error": {
"code": "validation_failed",
"message": "One or more fields are invalid"
}
}{
"error": {
"code": "validation_failed",
"message": "One or more fields are invalid"
}
}Authorizations
API key issued by VitaRelay. Send as Authorization: Bearer vr_live_…
(production) or Authorization: Bearer vr_test_… (sandbox).
Body
application/json
Minimum array length:
1Show child attributes
Show child attributes
Show child attributes
Show child attributes
The id you used when creating the patient. One of patient_id or external_patient_id is required.
Maximum string length:
128The delivery speed the patient picked (ground or overnight).
Available options:
patient_checkout, card_on_file The patient agreed to have their saved card charged for the medication and shipping, up to the estimate, once the doctor approves. Show the returned authorization_text where they decide. Default false.
Response
A repeat of an earlier call with the same external_request_id.