Skip to main content
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.
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).
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. Get the payout as CSV

payoutReport returns the same payout as a flat CSV: one header row, one row per order line, and the payout columns (id, amount, value date, …) repeated on every row so each row reconciles on its own. It is built the same way as the file the store’s finance team receives by email when a payout is deposited, so with the same columns a reconciliation script can read either source and get the same file.
Without fields, the columns are the store’s saved selection from its payments settings (or the default set when nothing was saved). Pass fields to pick columns for this call only, for example fields: [PAYOUT_ID, VALUE_DATE, ORDER_REFERENCE, NET_IN_THIS_PAYOUT]; the saved selection is not changed (payoutReportSettingsUpdate changes it), and the file always lists columns in the catalog’s order. An empty fields list is HTTP 400. Amounts are decimal strings in the payout’s currency ("-25.00" for a refund-only line), dates are YYYY-MM-DD, timestamps are ISO 8601 UTC, and line_types joins values with | (capture|refund). Customer names and emails are never in the file. payoutReport is null for an unknown id; unlike payoutBreakdown it returns PAYMENTS_NOT_ENABLED when payments are not enabled for the store.

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

5. Export the ledger as CSV

paymentTransactionsExport returns the same file as the Export button on the Transactions page of the merchant app, so you don’t have to page through paymentTransactions and build it yourself. It is experimental, so add @experimental to the field.
This file holds shopper emails, in its customer_email column. That is the difference from payoutReport, whose file never has customer names or emails. Anyone with a payments_read key can read them, so handle the file as shopper data.
dateFrom and dateTo are optional, inclusive US Eastern calendar days, the same clock as paymentTransactions, and dateFrom after dateTo is HTTP 400. There is no search. The provider caps the file: when truncated is true, csv does not hold every transaction in the range, so narrow the dates and export again. The developer log records the request but never csv.

6. Email payout reports

The store can email the payoutReport file to its finance team each time a payout is deposited. payoutReportSettings reads that setup and payoutReportSettingsUpdate changes it. Both are experimental, need the payments_settings_write scope, and fail with PAYOUT_REPORT_EMAILS_NOT_AVAILABLE (403) on a store where payout report emails are not available yet.
  • Turn it on or off with enabled. Reports send only while it is on and at least one recipient is listed.
  • Set recipients with recipients, which replaces the whole list: at most 10 addresses, trimmed, lowercased and de-duplicated.
  • Choose columns with fields, which replaces the saved selection and can’t be empty. The file lists them in the catalog’s order, and defaultFields is the set used when none was saved.
Leave a field out to keep it. An invalid value fails with INVALID_PAYOUT_REPORT_SETTINGS (400). Saving fails with PAYMENTS_NOT_ENABLED (403) when payments are not enabled for the store, and with HSA_GALE_ORGANIZATION_NOT_LINKED (409) when the store is not linked to its payments organization yet.

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