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

# Rev 08.26

## TL;DR

Webhook events for subscriptions and cards now include the customer. Previously only order events carried buyer details, so handling `subscription:canceled` meant a follow-up API call before you knew whose subscription had ended.

The `cards` array on the `?include=customer` expansion now returns every saved payment method. PayPal cards used to collapse into one entry.

`GET /v2/payments` now supports `updated_at` range filters, so refunds and disputes show up in incremental syncs. And `search=` on `GET /v2/products` now actually searches.

Customers, products, promos, and affiliates now emit create/update/delete webhook events, so you can stop polling them.

Failed checkouts no longer emit webhook events at all. If you were using `subscription:unpaid` to catch declined sign-ups, move that to `payment:failed`.

***

## 1. `customer` on subscription and card events

If an event's object has a buyer behind it, that buyer is now on the payload at `data.object.customer`:

```json
{
  "id": "evt_9f3c1b8e-1a4d-4c2f-9b77-2e5a6d0c4f13",
  "object": "event",
  "type": "subscription:canceled",
  "api_version": "v2",
  "created": 1786806131,
  "account_id": 4471,
  "data": {
    "object": {
      "id": 4821,
      "order_id": 1503,
      "status": "canceled",
      "canceled_at": "2026-08-14T17:02:11.000Z",
      "customer": {
        "id": 902,
        "account_id": 4471,
        "email": "buyer@example.com",
        "name_first": "Alex",
        "name_last": "Rivera",
        "company_name": null,
        "tax_id": null,
        "gravatar": "https://gravatar.com/avatar/...",
        "created_at": "2025-11-02T09:14:00.000Z",
        "updated_at": "2026-08-14T17:02:11.000Z"
      }
    }
  }
}
```

(The subscription object is abbreviated above — it still carries every field it did before.)

This applies to every `subscription:*` event type, including the swap and trial events, and to every `card:*` event.

Order events (`order:*`, `payment:*`, `product:purchased`, `upsell:*`, `payment_plan:*`, `promo:applied`) already included `customer` and are unchanged. For `customer:*` and `affiliate:registered` events, the object already *is* the customer.

### What's in it

The fields listed above, and only those. Addresses and payment methods aren't included — fetch those from the customer or order endpoints if you need them.

One thing to watch if you're reusing parsing code: this is the base customer record, not the `?include=customer` expansion from `GET /v2/subscriptions/:id`. That expansion adds `custom_fields` and the customer's `cards`; the webhook payload has neither. It's the same shape across order, subscription, and card events, so you can parse it once.

On subscription and card events, a customer that no longer exists comes through as `customer: null` rather than a missing key, and the event still delivers.

### Compatibility

This is additive. `customer` is a new key on an object you already receive, so existing handlers keep working unchanged. If you're currently resolving the buyer with a second call to `GET /v2/orders/:id` or `GET /v2/customers/:id` after a subscription event, you can drop that call.

***

## 2. `cards` returns every saved payment method

The `?include=customer` expansion on `GET /v2/orders/:id`, `GET /v2/subscriptions/:id` and `GET /v2/paymentplans/:id` returns the customer's saved payment methods at `data.customer.cards`. That list was deduplicated by last four digits, which works fine for cards and quietly broke everything else.

PayPal and PayPal ACP wallet entries have no last four digits (the billing agreement lives on the underlying source, not the card), so they all shared a key of `null` and only the newest one survived. A customer who had paid with PayPal three times came back with a single entry. Real cards were affected too, wherever two of them shared their last four: different brands, or your Stripe and PayPal gateways, where the survivor could belong to a gateway you weren't asking about.

Entries are now keyed by gateway, brand and last four together, and an entry with no last four is never merged. Re-adding the same physical card on the same gateway still collapses to one entry, which is what the deduplication was there for.

### Compatibility

This one's additive too. Nothing that used to come back has disappeared and each entry has the same shape as before, there are just potentially more of them. Two things worth checking if you read this list:

* Code that assumed one entry per PayPal customer, or that used the array length as a card count, will now see the real number.
* The order changed. Entries used to come back sorted by last four ascending; they now follow the order the customer added them. Neither was ever documented, so sort explicitly if it matters to you.

***

## 3. `updated_at` filtering on `/v2/payments`

The payments list now accepts `updated_at` range filters — `updated_at.gte=` and `updated_at.lte=` — the same way orders, customers, and subscriptions already do. Payments was the one resource without it, and it mattered more there than anywhere else: a payment refunded or disputed months after it was created keeps its original `created_at`, so a sync filtering on `created_at` never sees the change. Those transitions do update the row, so `updated_at.gte=<last sync>` now catches them.

One shape note for sync code: a retried charge is a new payment row, not an update to the failed one. Retries arrive in your delta as new records either way, since a new row's `updated_at` starts at its `created_at`.

### Compatibility

Mostly additive, with one thing to check. An `updated_at` filter on payments used to be silently ignored — the request returned the full unfiltered list with a 200. If you have one sitting in production code, it starts working with this rev: the same request now returns only payments updated in that range. That's almost certainly what the code intended, but if anything downstream depends on the accidental full list, it will notice.

***

## 4. `search=` on `/v2/products`

`GET /v2/products?search=` now searches product names and descriptions, with the same contract as search on customers, checkouts, and affiliates. Before this rev the parameter was accepted and ignored, so the request came back 200 with every product.

### Compatibility

Same caveat as above: a previously dead `search=` on products starts filtering with this rev. If you were searching client-side after the fetch, your results don't change — you can just drop the local filter.

***

## 5. Webhook events for customers, products, promos, and affiliates

You can now receive webhook events when these records are created, changed, or removed, instead of polling for them:

* `customer:created`, `customer:updated`, `customer:deleted`
* `product:created`, `product:updated`, `product:deleted`
* `promo:created`, `promo:updated`, `promo:deleted`
* `affiliate:updated`

Each event's `data.object` is the same v2 object you get from that resource's `GET` endpoint. `product:deleted` and `promo:deleted` fire when the record is deactivated (a Spiffy delete is a soft delete), and the payload is the deactivated record with `is_active: false`, so you can act on the removal and still see what it was.

`customer:deleted` is the exception: the record is already gone by the time the event is sent, so its payload is just the ids — `{ "customer_id": <gone>, "merged_into_customer_id": <survivor> }`. Today it fires when two customers are merged; the survivor id tells you where to point anything that referenced the old record.

`updated` events only fire when a field actually changed. Re-saving a record without changing anything does not send one, so a customer buying again does not produce a stream of `customer:updated` events.

### Compatibility

If your endpoint subscribes to all events (`"*"`, the default), it starts receiving these automatically. If you match on event type in your handler, an unrecognized type should already be ignored — but check that a new `customer:*`, `product:*`, `promo:*`, or `affiliate:updated` event won't fall into a branch that assumes it's something else. Subscribe to specific event types if you want only some of them.

***

## 6. No webhook events for failed checkouts

When a checkout fails partway through, say a declined card on the payment step, Spiffy keeps the half-built order around for support to look at but marks it rolled back. It was never a sale.

Those orders were still firing events. A buyer whose card was declined on the very first charge could produce `subscription:unpaid`, then `subscription:expired` a day later when the gateway gave up, for a subscription that never started. If you tag delinquent customers off those events, you were tagging people who had never bought anything.

Rolled-back orders no longer emit webhook events.

Two event types are narrower as a result. `subscription:unpaid` now means what it sounds like: a running subscription has gone delinquent on a recurring charge. It no longer fires when the *first* charge fails at checkout, whether that's a decline or an abandoned 3D Secure challenge. Neither case ever produced a `subscription:started`, so the event had nothing to pair with. And `order:note:added` isn't sent for notes on a rolled-back order, though `customer:note:added` still is, since that one is about the person rather than the order.

### Compatibility

Check whether you key off `subscription:unpaid` to catch failed sign-ups. If you do, move that branch to `payment:failed`, which still fires for a declined first charge and carries the payment and its failure reason.

If you use `subscription:unpaid` for dunning an existing subscriber, nothing changes.

`order:note:added` shouldn't need changes. The affected orders are failed checkouts, which aren't orders you'd be reconciling against anyway.
