API ReferenceTruemed Sessions

Create Truemed Session Auth Hold

Signal that you placed an authorization hold on the shopper's card ahead of clinical review. This advances the session to `pending_truemed_review` and triggers Letter of Medical Necessity review once the shopper has completed the Truemed flow (or straight to `approved` for a pre-approved cart, which needs no review). This is a status notification only and takes no request body.

Authentication

x-truemed-api-keystring

Sales channel API key for merchant server-to-server authentication

Path parameters

truemed_session_idstringRequired
The Truemed session ID from the URL path.

Response

Successful response
auth_hold_idstring
Opaque identifier for the auth hold, returned by Truemed.
qualification_statusenum

The session’s qualification status after the call — pending_truemed_review once the auth hold triggers LMN review (intake already complete), pending_user_intake when the hold was stored ahead of intake completion, or approved for a pre-approved cart that needs no review.

One of:

  • pending_user_intake — The session was created; the shopper hasn’t completed intake yet.
  • pending_authorization — Intake is done — or was never needed — and the session is parked here until you 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 — The shopper holds a valid Letter of Medical Necessity covering the items in this order.
  • partially_approved — Review approved the shopper, but only part of the cart is HSA/FSA-eligible; the qualified per-item split is on order_items.
  • rejected — The shopper is ineligible for a Letter of Medical Necessity for the items in this order (including a cart that is entirely HSA/FSA-ineligible, which has no qualification path).
  • canceled — The session was canceled before completion; no further qualification or capture activity will occur.
truemed_session_idstring
The 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