Versioning & deprecations
How the Fungies API versions changes, what counts as breaking, and which fields are deprecated today.
The Fungies API is versioned in the URL. Every endpoint today lives under /v0:
https://api.fungies.io/v0/orders/listThe version in the path is the whole contract — a call made against /v0 today keeps working
against /v0 tomorrow.
What we can change without a new version
These are additive changes. They ship into /v0 at any time, and your integration must
tolerate them:
- New fields on existing responses. Ignore fields you don't recognise.
- New endpoints and new resources.
- New optional request parameters, with the previous behaviour as the default.
- New enum values — new order statuses, payment types, webhook event types.
What a new version would be for
A breaking change gets a new URL version rather than being applied to /v0:
- Removing a field or an endpoint
- Renaming a field, or changing its type
- Making an optional parameter required
- Changing the meaning of an existing value
Deprecated fields are the bridge between the two: they keep working in /v0 while their
replacements become the documented way to do the same thing.
Writing a tolerant client
The single most common integration break is a strict parser. If your client rejects unknown fields or unknown enum values, a routine additive change will break it.
- Ignore unknown fields. Don't validate responses with a schema that forbids extra keys.
- Handle unknown enum values. Log and skip an unrecognised event
typeor status instead of throwing — see the Event object. - Don't depend on key order or on the absence of a field.
Current deprecations
These fields still work in /v0 and are not going away without a version change, but new code
should use the replacement.
| Deprecated | Where | Use instead |
|---|---|---|
customer | payment_success, payment_refunded, payment_failed webhook payloads | user — data.customer and data.user are the same User object. |
price | items[] in the subscription create, update, and charge request bodies | unitPrice |
value | items[] in the same three request bodies | unitPrice |
archived | PATCH /v0/users/{userId}/archive response | success — both are true on a successful archive. |
subscriptionId | Query filter on GET /v0/orders/list and GET /v0/payments/list | subscriptionNumber |
cancelOption | PATCH /v0/subscriptions/{subscriptionIdOrNumber}/cancel request | cancelAtIntervalEnd — cancelOption: "endInterval" becomes cancelAtIntervalEnd: true. |
Item pricing precedence. If you send more than one of these on the same item, unitPrice wins,
then value, then price. Send only unitPrice.
What deprecated means here
A deprecated field is still live. It keeps its current behaviour, and nothing in the table above is
scheduled for removal from /v0 — removing it would be a breaking change, and breaking changes get
a new URL version. Treat the table as "migrate when convenient", not "migrate before a deadline".
Last updated
Rate limits & request IDs
How the Fungies API rate limits requests, how to back off from a 429, and how to correlate a call with x-request-id.
List discounts GET
Retrieve a paginated list of discounts with powerful filtering options. Discounts can be coupon codes that customers enter at checkout, or automatic sale discounts applied based on conditions. Results are sorted by creation date (newest first) by default.