Skip to content

Coach API docs: Connect billing reads list every field they return #62

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
DrAlexHarrison merged 1 commit into from
Oct 5, 2026
Merged

Coach API docs: Connect billing reads list every field they return #62

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 42 additions & 8 deletions guides/coach-api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -471,7 +471,7 @@ curl -H "Authorization: Bearer cp_live_..." \
"settlement_status": "settled"
}
],
"next_cursor": "1749480000000"
"next_cursor": "1749480000000|e_1"
}
```

Expand Down Expand Up @@ -531,11 +531,16 @@ curl -H "Authorization: Bearer cp_live_..." \
"lifetime_charges_cents": 240000,
"lifetime_fees_cents": 32400,
"lifetime_net_cents": 207600,
"platform_fee_bps": 1000
"platform_fee_bps": 1000,
"platform_fee_minimum_cents": 100,
"coach_pays_stripe_fees_from": 0,
"stripe_fee_domestic_bps": 290,
"stripe_fee_international_bps": 440,
"stripe_fee_fixed_cents": 30
}
```

Without a Connect account, `connect_account` is `null`, `is_onboarded` is `false` and every total is `0`.
Without a Connect account, `connect_account` is `null`, `is_onboarded` is `false` and every total is `0`. The fee terms come with every summary: Saturday's fee is `platform_fee_bps` of a charge and at least `platform_fee_minimum_cents`. From `coach_pays_stripe_fees_from` (Unix milliseconds; `0` while Saturday pays it) the coach pays Stripe's processing fee, at the rates on Saturday's account: `stripe_fee_domestic_bps` or `stripe_fee_international_bps` of the charge plus `stripe_fee_fixed_cents`.

### Connect earnings

Expand All @@ -548,7 +553,11 @@ Without a Connect account, `connect_account` is `null`, `is_onboarded` is `false
"total_gross_cents": 240000,
"total_stripe_fee_cents": 8400,
"total_platform_fee_cents": 24000,
"total_net_cents": 207600,
"total_refunded_cents": 2000,
"total_platform_fee_returned_cents": 200,
"total_disputes_cents": 1500,
"total_dispute_costs_recovered_cents": 0,
"total_net_cents": 204300,
"charge_count": 48,
"settled_count": 46,
"settling_count": 2,
Expand All @@ -559,7 +568,12 @@ Without a Connect account, `connect_account` is `null`, `is_onboarded` is `false
"charge_group_id": "ch_1",
"gross_amount_cents": 5000,
"stripe_fees_cents": 175,
"stripe_fee_paid_by": "coach",
"platform_fee_cents": 500,
"refunded_cents": 0,
"platform_fee_returned_cents": 0,
"disputes_cents": 0,
"dispute_costs_recovered_cents": 0,
"net_to_coach_cents": 4325,
"currency": "usd",
"settlement_status": "settled",
Expand All @@ -571,7 +585,7 @@ Without a Connect account, `connect_account` is `null`, `is_onboarded` is `false
}
```

`breakdowns` is an empty list when there are no charges.
`breakdowns` is an empty list when there are no charges. In each breakdown, `stripe_fees_cents` is the part of Stripe's processing fee the coach pays and `stripe_fee_paid_by` (`coach` or `saturday`, absent when no fee was recorded) says who paid it. `refunded_cents` went back to the athlete and `platform_fee_returned_cents` is Saturday's fee given back on those refunds. `disputes_cents` is what disputes and their fees took, less what was paid back; `dispute_costs_recovered_cents` is the part of it that repaid earlier disputes' costs. `net_to_coach_cents` is the gross less the Stripe fee the coach paid, Saturday's fee, refunds and disputes, plus the fee given back. The summary's `total_` fields add these up across the coach's charges.

### Connect transactions

Expand All @@ -592,14 +606,34 @@ Without a Connect account, `connect_account` is `null`, `is_onboarded` is `false
"currency": "usd",
"status": "succeeded",
"captured_at": 1749480000000,
"stripe_webhook_event_id": "evt_1"
"stripe_webhook_event_id": "evt_1",
"stripe_fee_paid_by": "coach"
},
{
"charge_id": "ch_2",
"arrangement_id": "arr_1",
"coach_uid": "coach_abc",
"athlete_uid": "ath_123",
"amount_cents": 10000,
"platform_fee_cents": 1000,
"stripe_fees_cents": 320,
"net_to_coach_cents": 6880,
"currency": "usd",
"status": "refunded",
"refund_amount_cents": 2000,
"captured_at": 1749390000000,
"stripe_webhook_event_id": "evt_2",
"stripe_fee_paid_by": "coach",
"platform_fee_returned_cents": 200
}
],
"total": 1,
"next_cursor": "1749480000000"
"total": 2,
"next_cursor": "1749390000000|ch_2"
}
```

A charge reads `refunded` once any part of it is refunded; `refund_amount_cents` says how much went back to the athlete, so the rest can still be refunded. `stripe_fees_cents` is the part of Stripe's processing fee the coach pays, and `stripe_fee_paid_by` (`coach` or `saturday`) says who paid it on a destination charge; it is absent on an older direct charge, where the coach paid it. `platform_fee_returned_cents` is Saturday's fee given back on refunds. `arrangement_id`, `refund_amount_cents`, `stripe_fee_paid_by` and `platform_fee_returned_cents` are left out while they are empty or zero.

### Connect arrangements

`GET /v1/coach/billing/connect/arrangements` returns every coach-to-athlete billing arrangement the coach has configured, in any status.
Expand Down
Loading