API ReferenceTruemed Sessions

Create Shop Pay Truemed Session Refund

Record a refund you already issued on your own payment rail. `refund_amount_cents` is the authoritative refunded amount — it alone moves the reconciliation numbers. `refund_line_items` describes this refund's own return lines: the units returned and their economic value (post-discount subtotal and tax). The line values are facts about what came back, not an allocation of the money — a partial-money refund against returned lines worth more is legal, and the list may be empty or omitted for refunds with no returned units (shipping, adjustments, goodwill). Truemed updates the session history, the reconciliation reads, and the returned-units ledger to match. The call is idempotent on `idempotency_key`. Replaying the same refund with identical contents returns the result recorded the first time; a replay whose contents differ is rejected with a `400` rather than merged. Line order doesn't matter, so the same lines in a different order count as the same refund.

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. Independent of the line values: a partial-money refund against returned lines worth more is legal.

refund_line_itemslist of objectsOptionalDefaults to []

The lines returned in this refund — this refund’s own return lines only, never repeated from prior refunds and never order-level context. Omit or send empty for refunds with no returned units (shipping, adjustments, goodwill).

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