API Reference

Authentication

Include your secret API key in every request using one of:

• secret_key field in the JSON body
• X-Api-Key: vtc_… header
• Authorization: Bearer vtc_… header

Test API keys

Create a test key from your dashboard to exercise the same POST /orders contract without placing a real Shopify order. Test responses include a dummy scan_upload_url that will not start a live patient upload flow. Test calls are logged the same way as live keys.

Create order

Creates one FormFit mask line item on your clinic's Shopify B2B company with Net 30 payment terms. The order contact email is your clinic's Shopify B2B contact; the shipping address and patient name come from your request. By default Vitacore returns scan_upload_url so you can email the patient yourself. Set forge_sends_email_to_client to true to have Forge send the scan upload email directly to the patient (the link is omitted from the response when the email sends successfully).

Request body

{
  "secret_key": "vtc_your_secret_key_here",
  "patient_email": "patient@example.com",
  "patient_name": "Jane Doe",
  "phone": "+15551234567",
  "shipping_address": {
    "first_name": "Jane",
    "last_name": "Doe",
    "address1": "123 Main Street",
    "address2": "Apt 4",
    "city": "Portland",
    "province": "Oregon",
    "country": "United States",
    "country_code": "US",
    "zip": "97201"
  },
  "idempotency_key": "your-unique-request-id-optional",
  "mask_type": "cpap",
  "forge_sends_email_to_client": false
}

Required fields

• secret_key — your API key (or use header)
• patient_email — patient email (used for the scan upload link)
• patient_name — patient name (Shopify metafield + order notes)
• phone — patient phone number
• shipping_address — patient ship-to address

mask_type values

Both mask types are CPAP therapy masks. The API value cpap means full face, not CPAP therapy in general.

Optional fields

• idempotency_key — safe retries (min 8 chars)
• mask_type — cpap = Form Fit full face CPAP mask; nose = Form Fit nasal CPAP mask. Defaults to cpap when omitted.
• forge_sends_email_to_client — when true, Forge emails the patient the scan upload link (Shopify-style confirmation). Defaults to false. When the email sends successfully, scan_upload_url is omitted from the response.

Success response (201)

New orders return 201. Retrying with the same idempotency_key returns 200 with idempotent_replay: true and the original order data.

{
  "success": true,
  "data": {
    "idempotent_replay": false,
    "request_id": "a1b2c3…",
    "shopify_order_id": "5678901234",
    "shopify_order_name": "#1234",
    "vitacore_order_id": "ORD_5678901234",
    "patient_email": "patient@example.com",
    "patient_name": "Jane Doe",
    "forge_sends_email_to_client": false,
    "mask_type": "cpap",
    "scan_upload_url": "https://api.vitacore.com/api/portal/start-scan?order_id=ORD_5678901234&email=patient@example.com",
    "placed_at": "2026-05-29T12:00:00.000Z"
  }
}

When forge_sends_email_to_client is true

{
  "success": true,
  "data": {
    "idempotent_replay": false,
    "request_id": "a1b2c3…",
    "shopify_order_id": "5678901234",
    "shopify_order_name": "#1234",
    "vitacore_order_id": "ORD_5678901234",
    "patient_email": "patient@example.com",
    "patient_name": "Jane Doe",
    "forge_sends_email_to_client": true,
    "patient_scan_email_sent": true,
    "mask_type": "cpap",
    "placed_at": "2026-05-29T12:00:00.000Z"
  }
}

If patient_scan_email_sent is false, email delivery failed and scan_upload_url is included as a fallback.

Customize the patient email subject and body under Patient email in the developer portal. Placeholders like {{patient_first_name}} and {{mask_product_name}} (full face vs nasal CPAP product name) are filled in per order.

Errors

• 401 — invalid or revoked secret_key
• 400 — validation error (missing address fields, etc.)
• 403 — mask_type not allowed for your clinic
• 409 — idempotency_key reused by another key
• 422 — clinic not configured (missing FormFit variant, Shopify ordering disabled, or contact email not set)
• 502 — Shopify order creation failed

Order status

Poll production progress using the vitacore_order_id returned when you create an order (e.g. ORD_5678901234). Status is only available for orders placed with the same API key that created them. It matches what the patient sees on the portal: current manufacturing step and tracking when shipped.

Success response (200)

{
  "success": true,
  "data": {
    "vitacore_order_id": "ORD_5678901234",
    "shopify_order_id": "5678901234",
    "shopify_order_name": "#1234",
    "patient_email": "patient@example.com",
    "patient_name": "Jane Doe",
    "placed_at": "2026-05-29T12:00:00.000Z",
    "is_test": false,
    "scan_id": "SCAN_1779902370302_hzebwhy8e",
    "scan_status": "approved",
    "current_step_id": "printing",
    "current_step_label": "Printing",
    "progress_caption": "Printing in progress",
    "is_shipped": false,
    "is_cancelled": false,
    "cancelled_at": null,
    "tracking": null,
    "udi": null,
    "updated_at": "2026-06-11T20:00:00.000Z"
  }
}

After QA prints the FormFit UDI label, udi is set with GS1 fields: di (device identifier / GTIN), lot (7-character FUPC), production_date (YYYY-MM-DD), gs1_element_string (e.g. (01)00628678429093(11)260610(10)F4F0J5K), and printed_at. Before the label is printed, udi is null.

When shipped, tracking includes carrier, tracking_number, and optional shipped_date. Before the patient uploads a scan, scan_id is null and current_step_id is awaiting_scan. After cancellation, is_cancelled is true, cancelled_at is set, and current_step_id is cancelled.

Errors

• 401 — invalid or revoked API key
• 404 — unknown id, another clinic's order, or an order not placed with this API key

Cancel order

Cancel a partner-placed order before the patient uploads scan files (videos and calibration photo). Vitacore also cancels the Shopify order. Use the vitacore_order_id from create order. Only the same API key that placed the order may cancel it.

Cancellation is allowed while scan upload is incomplete and production has not started. Returns 409 once both videos and calibration are on file, mesh or print jobs have started, or the order has shipped.

Request body

{
  "reason": "Patient no longer needs mask",
  "partner_reference": "your-internal-ticket-optional"
}

Optional fields

• reason — free-text note stored on the order (max 512 chars)
• partner_reference — your clinic's ticket or reference id (max 128 chars)

Success response (200)

{
  "success": true,
  "data": {
    "vitacore_order_id": "ORD_5678901234",
    "shopify_order_id": "5678901234",
    "already_cancelled": false,
    "cancelled_at": "2026-06-22T20:15:00.000Z",
    "shopify_cancelled": true,
    "scan_upload_blocked": true
  }
}

If the order was already cancelled, already_cancelled is true and cancelled_at reflects the original cancellation time. Test keys skip the Shopify cancel call; shopify_cancelled is false because there is no live Shopify order.

Errors

• 401 — invalid or revoked API key
• 404 — unknown order, another clinic's order, or not placed with this API key
• 409 — scan upload complete, production or print jobs started, or order shipped

FUPC lookup

Look up patient and order details from the 7-character FUPC stamped on a FormFit mask. This is the same value as the UDI lot field (GS1 application identifier (10)) — you do not need the full UDI barcode string.

Results are scoped the same way as the full barcode lookup: you only receive data for masks tied to your clinic's orders or scans. Other clinics' FUPCs return 404.

POST accepts the same fields in the JSON body (fupc, optional request_type, optional secret_key if not using a header). Optional request_type defaults to patient. Other values: summary, clinical, manufacturing, qa, udi, order, full.

Success response (200)

{
  "success": true,
  "data": {
    "request_id": "a1b2c3…",
    "request_type": "patient",
    "barcode": {
      "raw": "O0R7T9E",
      "kind": "fupc",
      "fupc": "O0R7T9E",
      "gs1": null
    },
    "resolved": {
      "scan_id": "SCAN_1779902370302_hzebwhy8e",
      "order_id": "ORD_5678901234",
      "fupc": "O0R7T9E",
      "vm_job_id": "job-abc123",
      "shopify_order_id": "5678901234"
    },
    "patient": {
      "name": "Jane Doe",
      "email": "patient@example.com",
      "phone": "+15551234567",
      "label": null,
      "b2b_patient": { "label": "Jane D.", "phone": "+15551234567" },
      "shipping_address": { "…": "…" },
      "billing_address": null
    }
  }
}

Errors

• 401 — invalid or revoked API key
• 400 — FUPC is not 7 alphanumeric characters
• 404 — unknown FUPC, or mask belongs to another clinic

Barcode lookup

Same clinician-oriented data as FUPC lookup, but accepts a full GS1 UDI string, a raw FUPC, or a SCAN_… / ORD_… id. Scoped to your clinic's orders and scans.

Request parameters

• barcode — GS1 UDI element string, 7-char FUPC, SCAN_…, or ORD_…
• request_type — required. Same values as FUPC lookup: summary, patient, manufacturing, qa, udi, order, clinical, full

POST body: barcode, request_type, and optional secret_key. Success response shape matches FUPC lookup.

Errors

• 401 — invalid or revoked API key
• 400 — missing or invalid barcode / request_type
• 404 — unknown barcode, or mask belongs to another clinic

Clinic workflow

1. Call create order with patient details and shipping address.
2. Save vitacore_order_id from the response for status polling.
3. Either copy scan_upload_url and email the patient yourself, or set forge_sends_email_to_client: true and let Forge send the scan email.
4. Poll GET …/orders/{vitacore_order_id}/status for production progress and tracking.
5. To void an order before the patient uploads, call POST …/orders/{vitacore_order_id}/cancel.