List customer subscriptions

GEThttps://<your-url>/api/v2/customer-subscriptions

MCP id customer-subscriptions.indexAlso on this path: POST Create a customer subscription

Returns the organisation's customer subscriptions, newest start date first.

Token scope: api:read:customer_subscriptions
Without it: 403 insufficient-token-scope.
Permission: customer_subscriptions::read
Without it: 403 insufficient-permission.
Feature: Needs the billing feature on your organisation.
Without it: 404 endpoint-not-found.
Rate cost: 1 unit, read bucket. view=detail makes it 3. Adds: each include +1, q +2.
Also: If-None-Match answers 304 when nothing changed. Never cached: private, no-store. Unknown query parameters are refused, never ignored.

Both are checked, scope first. A token never does more than its user. How access is checked

Request

Example: Active subscriptions due to be invoiced this year

curl -G \
  'https://<your-url>/api/v2/customer-subscriptions' \
  --data-urlencode 'filter[status]=active' \
  --data-urlencode 'filter[auto_renew]=true' \
  --data-urlencode 'filter[next_invoice_date][lte]=2026-12-31' \
  --data-urlencode 'sort=-starts_at' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json'

const response = await fetch('https://<your-url>/api/v2/customer-subscriptions?filter[status]=active&filter[auto_renew]=true&filter[next_invoice_date][lte]=2026-12-31&sort=-starts_at', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <token>',
    'Accept': 'application/json',
  },
});

use Illuminate\Support\Facades\Http;

$response = Http::withToken('<token>')
    ->acceptJson()
    ->get('https://<your-url>/api/v2/customer-subscriptions?filter[status]=active&filter[auto_renew]=true&filter[next_invoice_date][lte]=2026-12-31&sort=-starts_at');

import requests
response = requests.request(
    'GET',
    'https://<your-url>/api/v2/customer-subscriptions?filter[status]=active&filter[auto_renew]=true&filter[next_invoice_date][lte]=2026-12-31&sort=-starts_at',
    headers={'Authorization': 'Bearer <token>', 'Accept': 'application/json'},
)

Response

The shape of the response, with sample values.

{
  "data": [
    {
      "id": 1,
      "customer_id": 1,
      "customer": {
        "id": 1
      },
      "subscription_type_id": 1,
      "subscription_type": {
        "id": 1
      },
      "description": "Managed hosting and maintenance.",
      "status": "pending",
      "billing_interval": "yearly",
      "starts_at": "2026-07-01",
      "next_invoice_date": "2026-03-04",
      "cancelled_at": "2026-03-04",
      "expires_at": "2026-03-04"
    }
  ],
  "meta": {
    "page": {
      "per_page": 1,
      "next_cursor": "…",
      "prev_cursor": "…",
      "total": 1,
      "current_page": 1,
      "last_page": 1
    }
  },
  "links": {
    "self": "https://<your-url>/api/v2/work-items/1",
    "next": "https://<your-url>/api/v2/work-items/1",
    "prev": "https://<your-url>/api/v2/work-items/1"
  }
}

8 more fields, listed under Response

Defaults to the summary view; view=detail carries the same fields on this resource (no field of it is detail-only) and costs three read units instead of one. filter[status]=active with filter[auto_renew]=true and filter[next_invoice_date][lte]=<today> is the due-for-invoicing query the renewal run uses. Search with q= over the subscription description, and pass trashed=with|only to see deleted subscriptions. There is no relationship sort: use sort=customer_id or filter[customer_id] rather than customer.name.

Query parameters

Unknown parameters are refused with 400, naming the parameter.

46 parameters in 7 groups

Views

viewstring

Which field set to render.

summarydefaultdetail

Pagination

per_pageinteger1 to 100

Rows per page. At most 25 when include names a to-many relation; a larger value is 400 invalid-query-parameter.

Default: 25

cursorstring

Opaque keyset cursor from a previous page's links.next. Never construct one by hand.

pageinteger1 to 1000

Opt in to page-number paging: 1-based, at most 1000. Omit it, the default, to page by opaque cursor, which is what links.next hands you. Cannot be combined with cursor. Published only on collections that count their rows on every request.

Filters

=: equals
[in]: any of a comma-separated list
[null]: true or false: whether it is empty
[gte][lte][lt]: at least, at most, less than
[ne]: not equal

filter[auto_renew]boolean

Whether the renewal run may invoice the subscription again.

filter[billing_interval]string=[ne][in]

Interval the subscription is invoiced at.

A comma-separated list of at most 100 values.

yearlymonthlyone-time

New values may be added.

filter[cancelled_at]date (YYYY-MM-DD)=[gte][lte][null]

Day the subscription was cancelled. null selects the ones that were not.

Whether the field is null.

filter[created_at]timestamp (YYYY-MM-DDThh:mm:ssZ)=[gte][lt]

Creation timestamp. Pair with sort=id for a stable full export.

filter[customer_id]integer=[in]

Customer the subscription belongs to. This is how you list one customer's subscriptions: there is no nested path for them.

A comma-separated list of at most 100 values.

filter[expires_at]date (YYYY-MM-DD)=[gte][lte][null]

Day the subscription runs out. null selects the open-ended ones.

Whether the field is null.

filter[last_invoiced_at]date (YYYY-MM-DD)=[gte][lte][null]

Day the subscription was last invoiced. null selects the ones that never were.

Whether the field is null.

filter[next_invoice_date]date (YYYY-MM-DD)=[gte][lte][null]

First day of the period to be invoiced next. null selects the subscriptions the renewal run skips. Combined with filter[status]=active and filter[auto_renew]=true this is the due-for-invoicing query the renewal run itself uses, and it is the single most useful query on this resource.

Whether the field is null.

filter[starts_at]date (YYYY-MM-DD)=[gte][lte]

First day the subscription runs from. Combine gte and lte to select a period, e.g. the subscriptions that started in one month.

filter[status]string=[ne][in]

Lifecycle status. Only active subscriptions are invoiced by the renewal run.

A comma-separated list of at most 100 values.

pendingactivecancelledexpired

New values may be added.

Search

qstring

Free-text search over description. At most one substring match per request: q together with a contains filter is 400 invalid-query-parameter.

Sorting

sortstring

Up to three keys, comma-separated, each optionally prefixed with - for descending.

Default: starts_at

Key	Sorts by
`starts_at`	First day the subscription runs from, newest first.
`next_invoice_date`	First day of the period to be invoiced next, earliest first.
`cancelled_at`	Cancellation date, earliest first.
`expires_at`	Expiry date, earliest first.
`last_invoiced_at`	Date the subscription was last invoiced, earliest first.
`id`	Id, ascending. An id never changes, so use this for a stable full export.
`updated_at`	Last-write timestamp; pair with the id tiebreaker for sync.

Prefix a key with - for descending.

Includes

includestring

Comma-separated names to inline, at most five.

Path	Adds	Cost
`customer`	The customer this subscription belongs to, with their name and code. Requires the `customers::read` permission and a token scope covering the customers prefix.	+1
`subscription_type`	The subscription type this subscription is an instance of, with its name, which is the name plnnrly shows for the subscription. Requires the `subscription_types::read` permission and a token scope covering the `subscription_types` prefix.	+1

Other

trashedstring

Whether soft-deleted rows are included.

withoutdefaultwithonly

Request headers

X-Request-Idstringpattern

A correlation id of your own. It is recorded in our logs next to the server's request id but never returned: the response header always carries the server's id. A value that does not match the pattern is discarded silently, never rejected.

If-None-Matchstring

The ETag a read is conditional on. A match is answered 304 with no body.

Response 200

Returns a page of CustomerSubscriptionList rows.

dataarray of CustomerSubscriptionList

The rows, each a CustomerSubscriptionList.

meta.pagePage

per_page, next_cursor, prev_cursor, total, current_page, last_page.

linksPageLinks

self, next, prev.

Each row is a CustomerSubscriptionList: 20 fields.

Headers

ETag: A weak validator (W/"…") of the rendered page.
RateLimit: The IETF httpapi-ratelimit-headers form of your remaining allowance on the tightest bucket this request touched.
RateLimit-Policy: The ceiling and window of that bucket, as <limit>;w=<seconds>.
X-Request-Id: The server-generated ULID correlating this response with our logs.

Every response also carries Cache-Control, Vary, X-Content-Type-Options, X-Plnnrly-Api-Version, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Headers and versioning

idinteger

Unique identifier.

customer_idinteger

Customer this subscription belongs to.

customerRef or CustomerSummary

The customer this subscription belongs to. Expanding it with ?include=customer additionally requires the customers::read permission and a token scope covering the customers prefix.

subscription_type_idinteger

Subscription type this subscription is an instance of.

subscription_typeRef or SubscriptionTypeSummary

The subscription type this subscription is an instance of, which is also where its displayed name comes from. Expanding it with ?include=subscription_type additionally requires the subscription_types::read permission and a token scope covering the subscription_types prefix.

descriptionstring or nullMultiline

What this subscription covers, as free text. This is the field ?q= searches, and it is also what a generated invoice line falls back to.

statusstring

Lifecycle status. Only an active subscription is picked up by the renewal run; the other three are inert.

pendingactivecancelledexpired

New values may be added.

billing_intervalstring

How often the subscription is invoiced. one-time forces auto_renew to false, because a one-off has no next period to move on to.

yearlymonthlyone-time

New values may be added.

starts_atdate (YYYY-MM-DD)

First day the subscription runs from, as a zone-free calendar date. Newest first is the default sort.

next_invoice_datedate (YYYY-MM-DD) or null

First day of the period to be invoiced next. Omit it on create and the server fills it with starts_at, so the first period is billable; the renewal run advances it by one interval each time it invoices. Null makes the subscription invisible to that run (it is skipped, silently), so a subscription that should never auto-invoice is expressed this way.

cancelled_atdate (YYYY-MM-DD) or null

Day the subscription was cancelled, null while it has not been. It is a record of the cancellation date only: nothing derives status from it.

expires_atdate (YYYY-MM-DD) or null

Day the subscription runs out, null when it is open-ended.

auto_renewboolean

Whether the renewal run may invoice this subscription again. A one-time subscription is always false: it is forced on every save, so sending true together with billing_interval=one-time succeeds and comes back as false rather than failing.

exact_subscription_idstring or null≤ 255Server-assigned

Exact Online subscription this one maps to, by Exact's own external identifier, not by a local id. Written by the sync; null when the subscription has never been synced.