curl --request POST \
--url https://vitarelay.com/api/public/v1/orders \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"external_order_id": "clinic-order-8890",
"external_patient_id": "clinic-patient-001",
"items": [
{
"product_id": "7c1f0f7e-9a2b-4f1d-9c33-1a2b3c4d5e6f",
"quantity": 1
}
],
"shipping": {
"line1": "22 Wellness Ave",
"city": "Tampa",
"state": "FL",
"postal_code": "33602",
"country": "US"
}
}
'import requests
url = "https://vitarelay.com/api/public/v1/orders"
payload = {
"external_order_id": "clinic-order-8890",
"external_patient_id": "clinic-patient-001",
"items": [
{
"product_id": "7c1f0f7e-9a2b-4f1d-9c33-1a2b3c4d5e6f",
"quantity": 1
}
],
"shipping": {
"line1": "22 Wellness Ave",
"city": "Tampa",
"state": "FL",
"postal_code": "33602",
"country": "US"
}
}
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({
external_order_id: 'clinic-order-8890',
external_patient_id: 'clinic-patient-001',
items: [{product_id: '7c1f0f7e-9a2b-4f1d-9c33-1a2b3c4d5e6f', quantity: 1}],
shipping: {
line1: '22 Wellness Ave',
city: 'Tampa',
state: 'FL',
postal_code: '33602',
country: 'US'
}
})
};
fetch('https://vitarelay.com/api/public/v1/orders', 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/orders",
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([
'external_order_id' => 'clinic-order-8890',
'external_patient_id' => 'clinic-patient-001',
'items' => [
[
'product_id' => '7c1f0f7e-9a2b-4f1d-9c33-1a2b3c4d5e6f',
'quantity' => 1
]
],
'shipping' => [
'line1' => '22 Wellness Ave',
'city' => 'Tampa',
'state' => 'FL',
'postal_code' => '33602',
'country' => 'US'
]
]),
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/orders"
payload := strings.NewReader("{\n \"external_order_id\": \"clinic-order-8890\",\n \"external_patient_id\": \"clinic-patient-001\",\n \"items\": [\n {\n \"product_id\": \"7c1f0f7e-9a2b-4f1d-9c33-1a2b3c4d5e6f\",\n \"quantity\": 1\n }\n ],\n \"shipping\": {\n \"line1\": \"22 Wellness Ave\",\n \"city\": \"Tampa\",\n \"state\": \"FL\",\n \"postal_code\": \"33602\",\n \"country\": \"US\"\n }\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/orders")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"external_order_id\": \"clinic-order-8890\",\n \"external_patient_id\": \"clinic-patient-001\",\n \"items\": [\n {\n \"product_id\": \"7c1f0f7e-9a2b-4f1d-9c33-1a2b3c4d5e6f\",\n \"quantity\": 1\n }\n ],\n \"shipping\": {\n \"line1\": \"22 Wellness Ave\",\n \"city\": \"Tampa\",\n \"state\": \"FL\",\n \"postal_code\": \"33602\",\n \"country\": \"US\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://vitarelay.com/api/public/v1/orders")
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 \"external_order_id\": \"clinic-order-8890\",\n \"external_patient_id\": \"clinic-patient-001\",\n \"items\": [\n {\n \"product_id\": \"7c1f0f7e-9a2b-4f1d-9c33-1a2b3c4d5e6f\",\n \"quantity\": 1\n }\n ],\n \"shipping\": {\n \"line1\": \"22 Wellness Ave\",\n \"city\": \"Tampa\",\n \"state\": \"FL\",\n \"postal_code\": \"33602\",\n \"country\": \"US\"\n }\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "sandbox_ord_5c1a9b2e",
"order_number": "VR-88901",
"status": "paid",
"total_cents": 12900,
"external_order_id": "clinic-order-8890"
}
}{
"data": {
"id": "sandbox_ord_5c1a9b2e",
"order_number": "VR-88901",
"status": "paid",
"total_cents": 12900,
"external_order_id": "clinic-order-8890"
},
"sandbox": true
}{
"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"
}
}{
"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"
}
}{
"error": {
"code": "validation_failed",
"message": "One or more fields are invalid"
}
}{
"error": {
"code": "validation_failed",
"message": "One or more fields are invalid"
}
}Create an order
Vita Clinic only. Requires the orders:write scope.
Prices are resolved from the catalog — the request body must not (and
cannot) contain prices or organization ids. Ordering a 503B product
returns 422 product_not_allowed.
With a live key the clinic’s card on file is charged synchronously:
success returns 201 with status: "paid"; a failure returns 402
with code card_required or payment_declined. When platform billing
is in dry-run mode the order is returned with
status: "awaiting_payment" and billing_dry_run: true.
Set billing_mode to patient_checkout to create an unpaid order
and receive a checkout block for embedded Accept.js payment on your
own page (see POST /orders//pay). In that mode no clinic card is
required, the response status is awaiting_payment, and the order
stays unpaid until the nonce is submitted. If card checkout is
temporarily unavailable the call fails with 503 payment_unavailable
before any order is created, so it is safe to retry.
With a test key (vr_test_) and billing_mode=patient_checkout, the
simulated order also returns a checkout block pointing at the test
Accept.js host, so you can build and exercise your card form. Sandbox
orders cannot be paid — their sandbox_ord_… ids are not accepted by
POST /orders//pay.
Pricing. With billing_mode=patient_checkout the patient is the payer,
so the order carries your clinic’s own storefront prices: a listed
product at its shop price, a package at the package price you set (spread
exactly over its products, so the lines add up to it). The shop’s doctor
consult fee (503A) and shipping line are added the same way as in your
storefront, total_cents and checkout.amount_cents are the full amount
the patient pays, and your markup accrues to you once the order is paid.
Pass shipping_method (ground or overnight) to carry the patient’s
delivery choice. With card_on_file / clinic_card your clinic pays, so
lines are billed at VitaRelay catalog price — you bill your own customer
yourself. If your storefront isn’t enabled, patient_checkout falls
back to catalog prices.
Clinic discount rules. A rule your clinic has set up, such as a
multi-item discount (a set amount off each product beyond the first),
applies to patient_checkout orders on its own when the cart
qualifies. You send nothing extra: the server decides. The discount is
already taken off total_cents and checkout.amount_cents, it is
reported as discount_cents, and it is funded from your clinic’s
markup (it can never exceed what your clinic earns on those lines), so
your earnings on the order are reduced by the same amount. Services
and subscription lines never count, and a rule can exclude specific
packages.
Supplying external_order_id makes the call idempotent. Replaying a
patient_checkout request whose order is still unpaid returns the same
order and its checkout block again.
curl --request POST \
--url https://vitarelay.com/api/public/v1/orders \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"external_order_id": "clinic-order-8890",
"external_patient_id": "clinic-patient-001",
"items": [
{
"product_id": "7c1f0f7e-9a2b-4f1d-9c33-1a2b3c4d5e6f",
"quantity": 1
}
],
"shipping": {
"line1": "22 Wellness Ave",
"city": "Tampa",
"state": "FL",
"postal_code": "33602",
"country": "US"
}
}
'import requests
url = "https://vitarelay.com/api/public/v1/orders"
payload = {
"external_order_id": "clinic-order-8890",
"external_patient_id": "clinic-patient-001",
"items": [
{
"product_id": "7c1f0f7e-9a2b-4f1d-9c33-1a2b3c4d5e6f",
"quantity": 1
}
],
"shipping": {
"line1": "22 Wellness Ave",
"city": "Tampa",
"state": "FL",
"postal_code": "33602",
"country": "US"
}
}
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({
external_order_id: 'clinic-order-8890',
external_patient_id: 'clinic-patient-001',
items: [{product_id: '7c1f0f7e-9a2b-4f1d-9c33-1a2b3c4d5e6f', quantity: 1}],
shipping: {
line1: '22 Wellness Ave',
city: 'Tampa',
state: 'FL',
postal_code: '33602',
country: 'US'
}
})
};
fetch('https://vitarelay.com/api/public/v1/orders', 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/orders",
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([
'external_order_id' => 'clinic-order-8890',
'external_patient_id' => 'clinic-patient-001',
'items' => [
[
'product_id' => '7c1f0f7e-9a2b-4f1d-9c33-1a2b3c4d5e6f',
'quantity' => 1
]
],
'shipping' => [
'line1' => '22 Wellness Ave',
'city' => 'Tampa',
'state' => 'FL',
'postal_code' => '33602',
'country' => 'US'
]
]),
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/orders"
payload := strings.NewReader("{\n \"external_order_id\": \"clinic-order-8890\",\n \"external_patient_id\": \"clinic-patient-001\",\n \"items\": [\n {\n \"product_id\": \"7c1f0f7e-9a2b-4f1d-9c33-1a2b3c4d5e6f\",\n \"quantity\": 1\n }\n ],\n \"shipping\": {\n \"line1\": \"22 Wellness Ave\",\n \"city\": \"Tampa\",\n \"state\": \"FL\",\n \"postal_code\": \"33602\",\n \"country\": \"US\"\n }\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/orders")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"external_order_id\": \"clinic-order-8890\",\n \"external_patient_id\": \"clinic-patient-001\",\n \"items\": [\n {\n \"product_id\": \"7c1f0f7e-9a2b-4f1d-9c33-1a2b3c4d5e6f\",\n \"quantity\": 1\n }\n ],\n \"shipping\": {\n \"line1\": \"22 Wellness Ave\",\n \"city\": \"Tampa\",\n \"state\": \"FL\",\n \"postal_code\": \"33602\",\n \"country\": \"US\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://vitarelay.com/api/public/v1/orders")
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 \"external_order_id\": \"clinic-order-8890\",\n \"external_patient_id\": \"clinic-patient-001\",\n \"items\": [\n {\n \"product_id\": \"7c1f0f7e-9a2b-4f1d-9c33-1a2b3c4d5e6f\",\n \"quantity\": 1\n }\n ],\n \"shipping\": {\n \"line1\": \"22 Wellness Ave\",\n \"city\": \"Tampa\",\n \"state\": \"FL\",\n \"postal_code\": \"33602\",\n \"country\": \"US\"\n }\n}"
response = http.request(request)
puts response.read_body{
"data": {
"id": "sandbox_ord_5c1a9b2e",
"order_number": "VR-88901",
"status": "paid",
"total_cents": 12900,
"external_order_id": "clinic-order-8890"
}
}{
"data": {
"id": "sandbox_ord_5c1a9b2e",
"order_number": "VR-88901",
"status": "paid",
"total_cents": 12900,
"external_order_id": "clinic-order-8890"
},
"sandbox": true
}{
"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"
}
}{
"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"
}
}{
"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
Exactly one of patient_id or external_patient_id is required.
1Show child attributes
Show child attributes
Your identifier for this order. Acts as an idempotency key.
Patient UUID, or a sandbox_pat_… id when using a test key.
Show child attributes
Show child attributes
Patient saved card. Required when any line has purchase=subscription (422 payment_method_required).
Patient saved address for shippable subscription lines (defaults to the preferred address). Service-only lines never require shipping; otherwise 422 shipping_required.
card_on_file (default) charges the Vita Clinic's stored card synchronously. patient_checkout creates the order UNPAID and returns a checkout object so the patient can pay on the partner's own page via Authorize.Net Accept.js — no card is required on the clinic.
card_on_file, patient_checkout patient_checkout only. The delivery speed the patient picked; it sets the shipping line added to the order. Anything else (or omitted) uses the standard ground rate for the cart.
ground, overnight Response
Idempotent replay of an existing external_order_id.
Show child attributes
Show child attributes
{
"id": "sandbox_ord_5c1a9b2e",
"order_number": "VR-88901",
"status": "paid",
"total_cents": 12900,
"external_order_id": "clinic-order-8890"
}