> For the complete documentation index, see [llms.txt](https://developers.spiffy.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.spiffy.co/api/changelog/rev-07.26.md).

# Rev 07.26

## TL;DR

`GET /v2/subscriptions` and `GET /v2/paymentplans` now support server-side filtering. Until now, filter params on these endpoints were accepted but ignored, so a full sync meant paging through every record and filtering on your side. You can now ask for exactly the slice you need, including "everything that changed since my last sync."

`GET /v2/orders` now has a `checkout_id` filter, so you can pull every order from a checkout in one query. See [§5](#id-5.-new-checkout_id-filter-on-get-v2-orders).

{% hint style="warning" %}
If you already send filter params to `GET /v2/subscriptions` (they used to no-op), those params now take effect and your result sets will shrink accordingly. Invalid filter values that were previously ignored now return `400`. See [§3](#id-3.-validation-changes).
{% endhint %}

***

## 1. New: filters on `GET /v2/subscriptions`

| Filter                    | Type     | Notes                                                                                                        |
| ------------------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| `id`                      | number   |                                                                                                              |
| `status`                  | enum     | `pending`, `trialing`, `active`, `past_due`, `canceling`, `canceled`, `unpaid`, `swapped`. Case-insensitive. |
| `order_id`                | number   |                                                                                                              |
| `customer_id`             | number   |                                                                                                              |
| `email`                   | text     | Customer email. Supports `.contains`.                                                                        |
| `product_id`              | number   | Filters by the subscription's product.                                                                       |
| `product_option_price_id` | number   |                                                                                                              |
| `created_at`              | datetime | Range operators supported.                                                                                   |
| `updated_at`              | datetime | Range operators supported.                                                                                   |
| `next_payment_at`         | datetime | Range operators supported.                                                                                   |

Both param styles work, with dotted operator suffixes (`.eq`, `.ne`, `.gt`, `.gte`, `.lt`, `.lte`, `.contains`, `.in`, `.nin`, `.null`):

```
GET /v2/subscriptions?status=active
GET /v2/subscriptions?filter[status.in]=active,past_due
GET /v2/subscriptions?filter[updated_at.gte]=2026-07-01T00:00:00Z
```

Datetime values must be ISO 8601 strings in UTC. Unix timestamps are rejected with a `400`.

### Incremental sync

The `updated_at` filter is the recommended way to keep an external copy of your subscription data current. Instead of re-downloading the full list on every run, record the time of your last successful sync and request only what changed since:

```
GET /v2/subscriptions?filter[updated_at.gte]=2026-07-02T09:00:00Z&sort=updated_at&per_page=100
```

On a typical day this is a handful of requests instead of hundreds, which matters if you're tracking a monthly API quota. We still recommend an occasional full resync (weekly is plenty) to pick up any records whose `updated_at` wasn't touched.

## 2. New: filters on `GET /v2/paymentplans`

Same mechanics as above, with this field set:

| Filter            | Type     | Notes                                                                       |
| ----------------- | -------- | --------------------------------------------------------------------------- |
| `id`              | number   |                                                                             |
| `status`          | enum     | `active`, `past_due`, `unpaid`, `completed`, `defaulted`. Case-insensitive. |
| `order_id`        | number   |                                                                             |
| `customer_id`     | number   |                                                                             |
| `email`           | text     | Customer email. Supports `.contains`.                                       |
| `created_at`      | datetime | Range operators supported.                                                  |
| `updated_at`      | datetime | Range operators supported.                                                  |
| `next_payment_at` | datetime | Range operators supported.                                                  |

## 3. Validation changes

Bad filter input on v2 list endpoints now fails fast with a `400` naming the field, the offending value, and (for enums) the valid values. Previously this class of input was either silently ignored or produced a generic `500`.

| Input                                         | Old behavior        | New behavior                   |
| --------------------------------------------- | ------------------- | ------------------------------ |
| Unknown enum value (`?status=bogus`)          | Ignored or `500`    | `400` with valid values        |
| Non-date on a datetime filter                 | `500`               | `400`                          |
| Unix timestamp on a datetime filter           | `500`               | `400` (use ISO 8601)           |
| Non-number on a number filter (`?order_id=x`) | `500`               | `400`                          |
| Uppercase enum value (`?status=Active`)       | Ignored or `500`    | Matches (lowercased)           |
| `?sort=` by an unknown or unsortable field    | `500` in some cases | Falls back to the default sort |

Unknown filter *params* (a field that isn't filterable at all) are still silently ignored, as documented.

## 4. MCP connector

The `list_subscriptions` and `list_paymentplans` tools on the Spiffy MCP connector now expose the same filters as `filter_*` parameters (date fields as `filter_<field>_gte` / `_lte` / `_gt` / `_lt` range variants), with valid enum values listed in each parameter's description.

## 5. New: `checkout_id` filter on `GET /v2/orders`

`GET /v2/orders` now accepts `checkout_id`:

```
GET /v2/orders?filter[checkout_id]=1234
```

That returns every order placed through the checkout, whatever version of it the customer saw. It's the ID you already work with: the one in the URL when you open the checkout in the builder, and the one on your checkouts list.

The endpoint already had `checkout_publish_id`, which is easy to mistake for this but isn't the same thing. Every time you edit and republish a checkout, Spiffy stores a new published version, and each order records the version it was bought through. So `checkout_publish_id` gets you orders from one version, not from the checkout as a whole. Pulling all of them meant finding every version ID first, and no endpoint lists those, so most people gave up and downloaded their whole order history to match up on their own side.

Both param styles work, along with the usual operator suffixes:

```
GET /v2/orders?checkout_id=1234
GET /v2/orders?filter[checkout_id.in]=1234,5678
GET /v2/orders?filter[checkout_id]=1234&filter[created_at.gte]=2026-07-01T00:00:00Z
```

`checkout_publish_id` is unchanged and still works, so nothing you've built will break. Use it when you specifically want a single version.

One limit: you can't `?sort=` by `checkout_id`. Sorting by it falls back to the default sort instead of erroring.

On the Spiffy MCP connector, the `list_orders` tool exposes this as `filter_checkout_id`.
