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

# Payouts & Balance Transactions API

> Track, filter, and reconcile money movements from Flex to your Shopify store

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

```http theme={null}
GET /v1/payouts
Authorization: Bearer {{token}}
```

**Expected:** List all payouts across all timeranges.

```json theme={null}
{
  "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

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

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

```json theme={null}
{
  "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

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

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

```json theme={null}
{
  "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

```http theme={null}
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

```json theme={null}
{
  "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
    }
  ]
}
```

### 5. With limit parameter

```http theme={null}
GET /v1/payouts?limit=1
Authorization: Bearer {{token}}
```

**Expected:** Only 1 payout (newest first)

```json theme={null}
{
  "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
    }
  ]
}
```

### 6. Get specific payout by ID

```http theme={null}
GET /v1/payouts?payout_id=fpo_01k5g4xty062bqx5xr4xf7cxct
Authorization: Bearer {{token}}
```

**Expected:** Only that specific payout

```json theme={null}
{
  "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
    }
  ]
}
```

### 7. Precise timestamp filtering

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

**Expected:** Both payouts (≥ exact timestamp)

```json theme={null}
{
  "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
    }
  ]
}
```

## Balance Transactions

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

### Get all balance transactions

```http theme={null}
GET /v1/balance_transactions
Content-Type: application/json
Authorization: Bearer {{token}}
```

```json theme={null}
{
  "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

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

```json theme={null}
{
  "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

```http theme={null}
GET /v1/balance_transactions?balance_transaction_id=fbtxn_01k5g4xv968zg8t2jvhbdn9d5t
Authorization: Bearer {{token}}
```

```json theme={null}
{
  "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
    }
  ]
}
```

### With limit parameter

```http theme={null}
GET /v1/balance_transactions?limit=3
Authorization: Bearer {{token}}
```

```json theme={null}
{
  "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
    },
    {
      "balance_transaction_id": "fbtxn_01k5g4xv9ka7p51tt7b17zxh4f",
      "amount": 16463,
      "available_on": "2025-09-17T00:00:00Z",
      "created_at": "2025-09-15T07:19:55Z",
      "exchange_rate": null,
      "fee": 606,
      "net": 15857,
      "reporting_category": "charge",
      "checkout_session_id": "fcs_01k563wdp0qwrmtxz99rdpcj01",
      "client_reference_id": "rf7GjzjT0BrZU0lSpYLbDlDWP",
      "status": "available",
      "source_id": "fch_01k563x7jad8ef3hvrdjfxjrtt",
      "type": "payment",
      "test_mode": false
    }
  ]
}
```

### Pagination with ending\_before

```http theme={null}
GET /v1/balance_transactions?ending_before=fbtxn_01k5g4xva7x1dnmak291y1pvfr&limit=3
Content-Type: application/json
Authorization: Bearer {{token}}
```

```json theme={null}
{
  "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
    },
    {
      "balance_transaction_id": "fbtxn_01k5g4xv9ka7p51tt7b17zxh4f",
      "amount": 16463,
      "available_on": "2025-09-17T00:00:00Z",
      "created_at": "2025-09-15T07:19:55Z",
      "exchange_rate": null,
      "fee": 606,
      "net": 15857,
      "reporting_category": "charge",
      "checkout_session_id": "fcs_01k563wdp0qwrmtxz99rdpcj01",
      "client_reference_id": "rf7GjzjT0BrZU0lSpYLbDlDWP",
      "status": "available",
      "source_id": "fch_01k563x7jad8ef3hvrdjfxjrtt",
      "type": "payment",
      "test_mode": false
    }
  ]
}
```