# API Version Upgrade Guide
URL: https://www.quiltt.dev/api/version-upgrade-guide
Description: Learn what changes between Quiltt API versions and how to upgrade your API keys to the latest version.
Navigation: api → version-upgrade-guide
Tags: API, Migration
Content Length: 7k characters

Quiltt uses date-based API versioning. Breaking changes are only introduced in new versions, so your existing integration continues working until you explicitly upgrade. You can check your current version in the [Quiltt Dashboard](https://dashboard.quiltt.dev), where it appears as a version badge on each API key.

| Version | Released | What Changed |
|---|---|---|
| `2026-04-01` | April 1, 2026 | Removes deprecated fields; updates Ntropy enrichment to V3 |
| `2025-04-01` | April 1, 2025 | Renames Product and Feature enum values |
| `2024-01-01` | January 1, 2024 | Oldest supported version |

If you're upgrading across multiple versions (e.g. from `2024-01-01` to `2026-04-01`), review the changes for each version in between.

## How to Upgrade

1. **Review the changes** below for each version between your current version and the latest.
2. **Test with a header override** — Set the `Quiltt-Version` header to try the new version without changing your key:

```yaml
Quiltt-Version: "2026-04-01"
```

1. **Upgrade the key** — In the [Quiltt Dashboard](https://dashboard.quiltt.dev), open the **API Keys** page and click the **Upgrade to vX** button on the key you want to move to the newer version. Alternatively, create a new key — new keys use the latest version — migrate your deployment to use it, then delete your old key.

Info:
Test with the `Quiltt-Version` header in your development environment before updating the version on your API key. The header override applies only to that single request.

## Version 2026-04-01

This version removes previously deprecated fields and arguments, and updates the Ntropy enrichment data model to V3.

### Deprecated fields removed

If your queries reference any of these fields, update them before upgrading.

| Type | Removed Field | Use Instead |
|---|---|---|
| `Account` | `type` | `kind` or `taxonomy` |
| `Account` | `origin` | `provider` |
| `Connection` | `features` | `products` |
| `Holding` | `account` | Query from `Account.holdings` |
| `Holding` | `remoteData` | Query from `Account.remoteData` |
| `Image` | `_sourcename` | Remove from query |
| `Merchant` | `metadata` | Remove from query |
| `Merchant` | `state` | Remove from query |
| `ConnectionDisconnectPayload` | `errors` | Handle via GraphQL errors |

### Deprecated arguments removed

| Type | Field | Removed Argument | Use Instead |
|---|---|---|---|
| `Connection` | `accounts` | `search` | `filter` |
| `Account` / `Connection` | `transactions` | `search` | `filter` |
| `AccountFilter` | — | `type` | `kind` |

### Deprecated enum values removed

| Enum | Removed Value |
|---|---|
| `TransactionStatus` | `PROJECTED` |

### Deprecated subscriptions removed

| Removed | Use Instead |
|---|---|
| `connectionUpdated` | `connectionSynced` |

### Ntropy `location` type change

The `location` field on `RemoteDataNtropyEnrichedTransaction` changed from a plain `String` to a structured `RemoteDataNtropyLocation` object. If you only need the original string, use `location.rawAddress`. The new `location.structured` sub-object provides parsed address components:

**Before (≤ 2025-04-01):**

```graphql
query {
  transactions {
    nodes {
      remoteData {
        ntropy {
          enrichment [location  # "123 Main St, New York, NY"]
        }
      }
    }
  }
}
```

**After (2026-04-01):**

```graphql
query {
  transactions {
    nodes {
      remoteData {
        ntropy {
          enrichment {
            location {
              rawAddress  # "123 Main St, New York, NY"
              structured [street
                houseNumber
                city
                state
                postcode
                country
                countryCode
                storeNumber
                latitude
                longitude
                googleMapsUrl
                appleMapsUrl]
            }
          }
        }
      }
    }
  }
}
```

### Ntropy V2 fields removed

The following fields on `RemoteDataNtropyEnrichedTransaction` are removed. Use the V3 equivalents:

| Removed Field | V3 Replacement |
|---|---|
| `merchant` | `entities.counterparty.name` |
| `merchantId` | `entities.counterparty.id` |
| `person` | `entities.counterparty.type` |
| `logo` | `entities.counterparty.logo` |
| `website` | `entities.counterparty.website` |
| `mcc` | `entities.counterparty.mccs` |
| `labels` | `categories` |
| `transactionType` | `categories` |
| `locationStructured` | `location.structured` |
| `transactionId` | `id` |
| `recurrence` | — |
| `recurrenceGroup` | — |
| `recurrenceGroupId` | — |

### Ntropy enrichment endpoint change

The Ntropy enrichment data in the REST API is returned under `documents["api.ntropy.com"]`, keyed by endpoint path. In this version, the V2 path (`/v2/transactions/{mode}`) is removed for integrations enabled after April 1, 2026. Older integrations continue to receive both paths.

The document path and body structure differ between versions:

**V2 path** (`/v2/transactions/{mode}`):

```json
{
  "documents": {
    "api.ntropy.com": {
      "/v2/transactions/{mode}": {
        "id": "xbx8YP14g565Xk",
        "timestamp": "2024-06-20T18:27:49Z",
        "body": {
          "transactionId": "xbx8YP14g565Xk",
          "merchant": "Starbucks",
          "merchantId": "d4bc3c80-ec1a-3da2-836e-2a4ca4758be5",
          "logo": "https://logos.ntropy.com/starbucks.com",
          "website": "starbucks.com",
          "mcc": [5814],
          "labels": ["coffee shop"],
          "location": "10 Union Square E, New York, NY 10003, United States",
          "locationStructured": ["address": "Union Square East",
            "city": "New York",
            "state": "New York",
            "postcode": "10003",
            "country": "US"]
        }
      }
    }
  }
}
```

**V3 path** (`/v3/transactions`):

```json
{
  "documents": {
    "api.ntropy.com": {
      "/v3/transactions": {
        "id": "xbx8YP14g565Xk",
        "timestamp": "2024-06-20T18:27:49Z",
        "body": {
          "id": "xbx8YP14g565Xk",
          "entities": {
            "counterparty": ["id": "d4bc3c80-ec1a-3da2-836e-2a4ca4758be5",
              "name": "Starbucks",
              "logo": "https://logos.ntropy.com/starbucks.com",
              "website": "starbucks.com",
              "mccs": [5814],
              "type": "organization"]
          },
          "categories": ["general": "coffee shop"],
          "location": {
            "rawAddress": "10 Union Square E, New York, NY 10003, United States",
            "structured": ["street": "Union Square East",
              "city": "New York",
              "state": "New York",
              "postcode": "10003",
              "countryCode": "US",
              "country": "United States"]
          }
        }
      }
    }
  }
}
```

If your code accesses Ntropy data via the REST API, update it to read from the `/v3/transactions` path and use the nested body structure.

## Version 2025-04-01

This version replaces the `features` field with `products` on Connections, using more descriptive enum values:

### Product and Feature enum renames

| Removed | Replacement |
|---|---|
| `BALANCES` | `ACCOUNT_BALANCE_REFRESHES` |
| `STATEMENTS` | `ACCOUNT_STATEMENTS` |
| `TRANSACTIONS` | `ACCOUNT_BALANCES_AND_TRANSACTIONS` |

If your queries use `features`, switch to `products` with the new values:

```graphql
query {
  connections [# was: features returning [TRANSACTIONS, BALANCES]
    products  # now: [ACCOUNT_BALANCES_AND_TRANSACTIONS, ACCOUNT_BALANCE_REFRESHES]]
}
```

## Version 2024-01-01

This is the oldest currently supported API version. If you're still on `2024-01-01`, review the changes in each version above to plan your upgrade.