## 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}}
```