> This page is for version v1 (default).
> For other versions, use one of these documentation indexes:
> - v1 (default): https://developers.truemed.com/v-1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.truemed.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.truemed.com/_mcp/server.

# Itemized fees and discounts

> How to pass itemized fees, discounts, and taxes to create_payment_session so Truemed can show a full breakdown at checkout.

## Overview

We've updated the [`create_payment_session`](/api-reference/payment-sessions/create-payment-session) API to accept
additional details about any fees and discounts you're applying, at both the order-level and item-level. This allows
us to display the information provided on our payment page to provide a better breakdown of the total payment amount
to users.

All fields added are optional, and should only be provided if the partner is applying discounts or additional charges

* all existing requests will continue to function as usual.

This page gives a general overview of the changes required to your requests. Our checkout page will display an
itemized breakdown of each item and the cart if any itemized info is provided. Partners can also test that we are
storing the information on a payment by using the
[`payment_session_status`](/api-reference/payment-sessions/retrieve-payment-session) or
[`list_payment_sessions`](/api-reference/payment-sessions/list-payment-session) APIs. These have been updated to
return the `amount_details` objects provided on payment creation.

When providing amount details, they must satisfy the following equation:

![Total Amount Equation](/_fern-img/ea476170dff58047e1a2697a66fe431302a46ceb385b7bb9324803d72f93cf3e.webp)

## Example scenario: order-level charges

Let's walk through an example scenario:

1. The total payment amount is \$1000
2. There are 3 items being purchased:
   1. 1x "Item A" with a unit price of \$55
      * A \$45 additional charge named "Color Upgrade"
      * A \$10 discount named "Ten Dollars Off"
   2. 2x "Item B" with a unit price of \$150
   3. 4x "Item C" with a unit price of \$20
      * A \$5 discount named "Summer Sale"
3. There is a tax of \$50, a handling fee of \$100, and a shipping cost of \$275 applied to the order

To provide the 3 additional charges to us for display on our payment page, the request would include the fields below
(note that you will be providing additional fields in the request - this is a slimmed down version for clarity).

```json
{
    "total_amount": 100000,
    "order_items": [
        {
            "name": "Item A",
            "quantity": 3,
            "price": 5500,
            "sku": "Item A SKU",
            "amount_details": {
                "total_additional_charges": 4500,
                "additional_charges_details": [
                  {"name": "Color Upgrade", "amount": 4500}
                ],
                "total_discounts": 1000,
                "discounts_details": [
                  {"name": "Ten Dollars Off", "amount": 1000}
                ]
            }
        },
        {
            "name": "Item B",
            "quantity": 2,
            "price": 15000,
            "sku": "Item B SKU"
        },
        {
            "name": "Item C",
            "quantity": 4,
            "price": 2000,
            "sku": "Item C SKU",
            "amount_details": {
                "total_discounts": 500,
                "discounts_details": [
                  {"name": "Summer Sale", "amount": 500}
                ]
            }
        }
    ],
    "amount_details": {
        "total_additional_charges": 42500,
        "additional_charges_details": [
          {"name": "Tax", "amount": 5000},
          {"name": "Handling", "amount": 10000},
          {"name": "Shipping", "amount": 27500}
        ]
    }
}
```

In this example scenario, there are no discounts provided at the order level, so `total_discounts` and
`discounts_details` are omitted. There are also no item level fees or discounts for Item B, so `amount_details` is
omitted from that order item. With this information, we can display each additional charge on our payment page.

The important points to note are:

1. Each additional charge detail `amount` must be $\geq 0$
   * Partners are allowed to provide an additional charge with an amount of 0 to indicate that the charge is free
2. All additional charge amounts sum up to the `total_additional_charges` field
3. The sum of each item's subtotal (quantity × price + item-level charges - item-level discounts) + any order-level
   additional charges - any order-level discounts must equal the payment's `total_amount`

For the example scenario above:

$$
100000 = (3 \times 5500 + 4500 - 1000) + (2 \times 15000) + (4 \times 2000 - 500) + 42500 - 0
$$

> **Note**
>
> ### Invalid info provided
>
> If the `amount_details` objects provided are not valid in any way, you will receive an `InvalidRequestParameter`
> error with a message indicating the issue. If the `total_amount` does not equal the expected amount, you will receive
> a `TotalAmountInvalid` error.