Reconciling payouts

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.

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

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.

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

Getting Started

Guides

Reference

Reconciling payouts

1. List payouts for a date range

2. Break a payout into order lines

3. Read the per-order ledger

Cursors

Errors

​1. List payouts for a date range

​2. Break a payout into order lines

​3. Read the per-order ledger

​Cursors

​Errors

1. List payouts for a date range

2. Break a payout into order lines

3. Read the per-order ledger

Cursors

Errors