Subscriptions

Subscription endpoints are scoped to a project:

/api/billstack/teams/{teamId}/projects/{projectId}/subscriptions

Subscriptions are created via Checkout sessions, not directly through this API. These endpoints are for managing existing subscriptions.

List Subscriptions

GET /subscriptions?activeOnly=true&customerId=pc_xxx&limit=50&offset=0

Parameter	Type	Default	Description
`activeOnly`	`boolean`	`true`	Only return active/trialing subscriptions
`customerId`	`string`	—	Filter by BillStack customer ID
`limit`	`number`	`50`	Max items to return
`offset`	`number`	`0`	Items to skip

Example:

curl "https://your-billstack.com/.../subscriptions?customerId=pc_a1b2c3d4" \
  -H "Authorization: Bearer bs_..."

Response:

{
  "subscriptions": [
    {
      "id": "ps_m3n4o5p6",
      "customerId": "pc_a1b2c3d4",
      "stripeSubscriptionId": "sub_xxx",
      "status": "active",
      "priceId": "pri_i9j0k1l2",
      "quantity": 1,
      "cancelAtPeriodEnd": false,
      "currentPeriodStart": "2026-03-01T00:00:00Z",
      "currentPeriodEnd": "2026-04-01T00:00:00Z",
      "metadata": {},
      "projectId": "proj_abc123",
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-03-01T00:00:00Z"
    }
  ]
}

Auth: Read access (session or API key with subscriptions:read).

Get Subscription

GET /subscriptions/{subscriptionId}

curl "https://your-billstack.com/.../subscriptions/ps_m3n4o5p6" \
  -H "Authorization: Bearer bs_..."

Response:

{
  "subscription": {
    "id": "ps_m3n4o5p6",
    "customerId": "pc_a1b2c3d4",
    "stripeSubscriptionId": "sub_xxx",
    "status": "active",
    "priceId": "pri_i9j0k1l2",
    "quantity": 1,
    "cancelAtPeriodEnd": false,
    "currentPeriodStart": "2026-03-01T00:00:00Z",
    "currentPeriodEnd": "2026-04-01T00:00:00Z",
    "metadata": {},
    "projectId": "proj_abc123",
    "createdAt": "2026-01-01T00:00:00Z"
  }
}

Auth: Read access.

Cancel at Period End

PATCH /subscriptions/{subscriptionId}

Field	Type	Description
`cancelAtPeriodEnd`	`boolean`	`true` to cancel at end of billing period, `false` to resume

Cancel:

curl -X PATCH "https://your-billstack.com/.../subscriptions/ps_m3n4o5p6" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{ "cancelAtPeriodEnd": true }'

The subscription remains active until the current billing period ends, then transitions to canceled.

Resume:

curl -X PATCH "https://your-billstack.com/.../subscriptions/ps_m3n4o5p6" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{ "cancelAtPeriodEnd": false }'

Reactivates a subscription that was previously set to cancel at period end. Only works if the subscription hasn't actually canceled yet.

Auth: Write access (session or API key with subscriptions:write).

Cancel Immediately

DELETE /subscriptions/{subscriptionId}

curl -X DELETE "https://your-billstack.com/.../subscriptions/ps_m3n4o5p6" \
  -H "Authorization: Bearer bs_..."

Response:

{
  "subscription": {
    "id": "ps_m3n4o5p6",
    "status": "canceled",
    "cancelAtPeriodEnd": false
  }
}

Cancels the subscription in Stripe immediately. The customer loses access right away. This cannot be undone — you would need to create a new subscription via checkout.

Auth: Write access.

Subscription Statuses

Status	Description
`active`	Subscription is current and paid
`trialing`	In a free trial period
`past_due`	Payment failed, retrying
`canceled`	Subscription ended
`unpaid`	All retry attempts exhausted
`incomplete`	First payment hasn't been confirmed
`incomplete_expired`	First payment window expired
`paused`	Subscription paused (if enabled in Stripe)

Subscription status changes are tracked automatically via webhooks — you don't need to poll for updates.

Subscriptions

List Subscriptions

Get Subscription

Cancel at Period End

Cancel Immediately

Subscription Statuses

On this page