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
cart_shipping — via the cart total it contributes to: a replay whose shipping amounts move the total is rejected naming cart_shipping
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.

Request Notes

Shipping

Charge your customers for shipping without distorting the eligibility split. Shopify surfaces order-wide shipping as a single cart-level ShippingLine with no per-item allocation, so shipping is reported exclusively on the optional cart_shipping object — line amount_details entries do not accept a shipping display level:

cart_shipping.amount_cents — the cart/order-level shipping charge, in cents.
cart_shipping.tax_cents — tax on that shipping, in cents, when charged separately. Optional.

When present, cart_shipping is added to the authorized total and rendered in the receipt’s Shipping row; it does not move the cart’s eligible or ineligible amounts. It is echoed back on the response cart_info as shipping_amount_cents and shipping_tax_cents.

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` - `cart_shipping` — via the cart total it contributes to: a replay whose shipping amounts move the total is rejected naming `cart_shipping` - `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`. ## Request Notes ### Shipping Charge your customers for shipping without distorting the eligibility split. Shopify surfaces order-wide shipping as a single cart-level `ShippingLine` with no per-item allocation, so shipping is reported exclusively on the optional `cart_shipping` object — line `amount_details` entries do not accept a shipping display level: - `cart_shipping.amount_cents` — the cart/order-level shipping charge, in cents. - `cart_shipping.tax_cents` — tax on that shipping, in cents, when charged separately. Optional. When present, `cart_shipping` is added to the authorized total and rendered in the receipt's Shipping row; it does not move the cart's eligible or ineligible amounts. It is echoed back on the response `cart_info` as `shipping_amount_cents` and `shipping_tax_cents`.

Authentication

x-truemed-api-keystring

Platform API key for platform 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.

cart_shippingobject or nullOptional

Optional cart/order-level shipping (and its tax) that applies to the whole order rather than to a single line — the shape Shopify reports as a cart-level ShippingLine. When present it is added to the authorized total and shown in the receipt’s Shipping row. This is the only place shipping is reported; it cannot be carried on line amount_details.

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 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