From a79d91a417c68d7aeb93a2c37c7a81d445c1b496 Mon Sep 17 00:00:00 2001 From: Alex Harrison Date: Mon, 5 Oct 2026 08:33:00 -0600 Subject: [PATCH] Coach API docs: Connect billing reads list every field they return The transactions example gains a partly refunded charge, with refund_amount_cents, stripe_fee_paid_by and platform_fee_returned_cents explained. The earnings summary and breakdowns gain the refund, returned-fee and dispute fields, and the Connect summary its fee terms (minimum platform fee, when coaches start paying Stripe's fee, Stripe's rates). The ledger and transactions next_cursor examples take the timestamp|id form the API returns. Co-Authored-By: Claude Opus 5.5 (1M context) Ci-From: linux Ci-Session: 558b5692-58d2-410d-98ee-4771e5b99c97 --- guides/coach-api.mdx | 50 +++++++++++++++++++++++++++++++++++++------- 1 file changed, 42 insertions(+), 8 deletions(-) diff --git a/guides/coach-api.mdx b/guides/coach-api.mdx index 820379f..e73a319 100644 --- a/guides/coach-api.mdx +++ b/guides/coach-api.mdx @@ -471,7 +471,7 @@ curl -H "Authorization: Bearer cp_live_..." \ "settlement_status": "settled" } ], - "next_cursor": "1749480000000" + "next_cursor": "1749480000000|e_1" } ``` @@ -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 @@ -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, @@ -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", @@ -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 @@ -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.