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.refundedtax 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:
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,swappedorpending— resume it first if you want to start billing it againa 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.
Last updated