Create Truemed Session

The entry point to the Truemed Session API: submit the cart and Truemed returns the new session’s HSA/FSA eligibility decomposition alongside a hosted-survey redirect_url (or null when the shopper is already qualified). A session is always minted — including for an entirely ineligible cart — so the response is a uniform place to read eligibility, never a rejection. Send the shopper to the redirect URL when one is present; truemed_session.updated webhooks signal each qualification change, and a GET on the session reconciles its current state before you capture the charge on your own rail.

The entry point to the Truemed Session API: submit the cart and Truemed returns the new session's HSA/FSA eligibility decomposition alongside a hosted-survey `redirect_url` (or `null` when the shopper is already qualified). A session is always minted — including for an entirely ineligible cart — so the response is a uniform place to read eligibility, never a rejection. Send the shopper to the redirect URL when one is present; `truemed_session.updated` webhooks signal each qualification change, and a GET on the session reconciles its current state before you capture the charge on your own rail.

Authentication

x-truemed-api-keystring

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

Request

Request body for CreateTruemedSessionRequest

customer_emailstringRequired3-320 characters

The customer's email address.

customer_namestringRequired1-255 characters

The customer's full name.

idempotency_keystringRequired1-200 characters

A unique key making this request safely retryable.

order_itemslist of objectsRequired

The cart’s line items, with item-level pricing.

return_urlstringRequired1-4096 characters

Where to return the customer after they finish the qualification survey. Query the session afterward to read the final status and decide the next step.

user_idstringRequired1-255 characters

Your durable identifier for this customer. Send the same value every time you create a session for the same customer — it ties their sessions together and powers LMN reuse: a returning customer whose prior LMN covers the cart skips the survey.

customer_statestring or nullOptional=2 characters

The 2-letter ISO 3166-2:US code for the customer’s region, without the US- prefix. Required for compliance; send it when known (e.g. from the shipping address).

metadatastring or nullOptional<=4096 characters

Opaque value echoed back on responses and webhooks.

test_configobject or nullOptional

Test-mode controls for integration testing: bypass the survey, auto-complete checkout, and auto-verify the LMN. Rejected in production.

Response

Successful response

cart_infoobject

Eligibility statement about the cart, fully known at create time.

qualification_infoobject

Create-time qualification snapshot. Track progression via webhooks.

truemed_session_idstring

The unique ID for this Truemed session.

redirect_urlstring or null

The URL to send the customer to for the qualification survey.

Errors

400

Bad Request Error

404

Not Found Error

405

Method Not Allowed Error

500

Internal Server Error

501

Not Implemented Error

$	curl -X POST https://dev-api.truemed.com/api/v2/truemed_sessions/create \
>	-H "x-truemed-api-key: <apiKey>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"customer_email": "alex@example.com",
>	"customer_name": "Alex Morgan",
>	"idempotency_key": "shop-pay-checkout-1001",
>	"order_items": [
>	{
>	"name": "Recovery Knee Brace",
>	"price": 12000,
>	"quantity": 1,
>	"amount_details": {
>	"additional_charges_details": [
>	{
>	"amount_cents": 850,
>	"display_level": "tax",
>	"name": "Tax"
>	}
>	],
>	"discounts_details": [
>	{
>	"amount_cents": 1000,
>	"display_level": "line_item",
>	"name": "WELCOME10"
>	}
>	]
>	},
>	"item_id": "line_item_1",
>	"sku": "KNEE-BRACE-001"
>	}
>	],
>	"return_url": "https://merchant.example.com/checkout/truemed-return",
>	"user_id": "shopify_customer_7001",
>	"customer_state": "CA",
>	"metadata": "{\"shopify_order_id\":\"gid://shopify/Order/1001\"}"
>	}'

1	{
2	"cart_info": {
3	"cart_type": "all_eligible",
4	"eligible_amount_cents": 11850,
5	"ineligible_amount_cents": 0,
6	"preapproved_amount_cents": 0
7	},
8	"qualification_info": {
9	"qualification_status": "pending_user_intake",
10	"is_already_qualified": false
11	},
12	"truemed_session_id": "ts_01JZ7D4M3A8B9C0D1E2F3G4H5J",
13	"redirect_url": "https://app.truemed.com/survey/ts_01JZ7D4M3A8B9C0D1E2F3G4H5J"
14	}