> 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-06.26.md).

# Rev 06.26

## TL;DR

Some of our v2 API endpoints weren't operating as documented. Most public endpoints already follow the documented `{ data }` / `{ data, meta }` envelope, but a handful of older endpoints had drifted. \
\
We're realigning them, plus tightening a few places where the API was silently accepting bad inputs or returning more data than it should have.

{% hint style="warning" %}
If your integration only consumes the documented shapes (`response.data` for resources, `response.meta.pagination` for list metadata, 2xx for success, 4xx for client error), you're unaffected by most of this. Look at [**§1**](#id-1.-response-body-shape-changes) and [**§2**](#id-2.-list-get-endpoints-include-is-now-strictly-opt-in) carefully — those are the most likely sources of breakage.
{% endhint %}

***

## 1. Response body shape changes

### 1.1 — Endpoints now return the documented `{ data }` envelope

These endpoints previously returned a non-standard shape (`{ <named_key>: ... }` or a bare object/array). They now return `{ data: ... }` to match the rest of the v2 API.

| Endpoint                                                               | Old                                                     | New                                                               |
| ---------------------------------------------------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------- |
| `GET /v2/products/counts`                                              | `{ subscription_product_count, onetime_product_count }` | `{ data: { subscription_product_count, onetime_product_count } }` |
| `PUT /v2/products/:id`                                                 | `{ product: { ... } }`                                  | `{ data: { ... } }`                                               |
| `GET /v2/products/:id/actions`                                         | `{ product: { ... } }`                                  | `{ data: { ... } }`                                               |
| `PUT /v2/products/:id/actions`                                         | `{ event_actions: [ ... ] }`                            | `{ data: [ ... ] }`                                               |
| `GET /v2/products/:id/options/:option_id/actions`                      | `{ event_actions: [ ... ] }`                            | `{ data: [ ... ] }`                                               |
| `PUT /v2/products/:id/options/:option_id/actions`                      | `{ event_actions: [ ... ] }`                            | `{ data: [ ... ] }`                                               |
| `PUT /v2/affiliates/checkslugs`                                        | `{ slugs: { ... } }`                                    | `{ data: { ... } }`                                               |
| `PUT /v2/affiliates/:id/checkslugs`                                    | `{ slugs: { ... } }`                                    | `{ data: { ... } }`                                               |
| `PUT /v2/affiliates/programs/:program_id/links/checkslugs`             | `{ slugs: { ... } }`                                    | `{ data: { ... } }`                                               |
| `PUT /v2/affiliates/programs/:program_id/links/:link_id/checkslugs`    | `{ slugs: { ... } }`                                    | `{ data: { ... } }`                                               |
| `GET /v2/affiliates/programs/:program_id/checkouts/:checkout_id/items` | `{ items: [ ... ] }`                                    | `{ data: [ ... ] }`                                               |
| `GET /v2/orders/:order_id/affiliate/commissions`                       | `{ commissions: [ ... ] }`                              | `{ data: [ ... ] }`                                               |

**Migration:**

{% tabs %}
{% tab title="Before" %}

```javascript
const { product } = await api.put(`/v2/products/${id}`, payload);

const { event_actions } = await api.get(`/v2/products/${id}/actions`);

const counts = await api.get('/v2/products/counts');
console.log(counts.subscription_product_count);
```

{% endtab %}

{% tab title="After" %}

```javascript
const { data: product } = await api.put(`/v2/products/${id}`, payload);

const { data: event_actions } = await api.get(`/v2/products/${id}/actions`);

const { data: counts } = await api.get('/v2/products/counts');
console.log(counts.subscription_product_count);
```

{% endtab %}
{% endtabs %}

### 1.2 — `GET /v2/customers/:id/cards` now returns the standard list envelope

Previously returned a bare array. Now returns `{ data: [...], meta: { pagination: {...} } }` and **honors `?per_page=` and `?page=`**. Before, the endpoint silently ignored pagination params and returned every active card on the customer.

{% tabs %}
{% tab title="Before" %}

```javascript
const cards = await api.get(`/v2/customers/${id}/cards`);
cards.forEach(...);
```

{% endtab %}

{% tab title="After" %}

```javascript
const { data: cards, meta } = await api.get(`/v2/customers/${id}/cards?per_page=50`);
cards.forEach(...);
```

{% endtab %}
{% endtabs %}

### 1.3 — Empty-success responses now return `204 No Content` instead of `200 OK`

20 endpoints that previously returned `200 OK` with the literal body `"OK"` now return `204 No Content` with no body.

{% hint style="success" %}
**If your client treats any 2xx as success and doesn't try to parse the body, no change is needed.**
{% endhint %}

You only need to update if you:

* explicitly check `response.status === 200` (change to `response.ok` or `status >= 200 && status < 300`), or
* call `.json()` on the response (will throw on a 204 — instead, just check the status code and skip body parsing).

Affected routes (all empty-success, no semantic body change):

| Resource      | Routes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Products      | <p><code>DELETE /v2/products/:id</code><br><code>PUT /v2/products/:id/options</code> (sort)<br><code>DELETE /v2/products/:id/options/:option\_id</code><br><code>PUT /v2/products/:id/options/:option\_id/prices/:price\_id</code> (move)<br><code>DELETE /v2/products/:id/options/:option\_id/prices/:price\_id</code></p>                                                                                                                                                                                                                                                                                                                                                                                                |
| Promos        | `DELETE /v2/promos/:id`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Payments      | <p><code>POST /v2/payments/:id/retry</code><br><code>POST /v2/payments/:id/send-receipt</code></p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Payment plans | `POST /v2/paymentplans/:id/notes`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Subscriptions | `POST /v2/subscriptions/:id/notes`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Affiliates    | <p><code>DELETE /v2/affiliates/programs/:program\_id/affiliates/:affiliate\_id</code><br><code>PUT /v2/affiliates/programs/:program\_id/options/:option\_id</code><br><code>DELETE /v2/affiliates/programs/:program\_id/options/:option\_id</code><br><code>PUT /v2/affiliates/programs/:program\_id/prices/:price\_id</code><br><code>DELETE /v2/affiliates/programs/:program\_id/prices/:price\_id</code><br><code>PUT /v2/affiliates/programs/:program\_id/checkouts/:checkout\_id</code><br><code>DELETE /v2/affiliates/programs/:program\_id/checkouts/:checkout\_id</code><br><code>DELETE /v2/affiliates/programs/:program\_id/links/:link\_id</code><br><code>DELETE /v2/affiliates/payouts/:payout\_id</code></p> |

***

## 2. List/get endpoints: `?include=` is now strictly opt-in

### 2.1 — Eagerly-loaded relations no longer automatically included in responses

{% hint style="danger" %}
**This is the biggest breaking change in this release.** If your integration relied on the implicit nested data, you'll need to either request it explicitly or fetch it from its own endpoint.
{% endhint %}

`list_subscriptions`, `list_orders`, `list_paymentplans` (and their single-resource counterparts) used to return the full nested object graph in every response — `order`, `customer`, `gateway`, `price`, `option`, `product`, `card`, `card.sources`, etc. — regardless of `?include=`. Responses were 4–5 KB per row even for trivial list calls.

Now these endpoints return the bare resource by default. Related objects appear only when explicitly requested via `?include=`.

{% tabs %}
{% tab title="Before" %}

```javascript
// Old: order/customer/gateway baked in by default
const { data } = await api.get('/v2/subscriptions/?per_page=50');
data.forEach(sub => {
  console.log(sub.order.customer.email); // worked before; will be undefined now
});
```

{% endtab %}

{% tab title="After" %}

```javascript
// New: opt in to what you actually use
const { data } = await api.get('/v2/subscriptions/?per_page=50&include=order,customer');
data.forEach(sub => {
  console.log(sub.customer.email);
});
```

{% endtab %}
{% endtabs %}

The available expansions per endpoint are listed in the OpenAPI spec at `/v2/openapi.json` and on [developers.spiffy.co](https://developers.spiffy.co/). The most commonly-needed ones:

| Endpoint                 | Likely-needed includes                                           |
| ------------------------ | ---------------------------------------------------------------- |
| `GET /v2/subscriptions/` | `customer`, `order`, `payments`                                  |
| `GET /v2/orders/`        | `customer`, `items`, `payments`, `subscriptions`, `paymentplans` |
| `GET /v2/paymentplans/`  | `customer`, `order`, `payments`, `items`                         |

{% hint style="info" %}
A few computed fields (e.g. `payment_ids`, `current_payment_status`, `detail`, `payment_status`) **continue to be returned by default** because they're cheap and consumers depend on them. Only the raw related objects are gated on `?include=`.
{% endhint %}

### 2.2 — `?include=customer` no longer returns the merchant `account` record

Previously, asking for `?include=customer` on a subscription or paymentplan also returned the full merchant `account` record (\~70 fields) embedded inside the customer. The customer expander never actually used the `account` data — it was loaded for nothing and serialized into responses by accident.

{% hint style="warning" %}
If your code reads `subscription.customer.account.<anything>`, that path will be `undefined` after this change. The `account_id` on the customer is still there if you need to look up the account separately.
{% endhint %}

{% tabs %}
{% tab title="Before" %}

```javascript
console.log(subscription.customer.account.subdomain);
```

{% endtab %}

{% tab title="After" %}

```javascript
// The account_id is still on customer; fetch the account separately if you need its fields.
const accountId = subscription.customer.account_id;
```

{% endtab %}
{% endtabs %}

### 2.3 — Order's `checkout` is now an opt-in expansion

`GET /v2/orders/:id` and `GET /v2/orders/` previously returned a `checkout` object on every response (the order's published checkout snapshot). Now it requires `?include=checkout`.

{% tabs %}
{% tab title="Before" %}

```javascript
const order = await api.get(`/v2/orders/${id}`);
console.log(order.data.checkout.url_slug);
```

{% endtab %}

{% tab title="After" %}

```javascript
const order = await api.get(`/v2/orders/${id}?include=checkout`);
console.log(order.data.checkout.url_slug);
```

{% endtab %}
{% endtabs %}

***

## 3. Validation: bad input now returns 4xx instead of silent success or 5xx

These endpoints previously returned misleading 200s or 500s for clearly-invalid input. They now return clear 400s with field-named messages.

### 3.1 — Date filter values are validated

Passing a malformed date to a `*_at` filter now returns a 400 instead of a 500 caused by a Postgres parse error.

```http
GET /v2/customers?filter[created_at.gte]=not-a-date
```

```
Before: 500 internal_error
Now:    400 bad_request, "Invalid date format for filter \"created_at\": \"not-a-date\". Expected ISO 8601 (e.g. 2026-01-15T00:00:00Z)."
```

### 3.2 — `field_id` on customer/order PATCH is validated

`PATCH /v2/customers/:id` and `PATCH /v2/orders/:id` accept a `fields` array where each entry has a `field_id`. Previously, an unrecognized `field_id` (e.g. `"name_first"` instead of `"core_1"`) was silently dropped — the response was 200 but nothing changed. Now those calls return a 400 that names the offending id and points at the discovery path:

```json
{
  "error": {
    "code": "bad_request",
    "message": "Unknown field_id(s): name_first. Valid customer field_ids are core_N for built-in columns (e.g. core_1 for name_first) or account_N for custom fields. Call get_customer with include=fields to discover the actual field_ids."
  }
}
```

{% hint style="warning" %}
**If you have automation that was passing wrong field\_ids and not noticing,** it'll start failing. Use `GET /v2/customers/:id?include=fields` (or the equivalent for orders) to discover the correct ids.
{% endhint %}

***

## 4. Bug fixes

These don't break anything, but are behavior changes you may notice.

### 4.1 — `PUT /v2/products/:id/options/:option_id/prices/:price_id` now allows name-only updates

Previously rejected with `"Amount must be a valid number"` if `amount` wasn't included, even though price `amount` and `frequency` are immutable on update (changing them would silently re-bill existing subscriptions). The endpoint never actually wrote `amount` — the validation was a leftover gate. Now the call succeeds with just `name`:

```http
PUT /v2/products/:id/options/:option_id/prices/:price_id
```

```json
{ "name": "New Price Label" }
```

If you want to change the amount or frequency, create a new price (`POST /v2/products/:id/options/:option_id/prices`) and optionally soft-delete the old one.

### 4.2 — `?sort=` actually works on `GET /v2/products/`

Sort was silently ignored on the products list endpoint (the implementation dropped any user-supplied sort property and fell back to `created_at desc`). Now it correctly sorts on `id`, `name`, `stripe_product_id`, `is_taxable`, `is_commissionable`, `is_subscription`, `use_options`, `created_at`, and `updated_at`.

### 4.3 — `GET /v2/customers/:id/cards` honors pagination

See [§1.2](#id-1.2-get-v2-customers-id-cards-now-returns-the-standard-list-envelope) above. Previously returned every card; now respects `?per_page=` and `?page=`.

***

## 5. What didn't change

A few things you might expect to be in this release but aren't:

* **Webhook endpoint CRUD** (`/v2/webhook-endpoints/...`) is intentionally unchanged. Those endpoints serve a different consumer model (third-party webhook receivers) and any envelope change there will go through a separate coordinated deprecation cycle.
* **402 declined-card responses** in subscription/paymentplan billing flows still return raw payment-plan packages alongside the 402. Separate cleanup, not part of this release.
* **Existing documented field shapes** for first-class resources (orders, customers, subscriptions, etc.) are unchanged. We didn't remove any documented fields; we only changed the envelope and gated the un-requested expansions.

***

## How to validate

The easiest way to test against the new behavior before deploy:

1. Pull the latest OpenAPI spec from `/v2/openapi.json` — it reflects the new shapes.
2. Hit the changed endpoints in your dev environment and grep your client code for the patterns in [§1](#id-1.-response-body-shape-changes) (`{ product:`, `{ event_actions:`, `{ slugs:`, etc.) and [§2](#id-2.-list-get-endpoints-include-is-now-strictly-opt-in) (any access to nested `customer.`, `order.`, `gateway.`, etc. on list-endpoint responses).
3. The 200→204 change is invisible to most fetch wrappers — only an issue if you parse `.json()` on the response or check `=== 200`.
