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.
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 toresponse.okorstatus >= 200 && status < 300), orcall
.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):
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:
GET /v2/subscriptions/
customer, order, payments
GET /v2/orders/
customer, items, payments, subscriptions, paymentplans
GET /v2/paymentplans/
customer, order, payments, items
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:
Pull the latest OpenAPI spec from
/v2/openapi.json— it reflects the new shapes.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