curl --request POST \
  --url https://vitarelay.com/api/public/practice/v1/orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "patient_id": "b3f1c2a4-0000-0000-0000-000000000001",
  "items": [
    {
      "platform_product_id": "8a1e6b90-503b-4b00-9000-000000000abc",
      "quantity": 2
    }
  ],
  "shipping_destination_type": "practice_office",
  "shipping_address": {
    "name": "Vital Glow — Men's and Women's Health",
    "line1": "1494 Lake Murray Boulevard STE A",
    "city": "Columbia",
    "state": "SC",
    "postal_code": "29212",
    "country": "US"
  },
  "external_order_id": "po-2026-0042"
}
EOF

{
  "data": {
    "order_id": "<string>",
    "order_number": "<string>",
    "status": "<string>",
    "escripts_created": 123,
    "sandbox": true,
    "idempotent_replay": true
  }
}

{
  "data": {
    "order_id": "<string>",
    "order_number": "<string>",
    "status": "<string>",
    "escripts_created": 123,
    "sandbox": true,
    "idempotent_replay": true
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

API Reference

Place an order for your own patient

Creates an order for any mix of R&D, 503B, and 503A products. For each 503A (patient-specific) line, VitaRelay records an external-source signed prescription whose prescriber identity is resolved from your roster by prescriber_npi.

A controlled substance requires the prescriber to have a DEA on file for the patient’s state; otherwise 422 controlled_requires_dea. Prescriber identity (name/DEA/license) is derived from your roster by NPI, never from the body.

The patient must belong to your practice; any other patient returns 404. external_order_id is an idempotency key — replaying a request with the same key returns the original order with idempotent_replay: true (HTTP 200).

Test keys return a simulated sandbox response and create no real rows.

Scope required: orders:write.

POST

orders

curl --request POST \
  --url https://vitarelay.com/api/public/practice/v1/orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "patient_id": "b3f1c2a4-0000-0000-0000-000000000001",
  "items": [
    {
      "platform_product_id": "8a1e6b90-503b-4b00-9000-000000000abc",
      "quantity": 2
    }
  ],
  "shipping_destination_type": "practice_office",
  "shipping_address": {
    "name": "Vital Glow — Men's and Women's Health",
    "line1": "1494 Lake Murray Boulevard STE A",
    "city": "Columbia",
    "state": "SC",
    "postal_code": "29212",
    "country": "US"
  },
  "external_order_id": "po-2026-0042"
}
EOF

{
  "data": {
    "order_id": "<string>",
    "order_number": "<string>",
    "status": "<string>",
    "escripts_created": 123,
    "sandbox": true,
    "idempotent_replay": true
  }
}

{
  "data": {
    "order_id": "<string>",
    "order_number": "<string>",
    "status": "<string>",
    "escripts_created": 123,
    "sandbox": true,
    "idempotent_replay": true
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Practice API key (vr_live_... or vr_test_...).

Body

application/json

items

object[]

required

Required array length: 1 - 50 elements

Show child attributes

shipping_destination_type

enum<string>

required

Available options:

practice_office,

patient_direct,

distributor_office

shipping_address

object

required

Show child attributes

patient_id

string<uuid>

Your own patient. Either this or external_patient_id is required.

external_patient_id

string

Your system's patient identifier (used when the patient was created via API).

prescriber_npi

string

Required only when the cart contains a 503A (patient-specific) product. Not needed for 503B office-stock or R&D orders.

Pattern: ^[0-9]{10}$

prescriptions

object[]

One line per 503A (patient-specific) product ordered. Not used for 503B office-stock or R&D.

Show child attributes

external_order_id

string

Idempotency key. Replays return the original order.

Response

Idempotent replay — the original order returned.

data

object

Show child attributes