API Overview

Base URL

All BillStack API endpoints follow this pattern:

https://your-billstack.com/api/billstack/teams/{teamId}/projects/{projectId}/...

Team-level endpoints (Stripe connection, API keys) omit the /projects/{projectId} segment:

https://your-billstack.com/api/billstack/teams/{teamId}/...

Authentication

BillStack supports two authentication methods:

API Key (for external SaaS apps)

Include your API key in the Authorization header:

curl https://your-billstack.com/api/billstack/teams/{teamId}/projects/{projectId}/customers \
  -H "Authorization: Bearer bs_a1b2c3d4..."

API keys are prefixed with bs_ and can be scoped to specific projects and permissions. See Create API Keys for details.

Session Cookie (for dashboard users)

Dashboard users authenticate via BetterAuth session cookies. This is handled automatically by the browser — no manual header is needed.

Team-level endpoints (Stripe connection, API key management) require session authentication only and cannot be accessed with API keys.

Request Format

• All request bodies must be JSON with Content-Type: application/json
• Query parameters use standard URL encoding
• IDs use BillStack prefixes (pc_, pp_, pri_, ps_) — not raw Stripe IDs

Response Format

All responses return JSON. Successful responses include the resource directly:

{
  "customer": {
    "id": "pc_xxx",
    "email": "jane@example.com",
    "name": "Jane Doe",
    "stripeCustomerId": "cus_xxx",
    "createdAt": "2026-03-30T12:00:00Z"
  }
}

List responses include an array:

{
  "customers": [
    { "id": "pc_xxx", "email": "jane@example.com" },
    { "id": "pc_yyy", "email": "john@example.com" }
  ]
}

Error Responses

Errors return an appropriate HTTP status code with a JSON body:

{
  "error": "Customer not found"
}

Pagination

List endpoints support pagination via query parameters:

curl ".../customers?limit=25&offset=50" \
  -H "Authorization: Bearer bs_..."

ID Prefixes

Each resource also stores its corresponding Stripe ID (e.g., stripeCustomerId, stripeProductId).

Endpoints