shopify-admin-payout-reconciliation

Purpose

Reconciles Shopify Payments payouts to the order transactions that contributed to them. For each payout, sums gross sales, refunds, adjustments, and fees, and compares the computed net to the payout's reported net amount. Discrepancies are flagged with a delta and the suspected cause. Read-only — no mutations.

Prerequisites

• Authenticated Shopify CLI session: shopify store auth --store <domain> --scopes read_shopify_payments_payouts,read_orders
• API scopes: read_shopify_payments_payouts, read_orders
• Store must use Shopify Payments. If the store uses only third-party gateways, this skill exits cleanly with a message.

Parameters

Safety

ℹ️ Read-only skill — no mutations are executed. Reconciliation output is informational; do not treat flagged discrepancies as confirmed errors before reviewing the underlying transactions in the Shopify admin.

Workflow Steps

1. OPERATION: shopifyPaymentsAccount — query Inputs: select payouts(first: 100, query: "issued_at:>='<NOW - days_back days>'") with id, issuedAt, status, net, gross, summary { chargesGross, chargesFee, refundsGross, refundsFee, adjustmentsGross, adjustmentsFee, retriedPayoutsGross, retriedPayoutsFee } Expected output: All payouts in the window. If account is null, exit — store does not use Shopify Payments.

2. For each payout, compute reconciliation expectation:

   expected_net = chargesGross - chargesFee
                - refundsGross + refundsFee   (refundsFee is normally negative / reversed)
                + adjustmentsGross - adjustmentsFee
                + retriedPayoutsGross - retriedPayoutsFee
   

   delta = reported_net - expected_net