Event Types

VitaRelay emits the core order and intake events below. Every order/intake.reviewed payload includes event (the type) and occurred_at (ISO 8601 timestamp); the newer intake.submitted event uses the versioned envelope shown in its section. Storefront integrations also receive the full order lifecycle (order.cancelled, order.fulfilled, order.payment_failed) and subscription lifecycle events. Deliveries generated by the sandbox also include "sandbox": true.

In live, order_id, patient_id, and escript_id are UUIDs and order_number is the real order number. In sandbox, ids look like sandbox_ord_…, sandbox_pat_…, and sandbox_int_….

Order events

order.paid

Fires when the order’s card-on-file charge succeeds.

{
  "event": "order.paid",
  "order_id": "0f1f2c9e-2f30-4a1b-8b1c-6f4e9a0c1d22",
  "order_number": "VR-20260804-118342",
  "total_cents": 48900,
  "occurred_at": "2026-08-04T15:04:11.220Z"
}

order.shipped

Fires when the order ships and tracking is attached.

{
  "event": "order.shipped",
  "order_id": "0f1f2c9e-2f30-4a1b-8b1c-6f4e9a0c1d22",
  "order_number": "VR-20260804-118342",
  "status": "shipped",
  "tracking_number": "1Z999AA10123456784",
  "tracking_carrier": "ups",
  "tracking_url": "https://www.ups.com/track?tracknum=1Z999AA10123456784",
  "occurred_at": "2026-08-05T18:22:03.005Z"
}

order.delivered

Fires when the carrier reports delivery.

{
  "event": "order.delivered",
  "order_id": "0f1f2c9e-2f30-4a1b-8b1c-6f4e9a0c1d22",
  "order_number": "VR-20260804-118342",
  "status": "delivered",
  "tracking_number": "1Z999AA10123456784",
  "tracking_carrier": "ups",
  "tracking_url": "https://www.ups.com/track?tracknum=1Z999AA10123456784",
  "occurred_at": "2026-08-07T14:10:47.881Z"
}

order.exception

Fires when the carrier reports a delivery problem (failed attempt, return to sender, address issue, and similar).

{
  "event": "order.exception",
  "order_id": "0f1f2c9e-2f30-4a1b-8b1c-6f4e9a0c1d22",
  "order_number": "VR-20260804-118342",
  "tracking_status": "exception",
  "tracking_number": "1Z999AA10123456784",
  "tracking_carrier": "ups",
  "tracking_url": "https://www.ups.com/track?tracknum=1Z999AA10123456784",
  "occurred_at": "2026-08-06T09:31:12.400Z"
}

Intake events

Subscription events

Subscription webhooks use the versioned envelope and may include: subscription.created, subscription.updated, subscription.paused, subscription.resumed, subscription.canceled, subscription.renewed, subscription.payment_failed, and subscription.rx_hold. shop.item.updated fires when subscription settings change. Every subscription event’s data includes: subscription_id, patient_id, item_kind, item_id, quantity, cadence, status, paused_reason, next_charge_at. Event-specific extras: reason (paused), skipped_next (updated), order_id + charged_cents (renewed), order_id + held_item_count (rx_hold), and for subscription.payment_failed: order_id, attempt, max_attempts, next_retry_at, final. subscription.payment_failed fires on every failed attempt (retries after 2 and 3 more days). The third failure sets final: true, next_retry_at: null, and also emits subscription.paused with reason: "payment_failed".

{
  "id": "e2b1a0c9-1d2e-3f4a-5b6c-7d8e9f0a1b2c",
  "type": "subscription.payment_failed",
  "event": "subscription.payment_failed",
  "api_version": "2026-09-25",
  "created_at": "2026-09-25T10:00:00.000Z",
  "data": {
    "subscription_id": "0f1f2c9e-2f30-4a1b-8b1c-6f4e9a0c1d22",
    "patient_id": "3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
    "item_kind": "product",
    "item_id": "153cfbff-3d44-4501-9e45-7e7bf1ab130e",
    "quantity": 1,
    "cadence": "monthly",
    "status": "active",
    "paused_reason": null,
    "next_charge_at": "2026-09-27T10:00:00.000Z",
    "order_id": "7c6d5e4f-3a2b-1c0d-9e8f-4a7b8c6d5e4f",
    "attempt": 1,
    "max_attempts": 3,
    "next_retry_at": "2026-09-27T10:00:00.000Z",
    "final": false
  }
}

subscription.renewed, subscription.payment_failed, and subscription.rx_hold are never emitted while patient billing is in dry-run mode (no real charge happens). Created/updated/paused/resumed/canceled events emit normally in dry-run.

intake.reviewed

Intake reviewed / prescription signed. Fires the moment a prescriber signs the escript — this is the “Rx cleared” signal you should key fulfillment off of.

{
  "event": "intake.reviewed",
  "escript_id": "b93f0a7c-8d54-4b3a-9d20-1b4a7f2c5e10",
  "patient_id": "3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
  "status": "signed",
  "cart_ref": "clinic-cart-7781",
  "signed_at": "2026-08-04T14:58:02.117Z",
  "occurred_at": "2026-08-04T14:58:02.190Z"
}

intake.submitted

Fires the moment a patient completes a hosted (“Mode B”) intake via the intake.telemedcomplete.com link. Use it to know a self-served intake is in and ready to route to the IDN. PHI-free: it carries ids, category, and status only — never the patient’s answers. This event uses the versioned envelope (type + event + api_version + created_at + data).

{
  "id": "e2b1a0c9-1d2e-3f4a-5b6c-7d8e9f0a1b2c",
  "type": "intake.submitted",
  "event": "intake.submitted",
  "api_version": "2026-08-20",
  "created_at": "2026-08-30T06:16:54.000Z",
  "data": {
    "patient_id": "3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
    "intake_id": "b93f0a7c-8d54-4b3a-9d20-1b4a7f2c5e10",
    "category": "async",
    "status": "submitted",
    "submitted_at": "2026-08-30T06:16:50.000Z",
    "external_intake_id": "your-ref-123",
    "external_patient_id": "your-patient-ref-9"
  }
}

Sandbox deliveries

Events generated by the simulated sandbox lifecycle are identical in shape but carry "sandbox": true and sandbox ids:

{
  "event": "order.shipped",
  "order_id": "sandbox_ord_9f2c41ab",
  "order_number": "SBX-000412",
  "status": "shipped",
  "tracking_number": "SBXTEST0000001",
  "tracking_carrier": "ups",
  "tracking_url": "https://example.com/track/SBXTEST0000001",
  "occurred_at": "2026-08-04T15:20:00.000Z",
  "sandbox": true
}

Never treat a payload with "sandbox": true as a real clinical or financial event.

Getting Started

API Reference

Webhooks

Guides

Event Types

Event Types

Order events

order.paid

order.shipped

order.delivered

order.exception

Intake events

Subscription events

intake.reviewed

intake.submitted

Sandbox deliveries

​Event Types

​Order events

​order.paid

​order.shipped

​order.delivered

​order.exception

​Intake events

​Subscription events

​intake.reviewed

​intake.submitted

​Sandbox deliveries

Event Types

Order events

order.paid

order.shipped

order.delivered

order.exception

Intake events

Subscription events

intake.reviewed

intake.submitted

Sandbox deliveries