Book a demo
Browse the docs

Versioning

How API versions work, and what changed recently.

This page states how Moon versions its API and what changed and when. For help choosing between the two versions, see API versions.

Versioning policy

Versions live in the path

There are two versions, and the version is part of the URL:

The URL you call decides which contract you get.

Both versions are live and supported. Neither is deprecated, and no end-of-life date has been announced for either. V2 is not a superset of V1: each has resources the other does not, and many integrations use both with the same API key. They operate on the same underlying records — a card issued through V1 is readable through V2, and the ids are identical.

What counts as a breaking change

Breaking changes are introduced as a new version rather than by changing an existing one. Within a version, treat these as changes that can arrive at any time, and write your client so they do not break it:

Additive — can ship at any time

  • New endpoints.
  • New optional fields in a request body or query string.
  • New fields in a response object.
  • New values in an enum, including new error code values and new webhook event types.
  • New entry types in the transaction feed.

Breaking — would ship as a new version

  • Removing or renaming a request field, response field or endpoint.
  • Making an optional request field required.
  • Changing the type of a field, or the HTTP status of a successful response.
  • Removing a value from an enum.

To stay compatible with the additive set:

  • Ignore fields you do not recognise. Do not fail on an unexpected key.
  • Treat enums as open. Handle an unknown status, type or code as "something new" rather than as an error.
  • Branch on the HTTP status first, then on code. Never parse message; its wording is not stable. See Errors.
  • Do not depend on field order, or on fields the reference marks as internal.

One spelling per field

Response fields are snake_case, and each field has exactly one spelling: the API carries no camelCase duplicates. Webhook deliveries are a separate contract — card and credit events carry a deprecated_fields array naming the fields in that object that have a preferred replacement; see Webhooks.

These keys are camelCase, and camelCase is the spelling to send and read them with:

  • velocityControls — the list key on the velocity-control listings; velocityControlId on the cardholder velocity-status route.
  • The current_page and per_page query parameters on the transaction feeds, plus start_date, end_date and transactionType on GET /v2/api-gateway/accounts/{id}/transactions.

Pagination and Data formats and ids list where each of these appears.

How changes are communicated

  • The endpoint pages and the OpenAPI specifications behind them are updated when the API changes, so the reference always describes the API that is running.
  • For advance warning of a change on a specific endpoint, write to our team and say which endpoints you depend on.

Sandbox and production run the same request and response shapes, so Sandbox is the place to check a behaviour you are unsure about before it reaches your customers. See Environments.

Last updated August 18, 2026