API ReferenceTruemed Sessions

Create Shop Pay Truemed Session Auth Hold

Signal that you've placed the authorization hold on your own payment rail, ahead of clinical review. Truemed accepts the hold only once the shopper's intake is resolved — an early hold is rejected rather than held for a later survey. Once accepted, the session advances to `pending_truemed_review` and Letter of Medical Necessity review begins, or straight to `approved` for a pre-approved cart that needs no review. This is a status notification only and takes no request body.

Authentication

x-truemed-api-keystring

Platform API key for platform server-to-server authentication

Path parameters

truemed_session_idstringRequired
The Shop Pay Truemed session to record the authorization hold against.

Headers

x-truemed-shop-idstringRequired
The Shopify Shop GID for the authenticated Shop Pay store.

Response

Successful response
qualification_statusenum

The session’s qualification status after the hold is recorded — pending_truemed_review once the hold triggers LMN review, approved for a pre-approved cart or a reused verified LMN that needs no review, or rejected when the request was already declined.

One of:

  • pending_user_intake — The session was created; the shopper hasn’t completed intake yet.
  • pending_authorization — Intake is complete and the session is waiting for you to signal an authorization hold (or report a capture). That is what starts clinical review.
  • pending_truemed_review — Intake is complete and the session is under clinician review.
  • approved — A clinician approved every item that went to review, and the shopper now holds a valid Letter of Medical Necessity for the qualified items in this order. Items that were already ineligible at creation stay ineligible; see the per-item order_items breakdown for what qualified.
  • rejected — No qualifying items in this order. Either a clinician declined the request, or an item that started out eligible failed review. A cart with no HSA/FSA-eligible items lands here too, since there is nothing for a clinician to review.
  • canceled — The session was canceled before completion; no further qualification or capture activity will occur.
truemed_session_idstring
The Shop Pay Truemed session this auth hold is attached to.

Errors

400
Bad Request Error
404
Not Found Error
405
Method Not Allowed Error
500
Internal Server Error
501
Not Implemented Error