Create Shop Pay Truemed Session

Create a Truemed session for a Shop Pay self-processed checkout. Submit the cart to start HSA/FSA qualification; the response returns the cart’s eligibility breakdown, the current qualification status, and — when shopper intake is required — a redirect_url to the hosted survey.

Creating a session does not place an authorization hold, capture funds, or start a new clinical review. It only records the cart and reports the next shopper step.

Idempotency

Send a unique idempotency_key to make this request safely retryable. Keys are scoped to the shop (resolved from x-truemed-shop-id), so the same key never collides across shops.

If the same idempotency_key is sent again with a request whose key fields match the original, the original session is returned unchanged. If the key is reused with a request that differs on any key field, the call fails with 400 IdempotencyViolation naming the field(s) that diverged.

Key fields included in the idempotency comparison:

customer_email — compared case-insensitively
user_id
order_items — including each line’s amount_details; the cart total is derived from these
return_url

Fields that are not part of the comparison — a differing value is ignored and the original session is returned — are customer_name, metadata, and customer_state.

Create a Truemed session for a Shop Pay self-processed checkout. Submit the cart to start HSA/FSA qualification; the response returns the cart's eligibility breakdown, the current qualification status, and — when shopper intake is required — a `redirect_url` to the hosted survey. Creating a session does not place an authorization hold, capture funds, or start a new clinical review. It only records the cart and reports the next shopper step. ## Idempotency Send a unique `idempotency_key` to make this request safely retryable. Keys are scoped to the shop (resolved from `x-truemed-shop-id`), so the same key never collides across shops. If the same `idempotency_key` is sent again with a request whose key fields match the original, the original session is returned unchanged. If the key is reused with a request that differs on any key field, the call fails with `400 IdempotencyViolation` naming the field(s) that diverged. Key fields included in the idempotency comparison: - `customer_email` — compared case-insensitively - `user_id` - `order_items` — including each line's `amount_details`; the cart total is derived from these - `return_url` Fields that are **not** part of the comparison — a differing value is ignored and the original session is returned — are `customer_name`, `metadata`, and `customer_state`.

Authentication

x-truemed-api-keystring

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

Request

Request body for ShopPayCreateTruemedSessionRequest

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. Stored on the session, echoed back on responses, and included in the idempotency comparison — replaying an idempotency_key with a different user_id is rejected.

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, when one is required.

Errors

400

Bad Request Error

404

Not Found Error

405

Method Not Allowed Error

500

Internal Server Error

501

Not Implemented Error

Creating a session does not place an authorization hold, capture funds, or start a new clinical review. It only records the cart and reports the next shopper step.

Idempotency

Send a unique idempotency_key to make this request safely retryable. Keys are scoped to the shop (resolved from x-truemed-shop-id), so the same key never collides across shops.

Key fields included in the idempotency comparison:

customer_email — compared case-insensitively
user_id
order_items — including each line’s amount_details; the cart total is derived from these
return_url

Fields that are not part of the comparison — a differing value is ignored and the original session is returned — are customer_name, metadata, and customer_state.

$	curl -X POST https://dev-api.truemed.com/api/v2/shop_pay/truemed_sessions/create \
>	-H "x-truemed-api-key: <apiKey>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"customer_email": "string",
>	"customer_name": "string",
>	"idempotency_key": "string",
>	"order_items": [
>	{
>	"name": "string",
>	"price": 1,
>	"quantity": 1,
>	"sku": "string"
>	}
>	],
>	"return_url": "string",
>	"user_id": "string"
>	}'

1	{
2	"cart_info": {
3	"eligible_amount_cents": 1,
4	"ineligible_amount_cents": 1,
5	"preapproved_amount_cents": 1
6	},
7	"qualification_info": {
8	"qualification_status": "pending_user_intake"
9	},
10	"truemed_session_id": "string",
11	"redirect_url": "string"
12	}