For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.


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:

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.

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.

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

DELETE /v2/products/:id PUT /v2/products/:id/options (sort) DELETE /v2/products/:id/options/:option_id PUT /v2/products/:id/options/:option_id/prices/:price_id (move) DELETE /v2/products/:id/options/:option_id/prices/:price_id

Promos

DELETE /v2/promos/:id

Payments

POST /v2/payments/:id/retry POST /v2/payments/:id/send-receipt

Payment plans

POST /v2/paymentplans/:id/notes

Subscriptions

POST /v2/subscriptions/:id/notes

Affiliates

DELETE /v2/affiliates/programs/:program_id/affiliates/:affiliate_id PUT /v2/affiliates/programs/:program_id/options/:option_id DELETE /v2/affiliates/programs/:program_id/options/:option_id PUT /v2/affiliates/programs/:program_id/prices/:price_id DELETE /v2/affiliates/programs/:program_id/prices/:price_id PUT /v2/affiliates/programs/:program_id/checkouts/:checkout_id DELETE /v2/affiliates/programs/:program_id/checkouts/:checkout_id DELETE /v2/affiliates/programs/:program_id/links/:link_id DELETE /v2/affiliates/payouts/:payout_id


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

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

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=.

The available expansions per endpoint are listed in the OpenAPI spec at /v2/openapi.json and on 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

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=.

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.

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.


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.

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:


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:

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 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 ({ product:, { event_actions:, { slugs:, etc.) and §2 (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.

Last updated