Payouts & Balance Transactions API - Flex Documentation

Overview

The Payouts API allows you to track, filter, and reconcile money movements from Flex to your Shopify store. Using these endpoints, you can fetch payout records, filter them by date ranges, and drill into the associated balance transactions.

Reconciliation

Flex provides all the data you need to reconcile payouts with your Shopify records.

How money flows:

1. Customers transact on your Shopify store.
2. Flex processes the payment.
3. An order is generated in your Shopify Admin with a corresponding payment.
4. The payment amount, minus Flex fees, is deposited into your Stripe account.
5. Within 24–72 hours, Stripe settles the funds into your linked bank account.

Payouts Endpoints

1. Get all payouts (no filters)

GET /v1/payouts
Authorization: Bearer {{token}}

Expected: List all payouts across all timeranges.

{
  "payouts": [
    {
      "payout_id": "fpo_01k5g4xty062bqx5xr4xf7cxct",
      "status": "paid",
      "amount": 5644,
      "arrival_date": "2025-09-11T00:00:00Z",
      "created_at": "2025-09-19T04:50:08.966956Z",
      "source_type": "card",
      "test_mode": false
    },
    {
      "payout_id": "fpo_01k5amhe3gcndv5ezv1mx0svct",
      "status": "paid",
      "amount": 49901,
      "arrival_date": "2025-09-17T00:00:00Z",
      "created_at": "2025-09-17T01:27:33.232593Z",
      "source_type": "card",
      "test_mode": false
    }
  ]
}

2. Filter by start_date only

GET /v1/payouts?start_date=2025-09-18T00:00:00Z
Authorization: Bearer {{token}}

Expected: Only the newer payout (created 2025-09-19)

{
  "payouts": [
    {
      "payout_id": "fpo_01k5g4xty062bqx5xr4xf7cxct",
      "status": "paid",
      "amount": 5644,
      "arrival_date": "2025-09-11T00:00:00Z",
      "created_at": "2025-09-19T04:50:08.966956Z",
      "source_type": "card",
      "test_mode": false
    }
  ]
}

3. Filter by end_date only

GET /v1/payouts?end_date=2025-09-18T00:00:00Z
Authorization: Bearer {{token}}

Expected: Only the older payout (created 2025-09-17)

{
  "payouts": [
    {
      "payout_id": "fpo_01k5amhe3gcndv5ezv1mx0svct",
      "status": "paid",
      "amount": 49901,
      "arrival_date": "2025-09-17T00:00:00Z",
      "created_at": "2025-09-17T01:27:33.232593Z",
      "source_type": "card",
      "test_mode": false
    }
  ]
}

4. Filter by date range

GET /v1/payouts?start_date=2025-09-17T00:00:00Z&end_date=2025-09-18T00:00:00Z
Authorization: Bearer {{token}}

Expected: Only the older payout

5. With limit parameter

GET /v1/payouts?limit=1
Authorization: Bearer {{token}}

Expected: Only 1 payout (newest first)

6. Get specific payout by ID

GET /v1/payouts?payout_id=fpo_01k5g4xty062bqx5xr4xf7cxct
Authorization: Bearer {{token}}

Expected: Only that specific payout

7. Precise timestamp filtering

GET /v1/payouts?start_date=2025-09-17T01:27:33.232593Z
Authorization: Bearer {{token}}

Expected: Both payouts (≥ exact timestamp)

Balance Transactions

Balance transactions provide detailed reconciliation data, including gross amounts, Flex fees, and net amounts.

Get all balance transactions

GET /v1/balance_transactions
Content-Type: application/json
Authorization: Bearer {{token}}

{
  "balance_transactions": [
    {
      "balance_transaction_id": "fbtxn_01k5g4xv968zg8t2jvhbdn9d5t",
      "amount": -49901,
      "available_on": "2025-09-17T00:00:00Z",
      "created_at": "2025-09-16T01:19:06Z",
      "exchange_rate": null,
      "fee": 0,
      "net": -49901,
      "reporting_category": "payout",
      "checkout_session_id": null,
      "client_reference_id": null,
      "status": "available",
      "source_id": "fpo_01k5amhe3gcndv5ezv1mx0svct",
      "type": "payout",
      "test_mode": false
    },
    {
      "balance_transaction_id": "fbtxn_01k5g4xv9dbaa01fnta41a3rt7",
      "amount": 18438,
      "available_on": "2025-09-17T00:00:00Z",
      "created_at": "2025-09-15T07:26:43Z",
      "exchange_rate": null,
      "fee": 675,
      "net": 17763,
      "reporting_category": "charge",
      "checkout_session_id": "fcs_01k5648ys1vpf3tzhervv9zzgn",
      "client_reference_id": "rFdxDcHpD9O3NCHgPXfZA7zTf",
      "status": "available",
      "source_id": "fch_01k5649q253tc5shjxw7r841pk",
      "type": "payment",
      "test_mode": false
    }
  ]
}

Get balance transactions for a specific payout

GET /v1/balance_transactions?payout_id=fpo_01k5amhe3gcndv5ezv1mx0svct
Content-Type: application/json
Authorization: Bearer {{token}}

{
  "balance_transactions": [
    {
      "balance_transaction_id": "fbtxn_01k5g4xv968zg8t2jvhbdn9d5t",
      "amount": -49901,
      "available_on": "2025-09-17T00:00:00Z",
      "created_at": "2025-09-16T01:19:06Z",
      "exchange_rate": null,
      "fee": 0,
      "net": -49901,
      "reporting_category": "payout",
      "checkout_session_id": null,
      "client_reference_id": null,
      "status": "available",
      "source_id": "fpo_01k5amhe3gcndv5ezv1mx0svct",
      "type": "payout",
      "test_mode": false
    }
  ]
}

Filter by specific balance_transaction_id

GET /v1/balance_transactions?balance_transaction_id=fbtxn_01k5g4xv968zg8t2jvhbdn9d5t
Authorization: Bearer {{token}}

With limit parameter

GET /v1/balance_transactions?limit=3
Authorization: Bearer {{token}}

Pagination with ending_before

GET /v1/balance_transactions?ending_before=fbtxn_01k5g4xv7x1dnmak291y1pvfr&limit=3
Content-Type: application/json
Authorization: Bearer {{token}}