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

# Rev 09.26

## TL;DR

Payment plans that were fully paid but never marked complete are now closed by a nightly job. On the first runs after this rev you'll receive `payment_plan:success` events for plans that finished weeks or months ago, and those plans will have a `finished_at` later than their last payment.

Refund endpoints take a new optional `skip_integration_actions`. It stops your own automations running for that refund. The refund itself is unchanged, and your Event Webhook endpoints still receive it.

Affiliate program links now carry a merchant-set display order. `GET /v2/affiliates/programs/{program_id}/links` returns them in that order rather than newest-first, and there's a new endpoint to change it.

An affiliate's performance digest cadence is now writable on `PUT /v2/affiliates/{id}`, so a merchant can turn the email off for an affiliate instead of asking them to do it themselves.

Changing a subscription's next billing date no longer sets its status to `active`. The endpoint now refuses subscriptions that nothing can bill — canceled, swapped, unfinished, or on Stripe with no Stripe subscription behind them.

Requests that returned nothing to you no longer count against your monthly API quota: a `304 Not Modified`, a `429`, and any `5xx` are all free.

***

## 1. Paid-off payment plans are closed automatically

A payment plan was only marked `completed` by whichever request took its final payment. Some routes to a final payment didn't do that — a charge recovered through a customer's payment-recovery link, for instance — and the plan stayed `active` or `past_due` with nothing left to collect. Those plans never sent `payment_plan:success`.

A nightly job now finds plans whose collected total covers what's owed and closes them: `status` becomes `completed`, `next_payment_at` becomes `null`, and `payment_plan:success` is sent.

### Compatibility

The first runs work through a backlog of plans that settled before this rev, capped per run, so those deliveries arrive spread over several days. They look like any other `payment_plan:success` and the plan in the payload really is paid off. The money moved a while ago, though, so anything that reads the event as "a payment just landed" — sending a receipt, or counting it in the current period's revenue — will be wrong for these.

`finished_at` is your check. It's stamped when the plan is closed, not when the last payment succeeded, so for a plan closed by this job the gap is however long it sat open. Plans completed the ordinary way still have the two seconds apart.

Plans already marked complete are untouched, and no event is sent twice.

***

## 2. Refunds can skip your automations

`POST /v2/payments/{id}/refund` and `POST /v2/orders/{id}/refund` accept a new optional boolean, `skip_integration_actions`. Send `true` and the refund runs normally but your own automations for it don't.

This is for refunding a duplicate purchase. Access is held per product, not per order, so an automation that revokes access on `payment:refunded` takes away the access the customer paid for on the order you kept. No automation setting avoids that. The automation can't tell the two orders apart.

### What still happens

Everything except your own automations:

* the refund is recorded and appears in your activity history
* your registered Event Webhook endpoints still receive `payment.refunded`
* tax and CRM integrations still run, including the TaxJar refund transaction and your CRM's deal and contact sync

Two things people read the wrong way round, so they're worth stating plainly.

Your **Send Webhook automation action** — the one you configure under Automations, including Zapier and Make — is an automation, so it does *not* run. Only the Event Webhook endpoints you register as a developer still fire.

And if you revoke access from a listener on one of those endpoints rather than from a Spiffy automation, this flag won't stop it. Filter on your side.

### The choice sticks to the payment

We store your choice on the payment. For some gateways the refund isn't final until they tell us so in a later request, and by then your original request is long gone.

So the last choice you made through Spiffy is the one that applies. If you refund with `skip_integration_actions: true` and later refund the same payment from your payment provider's own dashboard, that second refund skips too, because nothing told us otherwise. Refunding again through Spiffy without the flag sets it back.

A refund started outside Spiffy can never set the flag, only inherit it.

### Reading it back

The value isn't on the payment object. Each refund writes a `refund_payment` entry to activity history with `skip_integration_actions` in its data, so that's where to look for what a given refund actually did.

***

## 3. Affiliate program links have a display order

Merchants can now arrange the tracking links in an affiliate program, and that order is what their affiliates see in the portal. Links used to come back newest-first with no way to change it, so merchants who wanted a particular link at the top were numbering the names by hand.

Every link now carries `sort_order`, an integer, ascending.

### `GET /v2/affiliates/programs/{program_id}/links`

Returns links ordered by `sort_order`, then by `created_at` descending as a tie-break. Pass `sort=-created_at` to get the old order back.

### `PUT /v2/affiliates/programs/{program_id}/links/order`

Takes `{"link_ids": [3, 1, 2]}` and answers `204`.

The links you send are rearranged among the display positions they already hold. They are not renumbered from 1. So a request can reorder the links it names relative to each other, but it cannot move one past a link it leaves out — send every id to rearrange a whole program.

### Compatibility

The order of that list endpoint changes with this rev. Existing links were given positions matching the order they were already being returned in, so nothing moves until a merchant rearranges something — but if you depend on newest-first, ask for it explicitly rather than relying on the default.

***

## 4. An affiliate's digest cadence is writable

Affiliates get a "Referral Performance" email on a cadence they choose in their portal. Until now that was the only place it could be changed, so a merchant who wanted it stopped had to ask the affiliate to stop it.

`PUT /v2/affiliates/{id}` takes a new optional `performance_digest_frequency_days`:

| Value | Cadence           |
| ----- | ----------------- |
| `0`   | never             |
| `1`   | daily             |
| `7`   | weekly (Mondays)  |
| `30`  | monthly (the 1st) |

Any other value is a `400`. The field was already on the affiliate object, so reading it is unchanged, and new affiliates still start at `7` — `POST /v2/affiliates` ignores this field rather than rejecting it, so set it with a follow-up `PUT`.

### It's a preference, not an override

There's one value per affiliate, and whoever writes last wins. Setting `0` doesn't lock the affiliate out of it. They can turn the email back on from their portal, and nothing anywhere records that you were the one who turned it off. So if it matters that the setting held, read it back.

### Filtering

`GET /v2/affiliates` accepts `performance_digest_frequency_days` as a filter. `?performance_digest_frequency_days.gt=0` gives you the affiliates who haven't switched the email off.

Treat that as an upper bound rather than the recipient list. The send also requires an active membership of an active program, so an affiliate sitting at `7` with no active program is in the filter and gets nothing.

The opposite takes two requests, because the field can be null as well as `0` and both mean no email: `?performance_digest_frequency_days=0` and `?performance_digest_frequency_days.null=true`.

***

## 5. Changing a subscription's billing date no longer reactivates it

`PUT /v2/subscriptions/{subscription_id}/nextbillingdate` used to set the subscription's status to `active` whatever it was before. That made it a way to bring a canceled subscription — or one that was never finished being set up — back onto the books, with a schedule nothing could actually bill against. Stripe only bills subscriptions it knows about, and Spiffy's own collector only bills PayPal, PayPal Advanced, Spiffy Payments and Whop.

### New refusals

The endpoint now answers `400` for:

* a subscription whose status is `canceled`, `swapped` or `pending` — resume it first if you want to start billing it again
* a subscription on the Stripe gateway with no Stripe subscription behind it, which nothing can charge

### Status handling

A `past_due` or `unpaid` subscription still becomes `active`. So does a `trialing` subscription on a gateway Spiffy bills itself, because that promotion is what makes the new date take effect.

Everything else keeps the status it had. `trialing` and `canceling` subscriptions on Stripe used to come back `active`; they now come back as they were, which is what Stripe reports for the same subscription.

### Compatibility

If you are moving billing dates in bulk, the calls that used to succeed on retired or unfinished subscriptions will now fail. Read `status` first and skip those, or expect and ignore the `400`.

***

## 6. Cached and rejected requests no longer count against your monthly quota

Your account's monthly API quota used to count every request that reached it, even ones that returned nothing to you. Three kinds of those no longer count a unit.

A conditional `GET` that comes back `304 Not Modified` is free. Store the `ETag` from a response, send it back as `If-None-Match` on your next request for the same resource, and if nothing changed you get a `304` and spend no quota. Polling an unchanged resource this way costs nothing — until you reach your monthly limit, past which every request, conditional or not, is rejected with `429`.

A request rejected with `429` is also free, whether you're over your monthly limit or your plan has no API access. Being over the limit can no longer push your usage further past it.

Server errors are free too: any `5xx` no longer counts, since a failure on our side isn't work you asked for. Client errors still count — a `4xx` other than `429` is a request we processed, so it draws a unit like any `2xx`.

On a refunded response (`304`, `429`, or `5xx`), the `X-Monthly-RateLimit-Remaining` header on that response still reflects the request before the refund; the next request shows the settled count.
