# Fund My Squad — Partner API Documentation

> Base URL: https://api.fundmysquad.com (for both staging and production keys)
> Docs: https://fundmysquad.com/partners/docs
> Partner Portal: https://fundmysquad.com/partners

## Implementation Overview

Fund My Squad (FMS) is a fundraising platform for youth sports. The Partner API lets external platforms (league management, team apps, registration software) offer built-in fundraising to their users. Partners earn commission on every donation processed through fundraisers created via their integration.

### Integration Flow

```
┌─────────────────────────────────────────────────────────────────┐
│                     PARTNER INTEGRATION FLOW                     │
└─────────────────────────────────────────────────────────────────┘

1. SETUP
   ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
   │  Apply at     │────▶│  Get staging  │────▶│  Build & test │
   │  /partners    │     │  API key      │     │  in sandbox   │
   └──────────────┘     └──────────────┘     └──────────────┘

2. CREATE FUNDRAISER (your platform → FMS API)
   ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
   │ User wants to │────▶│ POST /partner │────▶│ FMS returns   │
   │ fundraise     │     │ /v1/fundraisers│    │ id, publicUrl,│
   │ on your app   │     │ {title, goal, │     │ donateUrl     │
   └──────────────┘     │  externalId}  │     └──────────────┘
                         └──────────────┘

3. COLLECT DONATIONS (donors → FMS hosted page)
   ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
   │ Share the     │────▶│ Donor visits  │────▶│ FMS processes │
   │ donateUrl or  │     │ FMS donation  │     │ payment via   │
   │ embed link    │     │ page          │     │ Stripe        │
   └──────────────┘     └──────────────┘     └──────────────┘

4. ENABLE PAYOUTS (fundraiser creator → Stripe Connect)
   ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
   │ POST /partner │────▶│ Redirect user │────▶│ User completes│
   │ /v1/fundraisers│    │ to Stripe     │     │ KYC/banking   │
   │ /:id/connect/ │     │ onboarding    │     │ setup         │
   │ onboard       │     └──────────────┘     └──────────────┘
   └──────────────┘

5. TRACK & DISPLAY (FMS API → your platform)
   ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
   │ GET /partner  │────▶│ Show progress │────▶│ GET /partner  │
   │ /v1/fundraisers│    │ on your       │     │ /v1/fundraisers│
   │ /:id          │     │ platform      │     │ /:id/donations│
   └──────────────┘     └──────────────┘     └──────────────┘

6. COMMISSION PAYOUT (automatic)
   ┌──────────────────────────────────────────────────────────┐
   │ On each donation:                                         │
   │   Donor pays $100                                         │
   │   → Stripe fee: ~$3.20                                    │
   │   → Platform fee (10%): $10.00                            │
   │     → Partner commission (e.g. 4%): $4.00                 │
   │     → FMS keeps: $6.00                                    │
   │   → Fundraiser creator receives: $86.80                   │
   └──────────────────────────────────────────────────────────┘
```

### Quick Start Checklist

1. Apply at https://fundmysquad.com/partners
2. Once approved, log in to the Partner Portal
3. Generate a staging API key
4. Test all endpoints in the Sandbox
5. Request a production API key
6. Integrate into your platform
7. Go live

---

## Authentication

All API requests require your partner API key in the `x-partner-api-key` header:

```bash
curl https://api.fundmysquad.com/partner/v1/fundraisers \
  -H "x-partner-api-key: fms_partner_abc123..."
```

### Environments

| Environment | Base URL | Keys |
|-------------|----------|------|
| Staging/Sandbox | https://api.fundmysquad.com | Staging keys (auto-generated) |
| Production | https://api.fundmysquad.com | Production keys (admin-approved) |

IMPORTANT: Always use https://api.fundmysquad.com as the base URL. The API automatically detects whether your key is staging or production and routes accordingly. Staging key requests are transparently proxied to the sandbox environment — no test data ever enters the production database. Responses from the sandbox include the header `x-fms-environment: sandbox`.

---

## Endpoints

### Create a Fundraiser

```
POST /partner/v1/fundraisers
```

**Required fields:**
- `title` (string) — Fundraiser title
- `goalAmount` (number) — Goal in dollars (e.g. 5000)
- `externalId` (string) — Your platform's unique ID for the team/user

**Optional fields:**
- `description` (string) — Fundraiser description
- `goalType` (string) — "team" or "individual"
- `category` (string) — e.g. "sports"
- `sport` (string) — e.g. "baseball", "soccer", "basketball"
- `heroImageUrl` (string) — URL to hero image
- `startsAt` (string) — ISO 8601 datetime
- `endsAt` (string) — ISO 8601 datetime
- `metadata` (object) — Arbitrary JSON for your own tracking

**Example:**
```bash
curl -X POST https://api.fundmysquad.com/partner/v1/fundraisers \
  -H "x-partner-api-key: fms_partner_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Tigers Spring Travel Fund",
    "goalAmount": 5000,
    "goalType": "team",
    "externalId": "team_8472",
    "sport": "baseball",
    "endsAt": "2026-06-01T00:00:00Z"
  }'
```

**Response:**
```json
{
  "fundraiser": {
    "id": "uuid-here",
    "title": "Tigers Spring Travel Fund",
    "slug": "tigers-spring-travel-fund",
    "status": "active",
    "goalAmount": 5000,
    "publicUrl": "https://fundmysquad.com/f/tigers-spring-travel-fund",
    "donateUrl": "https://fundmysquad.com/f/tigers-spring-travel-fund/donate",
    "partnerExternalId": "team_8472",
    "metadata": {}
  }
}
```

### List Fundraisers

```
GET /partner/v1/fundraisers
```

**Query parameters:**
- `externalId` (string) — Filter by your team/user ID
- `status` (string) — Filter: `active`, `closed`, `draft`
- `sort` (string) — `newest`, `oldest`, `most_raised`, `ending_soon`
- `limit` (number) — Max results, up to 100
- `offset` (number) — Pagination offset

**Example:**
```bash
curl "https://api.fundmysquad.com/partner/v1/fundraisers?externalId=team_8472&status=active" \
  -H "x-partner-api-key: fms_partner_abc123..."
```

### Get Fundraiser Details

```
GET /partner/v1/fundraisers/:id
```

Returns full details including current stats (raised amount, donation count, supporter count, progress %) and the 10 most recent donations.

### Lookup by External ID

```
GET /partner/v1/fundraisers/by-external-id/:externalId
```

Returns all fundraisers matching the given external ID.

### Update a Fundraiser

```
PATCH /partner/v1/fundraisers/:id
```

**Updatable fields:** `title`, `description`, `goalAmount`, `startsAt`, `endsAt`, `category`, `sport`, `heroImageUrl`, `externalId`, `metadata`

Only include the fields you want to change. Omitted fields are left unchanged.

### Close a Fundraiser

```
POST /partner/v1/fundraisers/:id/close
```

Sets status to "closed". Closed fundraisers no longer accept donations.

### Reopen a Fundraiser

```
POST /partner/v1/fundraisers/:id/reopen
```

Optionally pass `{ "endsAt": "2026-08-01T00:00:00Z" }` to set a new end date.

### List Donations

```
GET /partner/v1/fundraisers/:id/donations?limit=50&offset=0
```

Returns paginated list of donations with amount, donor info (respecting anonymity), and timestamp.

### Get Fundraiser Stats

```
GET /partner/v1/fundraisers/:id/stats
```

Returns detailed statistics including totals, averages, and a 14-day daily donation trend.

### Get Partner Summary

```
GET /partner/v1/summary
```

Returns aggregate stats across all your fundraisers: total raised, active/closed counts, unique teams, total donors.

---

## Squads & Members

Squads (groups) let you organize team members within a fundraiser. Each member can have individual fundraising progress tracked.

### Create a Squad

```
POST /partner/v1/fundraisers/:id/squads
```

**Required fields:**
- `name` (string) — Squad name (e.g. "Varsity", "U12 Blue")

**Optional fields:**
- `level` (string) — Level designation (e.g. "A", "Gold")
- `metadata` (object) — Arbitrary JSON

### List Squads

```
GET /partner/v1/fundraisers/:id/squads
```

Returns all squads with member counts and total raised per squad.

### Update a Squad

```
PATCH /partner/v1/fundraisers/:id/squads/:squadId
```

**Updatable fields:** `name`, `level`, `metadata`

### Delete a Squad

```
DELETE /partner/v1/fundraisers/:id/squads/:squadId
```

Removes the squad and all its members.

### Add a Member to a Squad

```
POST /partner/v1/fundraisers/:id/squads/:squadId/members
```

**Required fields:**
- `displayName` (string) — Member's name

**Optional fields:**
- `isMinor` (boolean) — Whether the member is under 18
- `birthdate` (string) — ISO date

### List All Members in a Fundraiser

```
GET /partner/v1/fundraisers/:id/members
```

Returns all members across all squads, sorted by total raised. Each member includes `groupName`, `totalRaised`, and `donationCount`.

### Update a Member

```
PATCH /partner/v1/fundraisers/:id/squads/:squadId/members/:memberId
```

**Updatable fields:** `displayName`, `isMinor`, `birthdate`

### Remove a Member

```
DELETE /partner/v1/fundraisers/:id/squads/:squadId/members/:memberId
```

---

## Stripe Connect (Payouts)

### Onboard a Fundraiser Creator

```
POST /partner/v1/fundraisers/:id/connect/onboard
```

**Required fields:**
- `returnUrl` (string) — Where to redirect the user after Stripe onboarding

**Optional fields:**
- `refreshUrl` (string) — Where to redirect if the onboarding link expires

**Response:**
```json
{
  "onboardingUrl": "https://connect.stripe.com/...",
  "stripeAccountId": "acct_...",
  "message": "Redirect the fundraiser creator to onboardingUrl..."
}
```

Redirect your user to `onboardingUrl`. After completing Stripe's KYC/banking setup, they'll be redirected to your `returnUrl`.

### Check Connect Status

```
GET /partner/v1/fundraisers/:id/connect/status
```

Returns `connected` (boolean), `chargesEnabled`, `payoutsEnabled`, `detailsSubmitted`.

### Commission Splits

When a donation is made to a partner-created fundraiser with a connected payout account:
- **Fundraiser creator** receives the donation minus platform fee and Stripe fees
- **Partner** receives their commission (set by FMS admin) — comes out of the platform fee
- **FMS** receives the remaining platform fee

Example with 10% platform fee and 4% partner commission on a $100 donation:
- Stripe fee: ~$3.20
- Partner commission: $4.00
- FMS: $6.00
- Fundraiser creator: $86.80

---

## Key Concepts

### External IDs

The `externalId` field bridges your platform and FMS. Pass your unique identifier for teams or users. This lets you create multiple fundraisers for the same team over time and look them all up with a single API call.

### Partner Metadata

The `metadata` field on fundraisers is a free-form JSON object. Store league info, coach contacts, season details — FMS preserves it as-is and returns it in all responses.

### Scopes

| Scope | Grants |
|-------|--------|
| `fundraisers:read` | List and view fundraisers |
| `fundraisers:write` | Create, update, close, reopen |
| `donations:read` | View donations |
| `*` | All permissions |

### Sandbox vs Production

Staging API keys create **sandbox fundraisers** that are not publicly visible and don't process real donations. Use these for development and testing. Production API keys create real fundraisers that accept real donations.

---

## Errors & Rate Limits

### Error Format

```json
{ "error": "description of what went wrong" }
```

### HTTP Status Codes

| Status | Meaning |
|--------|---------|
| 200 | Success |
| 201 | Created |
| 400 | Bad request — missing or invalid fields |
| 401 | Authentication failed — bad or expired API key |
| 404 | Not found (or not owned by your partner account) |
| 409 | Conflict — e.g. closing an already-closed fundraiser |
| 429 | Rate limit exceeded |
| 500 | Server error |

### Rate Limits

- 120 requests per minute per API key
- 10,000 requests per day per API key

Rate limit headers are included on every response:

| Header | Description |
|--------|-------------|
| `X-RateLimit-Limit` | Requests allowed per minute |
| `X-RateLimit-Remaining` | Requests remaining in current window |
| `X-RateLimit-Reset` | Unix timestamp when the window resets |
| `Retry-After` | Seconds until you can retry (only on 429) |

---

## Complete Endpoint Reference

| Method | Endpoint | Scope | Description |
|--------|----------|-------|-------------|
| POST | /partner/v1/fundraisers | fundraisers:write | Create a fundraiser |
| GET | /partner/v1/fundraisers | fundraisers:read | List all fundraisers |
| GET | /partner/v1/fundraisers/:id | fundraisers:read | Get fundraiser details |
| GET | /partner/v1/fundraisers/by-external-id/:externalId | fundraisers:read | Lookup by external ID |
| PATCH | /partner/v1/fundraisers/:id | fundraisers:write | Update a fundraiser |
| POST | /partner/v1/fundraisers/:id/close | fundraisers:write | Close a fundraiser |
| POST | /partner/v1/fundraisers/:id/reopen | fundraisers:write | Reopen a fundraiser |
| GET | /partner/v1/fundraisers/:id/donations | donations:read | List donations |
| GET | /partner/v1/fundraisers/:id/stats | fundraisers:read | Get fundraiser stats |
| GET | /partner/v1/summary | fundraisers:read | Partner portfolio summary |
| POST | /partner/v1/fundraisers/:id/squads | fundraisers:write | Create a squad |
| GET | /partner/v1/fundraisers/:id/squads | fundraisers:read | List squads |
| PATCH | /partner/v1/fundraisers/:id/squads/:squadId | fundraisers:write | Update a squad |
| DELETE | /partner/v1/fundraisers/:id/squads/:squadId | fundraisers:write | Delete a squad |
| POST | /partner/v1/fundraisers/:id/squads/:squadId/members | fundraisers:write | Add member to squad |
| GET | /partner/v1/fundraisers/:id/members | fundraisers:read | List all members |
| PATCH | /partner/v1/fundraisers/:id/squads/:squadId/members/:memberId | fundraisers:write | Update a member |
| DELETE | /partner/v1/fundraisers/:id/squads/:squadId/members/:memberId | fundraisers:write | Remove a member |
| POST | /partner/v1/fundraisers/:id/connect/onboard | fundraisers:write | Start Stripe Connect onboarding |
| GET | /partner/v1/fundraisers/:id/connect/status | fundraisers:read | Check Stripe Connect status |

---

## Support

- Email: support@fundmysquad.com
- Partner Portal: https://fundmysquad.com/partners/dashboard
- Apply: https://fundmysquad.com/partners