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

# Rev 10.26

## TL;DR

Plan requirements now apply to the v2 API. Five features the dashboard has only ever offered on the Business plan were never checked on the API, so the same account could do through the API what its own dashboard refused. Those requests now answer `403` with the code `plan_upgrade_required`. If you set affiliate lead tracking, a custom affiliate slug, a per-item commission override, `use_options` on a product, or a billing frequency outside the standard list, check what plan the accounts you write to are on.

`PUT /v2/promos/:id` is now a partial update. It used to clear every field you left out, so a request sending only a new code wiped the discount, the expiry and the limits. Promo codes and discount amounts are also validated on the server now.

> **Unreleased. Release date TBD.** Promotions gain a mode (one shared code or a unique code per customer), a product scope and a troubleshooting endpoint. See section 5.

> **Unreleased. Release date TBD.** Four new webhook events follow promotions and their unique codes: `promo:started`, `promo:ended`, `promo:code_issued` and `promo:code_expired`. Endpoints subscribed to `*` start receiving them when this ships. See section 6.

> **Unreleased. Release date TBD.** `POST /v2/paymentplans/:id/pay` now answers `409` while another payment on the plan is still processing, and `400` (previously no response) when the plan has no valid payment method. See section 7.

***

## 1. Plan requirements are enforced on the API

A refused request looks like this:

```json
{
  "error": {
    "code": "plan_upgrade_required",
    "message": "Custom billing frequency requires the Business plan."
  }
}
```

The message names the feature and the plan it needs. Reading is never refused: you can still fetch records that use any of these features, and nothing already stored changes.

### Affiliate lead tracking, lead sharing and purchase sharing

`POST /v2/affiliates/programs` and `PUT /v2/affiliates/programs/:program_id` refuse `is_lead_tracking_enabled`, `is_lead_sharing_enabled` and `is_purchase_sharing_enabled` when any of the three is on. All three are required fields, so sending them as `false` keeps working on every plan.

On `PUT`, sending a flag back as `true` when the program already has it on is allowed. All three fields are required, so an update that reads a program and writes it back carries whatever is stored, and refusing that would block ordinary edits like renaming or archiving a program. What is refused is turning a flag on that the stored program does not already have on, and that is checked per flag: a program with lead tracking on cannot use it to turn purchase sharing on as well.

### Custom affiliate link slugs

A `slug` is refused on `POST /v2/affiliates`, `PUT /v2/affiliates/:id`, `POST /v2/affiliates/programs/:program_id/links` and `PUT /v2/affiliates/programs/:program_id/links/:link_id`. Leave it out and Spiffy assigns one.

On the two `PUT` endpoints, sending back the slug the record already has is allowed, so an update that reads an affiliate or a link and writes it back is not refused for a slug it did not change. Changing the slug to a different value still needs Business.

`POST /v2/affiliates` creates a batch, and every `affiliates[].slug` is checked, so one slug in a batch of fifty refuses the whole request. The `checkslugs` endpoints are read-only and still answer on every plan.

### Per-checkout affiliate commission overrides

Only the per-item values are refused. On `PUT /v2/affiliates/programs/:program_id/checkouts/:checkout_id`, a `commission_percent` or `duration_in_payments` on a `checkout_items[]` or `block_items[]` entry is refused when it differs from what that item already has stored. `null` clears an override and is allowed on any plan. `0` is a real override, meaning no commission on that item, so setting it needs Business, but sending back a `0` that is already stored does not.

That matters because this endpoint takes every item on the checkout at once. An update that reads the items and writes them back is not refused for values it did not change, so a single premium item cannot block a request that is really about something else.

An item whose stored record already carries a commission override is exempt outright, so overrides set up while the account had the feature stay editable. The checkout-level `commission_percent` and `commission_flat_amount` on the same request are not affected, and neither are the per-price and per-option override endpoints under `/v2/affiliates/programs/:program_id`.

### Advanced pricing on products

`use_options: true` is refused on `PUT /v2/products/:id`, and on `POST /v2/products` for a product that is not a subscription.

Updating options and option prices under `/v2/products/:id/options` is not restricted. A one-time product keeps its default price on an option, and a subscription uses options on every plan, so those endpoints are ordinary product editing rather than the premium feature.

Creating one is different. `POST /v2/products/:id/options` is refused when the product is not a subscription and does not already have `use_options` set, because adding a named option to a plain one-time product is the feature itself. It still answers on every plan for a subscription product, and for a product that already uses options.

### Custom billing frequency

The standard cadences are weekly, every 2 weeks, monthly, every 4 weeks, every 2 months, quarterly, every 4 months, every 6 months and yearly. Any other `(frequency, frequency_count)` pair is the dashboard's "Other" option, which needs Business.

It is refused wherever a cadence is written:

* `POST /v2/products` (on `options[].prices[]`), `POST /v2/products/:id/prices`, `POST /v2/products/:id/options` (on `prices[]`), and `POST /v2/products/:id/options/:option_id/prices`
* `POST /v2/reports` and `PATCH /v2/reports/:report_id`
* `PUT /v2/paymentplans/:id/terms`

`PUT /v2/products/:id/options/:option_id/prices/:price_id` is unaffected. A price's amount and frequency are immutable there; only the name and integration mappings can change.

Reports and payment-plan terms are exempt when the record's stored cadence is already custom, so you can still rename a report or change a plan's amount without its existing cadence being refused. Both endpoints write both frequency columns whenever either one is supplied, so a `PATCH` sending only `frequency_count` is checked against the merged pair rather than against the body alone.

### Compatibility

This is a breaking change and it is not behind a flag. A request your integration has been making successfully can start answering 403 on an account whose plan does not include the feature.

Worth checking:

* What plan the accounts you write to are on. Business and above are unaffected.
* Whether you send the three affiliate program flags as `true`, or a `slug`, or `use_options: true`, or a non-standard frequency.
* How your error handling treats a 403. `plan_upgrade_required` is not a credentials problem and a new token will not fix it; it needs a plan change or a different payload.

The MCP connector runs these same endpoints, so the equivalent tool calls refuse the same way, with the same code and message.

***

## 2. Updating a promo no longer clears the fields you leave out

`PUT /v2/promos/:id` rebuilt the whole promo from the request body. Any field you did not send was written back as empty, so a request carrying only a new code cleared both discount types, set both amounts to zero, reset the duration to forever and removed the expiry and both limits. It answered `200` and said nothing.

It is now a partial update. A field you leave out keeps its current value. To clear a field, send it as `null`.

```http
PUT /v2/promos/418
{ "code": "SPRING26" }
```

Before, that reset the promo to a code with no discount. Now it changes the code and nothing else.

Sending the full set of fields still works exactly as it did, so an integration that already posts the whole promo on every update needs no change. `code` is no longer required on an update, since leaving it out now means "keep the current code" rather than "clear it".

The same applies to the MCP `update_promo` tool, which runs this endpoint.

Only `expire_at` and the two discount types clear to empty. The numeric fields (`order_limit`, `per_customer_limit`, `subscription_duration_in_months` and the two discount amounts) treat `null` as `0`, which means unlimited or forever. The code cannot be cleared. An empty string behaves the same as `null`.

### Compatibility

If your integration sends partial updates to `/v2/promos/:id` today and relies on the fields it omits being cleared, those fields will now be kept. Send them as `null` to clear them.

***

## 3. Promo codes and discount amounts are validated

Rules the dashboard has always applied in the browser are now applied on the server too, so they reach API and MCP callers. Each answers `400`.

### Codes are letters and numbers only

`BAD CODE` used to save with the space in it. Checkout matches a code exactly, so a code with a space or punctuation is one your buyers may not be able to type or paste reliably. Codes are also trimmed before saving, where leading and trailing spaces used to be kept.

### Percent discounts cannot exceed 100

A 150% discount was accepted and then quietly capped at the item price during checkout, so it behaved as 100% off.

### Discounts cannot be negative

A negative amount was accepted and acted as a surcharge: checkout subtracts the discount from the price, so the buyer was charged more than the listed total.

### Limits and counts cannot be negative

That covers `order_limit`, `per_customer_limit` and `subscription_duration_in_months`. A value that is not a number is now refused rather than stored as zero. Decimal amounts are still truncated, as before.

### Values too large for the field are refused

A promo code is capped at 255 characters and the numeric fields at 2147483647, which are the column limits. Going over used to reach the database and come back as a `500`; it is now a `400` that says which field and what the limit is. An expiry that cannot be parsed as a date is refused the same way, where it also used to be a `500`.

### Promos you already have are not affected

A rule only applies to a value you are changing. A promo holding something out of range can still be edited; you just cannot set a new value that breaks a rule. A code that differs from the stored one only by spacing or letter case counts as unchanged, so promos created before these rules stay editable.

Spiffy does not rewrite existing promos in bulk. The one thing a save does change on its own: re-sending a code that has leading or trailing spaces stores the trimmed version.

### Compatibility

If you create promo codes programmatically, check they are letters and numbers only. Codes already in the system keep working.

***

## 4. Dates sent to subscription endpoints accept ISO 8601

Three endpoints read a date out of the request body in a way that only worked when it was written as `YYYY-MM-DD HH:mm:ss`. Sent as ISO 8601, which is the format the API and the MCP tools document and return, the date was not understood:

* `PUT /v2/subscriptions/:id/nextbillingdate`
* `POST /v2/subscriptions/:id/hardresume` (`subscription_start_at`)
* `PUT /v2/subscriptions/:id` (`subscription_start_at`)

It did not come back as an error. The unreadable date passed the "must be in the future" and "within two years" checks, because a comparison against a date that is not a date is never true, and the request went ahead on a value that meant nothing. On the billing-date endpoint that reached the payment processor.

Both formats now work on all three, and a date that genuinely cannot be read is refused with a `400` instead of being used.

If you send dates in `YYYY-MM-DD HH:mm:ss` today, nothing changes for you.

***

## 5. Promotions: modes, unique codes, product scope

> **Unreleased. Release date TBD.** This section is a draft and will be dated when the release is scheduled.

Everything in this section is additive. Existing requests and responses keep working.

A promotion now has a `mode` (how customers get it) and an `application` (what it discounts).

### `mode`

`shared` is the default and works as promos always have: one code that everyone types. `unique` issues a separate code to each customer. A unique promotion has no code of its own, so `promo.code` is `null`. Create codes with `POST /v2/promos/:id/codes`, passing either `customer_id` or `email`. An email that matches no customer creates a minimal customer record on the account. You cannot change `mode` after the promotion is created. Trying to returns `PROMO_MODE_IMMUTABLE`.

### `application`

`checkouts` is the default. The promotion discounts the checkout items it is attached to in the checkout editor, as before. `products` discounts any checkout line whose product, option or price is in `scope_targets`. An empty `scope_targets` means every product.

A `products` promotion cannot be attached to checkout items. If a promotion is already attached and you switch it to `products`, the request answers `409` with `PROMO_HAS_ATTACHMENTS` and lists the checkouts in `details.attachments`. Send `detach: true` to detach them and continue.

### Defaults for existing requests

A `POST /v2/promos` that sends only a `code` still validates. It creates a `shared` promotion with `application` set to `checkouts`, and `name` defaults to the code.

### New fields on promotion reads

* `name`, `mode`, `application`, `starts_at` and `scope_targets`
* `summary`, a plain-language description of the discount
* `issued_count`, `redeemed_count` and `redeemed_revenue`. `redeemed_revenue` adds order totals across currencies without converting them.
* `customer_count`, the number of distinct customers with an order under the promotion
* `attachments`, the checkout items the promotion is attached to
* `status`, one of `scheduled`, `active`, `expired` or `inactive`, worked out the same way as the Status column in the dashboard's promotion list

The OpenAPI reference now lists the fields these endpoints actually return.

`GET /v2/promos/:id` and `GET /v2/promos/:id/actions` now also return a deleted promotion, with `status` set to `inactive`. Updating or deleting a deleted promotion still answers `404`.

### Issued codes

* `GET /v2/promos/:id/codes` lists a promotion's codes. It filters by `status`, `customer_id`, `code` and `source`. The `status` filter uses the status the code reports, so `status=expired` returns codes past their `effective_expires_at`.
* `GET /v2/promos/:id/codes/:code_id` returns one code.
* `POST /v2/promos/:id/codes/:code_id/revoke` revokes a code.
* `POST /v2/promos/:id/codes/:code_id/reissue` revokes the code and creates a replacement. If the customer already holds another active code for the promotion, that code is returned and nothing new is created. The response is `{ data, replaced, created }`: `201` when a code was created, `200` with `created: false` otherwise.
* `GET /v2/customers/:id/promo-codes` lists the codes issued to one customer.
* Every code response includes a `promo` summary with the promotion's `id`, `name`, `mode`, `application`, discount fields (`onetime_discount_type`, `onetime_discount_offset`, `subscription_discount_type`, `subscription_discount_offset`, `subscription_duration_in_months`) and `scope_targets`. These use the same names as the promotion response, so you can tell what a code is worth without fetching its promotion.
* `POST /v2/promos/check` runs every eligibility check for a code and reports each one that fails. It does not stop at the first failure.

The orders list also accepts a `promo_id` filter.

### Errors

Promotion errors put a machine-readable reason in `details.reason`. Field-level problems are listed in `details.fields[]`.

| `details.reason`         | Meaning                                                                                                      |
| ------------------------ | ------------------------------------------------------------------------------------------------------------ |
| `PROMO_FOREIGN_TARGET`   | A `scope_targets` entry belongs to another account.                                                          |
| `PROMO_MODE_IMMUTABLE`   | `mode` cannot be changed after creation.                                                                     |
| `PROMO_HAS_ATTACHMENTS`  | The promotion is attached to checkout items and cannot become a `products` promotion without `detach: true`. |
| `PROMO_NOT_UNIQUE_MODE`  | The endpoint only works on `unique` promotions.                                                              |
| `PROMO_NOT_LIVE`         | The promotion is not currently live, so codes cannot be issued.                                              |
| `PROMO_FOREIGN_CUSTOMER` | The customer belongs to another account.                                                                     |
| `PROMO_INVALID_EMAIL`    | The email address is not valid.                                                                              |
| `PROMO_CODE_NOT_ACTIVE`  | The code has already been redeemed, so it cannot be revoked or reissued.                                     |

### Compatibility

`promo.code` can now be `null`, but only on `unique` promotions. The `promo_code` field on orders and subscriptions keeps its name. When a customer used an issued code, it holds that code. Otherwise it holds the promotion's shared code. Reports still group by promotion, so a unique promotion with a thousand issued codes is one row.

### MCP tools

The Spiffy connector adds `list_promo_codes`, `create_promo_code`, `get_promo_code`, `revoke_promo_code`, `reissue_promo_code`, `list_customer_promo_codes` and `check_promo_code`.

***

## 6. Webhooks for promotions and issued promo codes

> **Unreleased. Release date TBD.** This section is a draft and will be dated when the release is scheduled.

Four events follow a promotion and the unique codes it issues. Two describe the promotion and two describe a code.

| Event                | When it fires                                                                                                                                                                                                                                                                                  | `data.object`           |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| `promo:started`      | A scheduled promotion reaches its `starts_at`. A promotion that is already live when you create it does not send it.                                                                                                                                                                           | The promotion           |
| `promo:ended`        | A promotion passes its `expire_at`. Its codes stop working while it is over. Ending the promotion sends no event per code, but each code still sends `promo:code_expired` later, when its own expiry passes. Deleting a promotion does not send it, and neither does reaching its order limit. | The promotion           |
| `promo:code_issued`  | A code is issued to a customer from the dashboard, from `POST /v2/promos/:id/codes`, or by an automation.                                                                                                                                                                                      | The code                |
| `promo:code_expired` | A code stops working because it was revoked (`reason: "revoked"`; a reissue revokes the old code) or because its own expiry passed (`reason: "expired"`).                                                                                                                                      | The code, with `reason` |

Each code sends `promo:code_expired` at most once. There is no separate revoke event. When a promotion ends, you get one `promo:ended` instead of an event per code, and its codes report `status: "expired"` while the promotion is over.

### Timing

Revokes send `promo:code_expired` right away. `promo:started`, `promo:ended` and the `expired` case of `promo:code_expired` come from a job that runs every 15 minutes, so they arrive up to 15 minutes after the date that caused them. Expiry events are sent gradually. When many codes expire at the same time, some arrive hours after their `expires_at`, oldest first. To find the exact moment a code stops working, read `effective_expires_at` on the code.

If you move a promotion's `expire_at` into the future after it ended, its codes work again until their own expiry, and the promotion sends `promo:ended` again when the new date passes.

### Payloads

`promo:started` and `promo:ended` deliver the promotion record, the same object `promo:created` and `promo:updated` deliver.

`promo:code_issued` and `promo:code_expired` deliver the issued code. The `customer` and `promo` objects are shortened in this example:

```json
{
  "id": "evt_8b1c2d3e",
  "object": "event",
  "type": "promo:code_expired",
  "api_version": "v2",
  "created": 1760184000,
  "account_id": 1,
  "data": {
    "object": {
      "id": 12,
      "account_id": 1,
      "promo_id": 4,
      "customer_id": 9,
      "code": "WB-X8K92F",
      "status": "revoked",
      "reason": "revoked",
      "expires_at": "2026-11-10T00:00:00.000Z",
      "effective_expires_at": "2026-11-10T00:00:00.000Z",
      "is_expired": false,
      "source": "action",
      "source_ref": "77",
      "issued_by": null,
      "redeemed_order_id": null,
      "redeemed_at": null,
      "revoked_at": "2026-10-20T09:30:00.000Z",
      "revoked_by": "dashboard",
      "expired_at": null,
      "replaces_code_id": null,
      "replaced_by": 13,
      "created_at": "2026-10-11T12:00:00.000Z",
      "updated_at": "2026-10-20T09:30:00.000Z",
      "customer": { "id": 9, "email": "jane@example.com", "name_first": "Jane", "name_last": "Doe" },
      "promo": { "id": 4, "name": "Welcome back", "mode": "unique", "code": null }
    }
  }
}
```

Notes on the fields:

* `reason` is only on `promo:code_expired`.
* `status` says what the code can do right now. A code past its `effective_expires_at` reports `expired` and `is_expired: true` even before the stored row is updated. The REST code endpoints apply the same rule.
* `expires_at` is the code's own expiry, set when it was issued. `effective_expires_at` is the earlier of that and the promotion's `expire_at`. Use `effective_expires_at` to know when the code stops working.
* `expired_at` is when the code was recorded as expired after its own expiry passed. It is `null` for a code that is active, redeemed or revoked, and for a code that only stopped working because its promotion ended.
* `revoked_by` says who revoked the code: `dashboard`, `api`, `action` (an automation) or `system` (a customer merge). It is `null` unless the code was revoked.
* `source` says who issued the code: `dashboard`, `api`, `action` or `system`. Revoking the code does not change it.
* `source_ref` points to whoever last changed the code. At issue it is the automation's log entry ID or the API client's ID, and `null` for a dashboard issue. If an automation or an API client revokes the code, it changes to the revoker's ID. A dashboard revoke leaves it alone.
* `replaced_by` is the ID of the code that replaced this one in a reissue. It is `null` after a plain revoke, and also when the reissue created nothing because the customer already held another active code (`created: false`). The new code's `promo:code_issued` carries `replaces_code_id`, pointing back to the old code.
* `customer` is the same base customer object that order webhooks embed. `promo` is the promotion record that `promo:created` and `promo:updated` deliver. Its `code` is `null` because the promotion is `unique`.

### The code events also trigger automations

`promo:started` and `promo:ended` only send webhooks, like the `promo:created`, `promo:updated` and `promo:deleted` events added in rev 08.26. They cannot trigger automations: `PUT /v2/promos/:id/actions` answers `400` with `details.reason` set to `INTG_BADEVENTCONFIG` if you attach an automation to either one.

`promo:code_issued` and `promo:code_expired` can also trigger automations, either on one promotion (in the dashboard, or with `PUT /v2/promos/:id/actions`) or for every promotion on the account. A "Send Webhook" automation posts the flat automation format: `promo_code_id`, `code`, `code_status`, `code_expires_at`, `code_effective_expires_at`, `code_is_expired`, `code_source`, `replaced_by_code_id`, `promo_id` and `promo_name`, plus a nested `promo_code` object. `promo:code_expired` adds `code_expired_reason` and `code_revoked_by`.

The native Spiffy actions cannot be attached to either code event. An action that issues a code on `promo:code_issued` would trigger itself again. `PUT /v2/promos/:id/actions` answers `400` with `details.reason` set to `INTG_ACTION_EXCLUDED_EVENT` if you try to attach one.

The same endpoint answers `400` with `details.reason` set to `PROMO_EVENT_NOT_APPLICABLE`, naming `details.event` and `details.mode`, when you attach an automation to `promo:code_issued` or `promo:code_expired` on a `shared` promotion. A shared promotion issues no codes, so those events never fire for it.

### Compatibility

These changes are additive. If your endpoint subscribes to `*`, it starts receiving all four events when this ships. If you do not use unique promotions, you can ignore event types that start with `promo:code_`. `promo:applied` is unchanged, except that the order's `promo_code` field holds the issued code when the customer used one (see section 5).

***

## 7. Payment plan payments: in-flight and missing-card errors

> **Unreleased. Release date TBD.** This section is a draft and will be dated when the release is scheduled.

Two error responses on `POST /v2/paymentplans/:id/pay` change.

### A payment already in progress answers `409`

If another payment on the same plan is still processing, the request is refused with `409`, error code `conflict` and the message `A payment is already in progress for this payment plan.` Nothing is charged. That happens when a second request arrives while the first is still running, or when the plan has a payment from the last 30 minutes that is still `pending` or waiting on a 3D Secure challenge. Older payments don't count, so one stuck in `pending` can't block the plan forever. Before this, two requests arriving together could both pass the balance check and both charge the card.

Wait for the earlier payment to finish, then try again.

### A plan with no usable payment method answers `400`

If the card on the plan has no valid payment method, the request now answers `400` with `This payment plan has no valid payment method on file.` Before this, the request never got a response: the error escaped the handler and the connection stayed open until your client timed out. Update the plan's card and try again.

### Compatibility

Successful payments, declines and 3D Secure responses work as before. If your integration retries any non-`2xx` straight away, give a `409` some time first.
