> ## Documentation Index
> Fetch the complete documentation index at: https://developers.redo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reconciling payouts

> Match HSA/FSA deposits to the orders, fees, and refunds that make them up

HSA/FSA orders paid through Redo's HSA checkout settle in payouts. These queries
return the deposit date and amount, the fees taken, and the per-order charge and
refund amounts, so you can reconcile a payout to the orders in it.

The queries are **Beta**. They require the `payments_read` scope, and payments
must be enabled for the store. Shopify order numbers are not on these rows yet.
Match a row to an order with `merchantReference` or `orderReference`.

## 1. List payouts for a date range

`dateFrom` and `dateTo` are inclusive **payout (value) dates**: the banking date
of the deposit, not the day the order was placed.

```graphql theme={null}
query Payouts($dateFrom: Date!, $dateTo: Date!) {
  payouts(first: 50, dateFrom: $dateFrom, dateTo: $dateTo) {
    nodes {
      id
      type
      status
      amount { amount currency }
      date
      estimatedArrivalDate
    }
    pageInfo { hasNextPage endCursor }
  }
}
```

`amount` is a `Money` value: an exact decimal string plus an ISO 4217 currency,
for example `{ "amount": "118.40", "currency": "USD" }`.

## 2. Break a payout into order lines

Call `payoutBreakdown` with each payout `id`. `lines` is the whole payout (it is
not paginated). `amount` is that order's net contribution to this payout and is
**negative** when the line is only a refund. `orderGross`, `orderPlatformFee`,
`orderLmnFee`, and `orderTotalFees` are the whole order's figures, not this
payout's share, and the same amounts repeat on every line for that order (for
example a refund in a later payout).

```graphql theme={null}
query Breakdown($payoutId: ID!) {
  payoutBreakdown(payoutId: $payoutId) {
    transactionCount
    payout { id date amount { amount currency } }
    lines {
      orderReference
      merchantReference
      customerName
      types
      amount { amount currency }
      orderGross { amount currency }
      orderPlatformFee { amount currency }
      orderLmnFee { amount currency }
      orderTotalFees { amount currency }
    }
  }
}
```

`payoutBreakdown` is null when the id is unknown, or when payments are not
enabled for the store. An unknown id and a payout that belongs to another store
look the same.

## 3. Read the per-order ledger

`paymentTransactions` is one row per order: gross, platform fee, LMN fee,
total fees, amount refunded, net to the merchant, and the payout that settled
the capture (`payout`, null until that payout is known). `platformFee` is
Redo's platform commission and excludes the LMN fee. Card-processing costs are
not charged to the merchant. `totalFees` is the platform fee plus the LMN fee.

`dateFrom` and `dateTo` are inclusive **US Eastern calendar days**
(`America/New_York`), which is how the order date is filtered. That is a
different clock from the payout value date above.

```graphql theme={null}
query Transactions($dateFrom: Date!, $dateTo: Date!) {
  paymentTransactions(first: 50, dateFrom: $dateFrom, dateTo: $dateTo) {
    nodes {
      orderReference
      merchantReference
      orderedAt
      status
      gross { amount currency }
      totalFees { amount currency }
      refunded { amount currency }
      netToMerchant { amount currency }
      payout { id date }
    }
    pageInfo { hasNextPage endCursor }
  }
}
```

`search` matches order reference, checkout id, receipt number, merchant
reference, or customer name. Fewer than 2 characters is rejected with HTTP 400.
`dateFrom` after `dateTo` is also HTTP 400.

## Cursors

`payouts` and `paymentTransactions` use Relay cursor pagination. The cursors are
**positions** in the filtered list. If a new order or payout lands inside the
range while you are paging, a row can move onto another page. Re-read the range
from the start when that matters.

## Errors

| `extensions.code` | HTTP | Meaning |
| - | - | - |
| `PAYMENTS_NOT_ENABLED` | 403 | This store has no payments integration. `paymentTransactions` and `payouts` return this error. `payoutBreakdown` returns null instead. |
| `PAYMENTS_PROVIDER_UNAVAILABLE` | 502 | The payments provider failed. The message is `Payments provider request failed`. |
| `INSUFFICIENT_SCOPE` | 403 | The token is missing `payments_read`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.