---
title: "List custom plan billings"
method: GET
path: "/custom-plan-billings"
tags: ["plans"]
---

# List custom plan billings

`GET /custom-plan-billings`

## Query parameters

- `company_id` string — Filter by company ID
- `plan_id` string — Filter by plan ID
- `plan_billing_source` 'custom_plan' | 'manage_plan'
- `status` 'active' | 'expired' | 'paid' | 'pending'
- `statuses` CustomPlanBillingStatus[] — Filter by multiple billing statuses
- `limit` integer — Page limit (default 100)
- `offset` integer — Page offset (default 0)

## Response `200`

OK

- object
  - `data` CustomPlanBillingResponseData[], required
    - `activation_strategy` 'on_payment' | 'on_publish', required
    - `billing_cycle_anchor` string, date-time, nullable — The billing period renewal date pinned when the subscription started, when one was set. When no invoice exists yet, the first invoice is raised on this date.
    - `company_id` string, required
    - `created_at` string, date-time, required
    - `days_until_due` integer, required
    - `external_invoice_id` string, nullable
    - `id` string, required
    - `paid_at` string, date-time, nullable
    - `plan_billing_source` 'custom_plan' | 'manage_plan', required
    - `plan_id` string, required
    - `prorate_first_period` boolean, nullable — Whether the shortened period the renewal date created was billed pro rata when the subscription started. False means that period is free and the first invoice is the one raised on the renewal date.
    - `published_at` string, date-time, nullable
    - `send_invoice` boolean, required
    - `status` 'active' | 'expired' | 'paid' | 'pending', required
    - `stripe_invoice_url` string, nullable
    - `updated_at` string, date-time, required
  - `params` object, required — Input parameters
    - `company_id` string — Filter by company ID
    - `limit` integer — Page limit (default 100)
    - `offset` integer — Page offset (default 0)
    - `plan_billing_source` 'custom_plan' | 'manage_plan'
    - `plan_id` string — Filter by plan ID
    - `status` 'active' | 'expired' | 'paid' | 'pending'
    - `statuses` CustomPlanBillingStatus[] — Filter by multiple billing statuses

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not found
- `500` — Server error

## Changes

> 125 revisions in range; 61 could not be searched.

- **2026-07-15** `3baa54bf8b3f` — 2 warning
  - for the `query` request parameter `limit`, the max was set to `250.00`
  - for the `query` request parameter `limit`, the min was set to `0.00`
- **2026-05-25** `110f1d3153f9` — 1 info
  - added the optional property `data/items/external_invoice_id` to the response with the `200` status

[Change history](https://skmtc.dev/schematichq/apis/schematic-api/changes/custom-plan-billings/get.md)

---

[API](https://skmtc.dev/schematichq/apis/schematic-api.md) · [All operations](https://skmtc.dev/schematichq/apis/schematic-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/schematichq/schematic-api/revisions/0b238e148fa1/schema)