Create Shop Pay Truemed Session Refund

Record a refund you already issued on your own payment rail. `refund_amount_cents` is the sole authoritative refunded amount — it alone moves the reconciliation numbers. `refund_line_items` is optional and is used only to classify how much of the refund is HSA/FSA-eligible: each line names which item came back and how many units, so Truemed knows which portion of the refunded money was eligible. It is never a money allocation and is never reconciled against `refund_amount_cents`. Omit it for amount-only refunds and Truemed falls back to deriving the eligible/ineligible split from the session's captured composition. A refund cannot exceed the session's captured amount net of prior refunds. The call is idempotent on `idempotency_key`. The replay identity includes `refund_line_items` when present: replaying the same refund with an identical amount and identical lines returns the result recorded the first time, while a replay whose amount OR lines differ is rejected with a `400` rather than merged. Line order does not matter.

Authentication

x-truemed-api-keystring

Platform API key for platform server-to-server authentication

Path parameters

truemed_session_idstringRequired
The Truemed session ID from the URL path.

Request

Request body for CreateTruemedSessionRefundRequest
idempotency_keystringRequired1-200 characters
A unique key making this request safely retryable.
refund_amount_centsintegerRequired<=100000000

The amount refunded, in cents — the authoritative money fact for this refund. refund_line_items, when present, are used only to classify the eligible split (which items and how many units came back); they are never reconciled against this amount.

refund_line_itemslist of objects or nullOptional

Optional. When provided, these lines classify the refund’s eligible portion only — which items came back and how many units — and are never a money allocation. Omit them for amount-only refunds. refund_amount_cents remains the sole authoritative money fact.

Response

Successful response
idempotency_keystring

The idempotency_key submitted with this refund request, echoed back verbatim.

refund_idstring

Truemed’s stable ID for this refund (mrt_refund_<id>).

refunded_amount_centsinteger
Cumulative refunded amount on this session, in cents, including this refund.
truemed_session_idstring
The session the refund was recorded against.

Errors

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