Data API Migration Guide

Migrating from v1.4.0 to v2.0.0

Overview

This document describes the changes introduced in version 2.0.0 of the Adatree Data API. It covers new endpoints, deprecated endpoints, schema changes, and the steps you need to take to migrate your integration.

Affected API Paths

Breaking changes (Fees, Discounts, Rate Tiers) and additive change (Instalments) affect two endpoints:

Path	Operation	Response Schema	Affected Sub-Schemas
`GET /data/banking/accounts`	`getBankingAccounts`	`BankingAccountList` → `BankingAccountDetail`	`fees[]` (BankingProductFee → BankingProductDiscount), `depositRates[].tiers[]` (BankingProductRateTierV3), `lendingRates[].tiers[]` (BankingProductRateTierV3), `instalments` (new)
`GET /data/banking/products`	`getBankingProducts`	`BankingProductList` → `BankingProductDetail`	`fees[]` (BankingProductFee → BankingProductDiscount), `depositRates[].tiers[]` (BankingProductRateTierV3), `lendingRates[].tiers[]` (BankingProductRateTierV3), `instalments` (new)

All other data API paths (transactions, payees, direct-debits, scheduled-payments, balances, energy endpoints) do not embed product reference data and are unaffected by these breaking changes.

Changelog Summary

New Additions

Field	Schema	Purpose
`BankingProductDetail.instalments`	`BankingProductDetail`	Instalment options for lending products

Updates

Schema	Old Structure	New Structure
`BankingProductFee`	Flat fields: `amount`, `balanceRate`, `transactionRate`, `accruedRate`, `accrualFrequency`	Discriminator `feeMethodUType` + nested `fixedAmount`/`rateBased`/`variable`
`BankingProductDiscount`	Flat fields: `amount`, `balanceRate`, `transactionRate`, `accruedRate`, `feeRate`	Discriminator `discountMethodUType` + nested `fixedAmount`/`rateBased`
`BankingProductRateTierV3`	Numeric `minimumValue`/`maximumValue`; singular `applicabilityConditions`	String `minimumValueString` (required)/`maximumValueString`; array `applicabilityConditionList`

Removals

Schemas	Status
`QueryPlanIds`, `QueryPlanTypes`, `QueryPlanFuelTypes`, `QueryPlanEffective`, `QueryPlanUpdatedSince`	Removed in v2.0.0 as they are never referenced in live API

Breaking Changes for API Users

1. Banking Product Fees – Flat Fields Removed

Old (v1.2.0):

{
  "name": "Monthly Fee",
  "feeType": "PERIODIC",
  "amount": "15.00",
  "balanceRate": null,
  "transactionRate": null,
  "accruedRate": null,
  "accrualFrequency": null,
  "feeMethodUType": "fixedAmount",
  "fixedAmount": {
    "amount": "15.00"
  },
  "currency": "AUD"
}

New (v2.0.0):

{
  "name": "Monthly Fee",
  "feeType": "PERIODIC",
  "feeMethodUType": "fixedAmount",
  "fixedAmount": {
    "amount": "15.00"
  },
  "currency": "AUD"
}

Fields Removed (required migration):

amount (deprecated)
balanceRate (deprecated)
transactionRate (deprecated)
accruedRate (deprecated)
accrualFrequency (deprecated)

Required Field Added:

feeMethodUType (enum: fixedAmount, rateBased, variable)

Action: Consumers must update JSON parsing to read from feeMethodUType + fixedAmount.amount / rateBased.rate / variable instead of flat fields.

2. Banking Product Discounts – Flat Fields Removed

Old (v1.2.0):

{
  "description": "Loyalty Discount",
  "discountType": "BALANCE",
  "amount": "0.50",
  "balanceRate": null,
  "transactionRate": null,
  "accruedRate": null,
  "feeRate": null,
  "discountMethodUType": "fixedAmount",
  "fixedAmount": {
    "amount": "0.50"
  }
}

New (v2.0.0):

{
  "description": "Loyalty Discount",
  "discountType": "BALANCE",
  "discountMethodUType": "fixedAmount",
  "fixedAmount": {
    "amount": "0.50"
  }
}

Fields Removed (required migration):

amount (deprecated)
balanceRate (deprecated)
transactionRate (deprecated)
accruedRate (deprecated)
feeRate (deprecated)

Required Field Added:

discountMethodUType (enum: FIXED_AMOUNT, RATE_BASED)

Action: Consumers must update JSON parsing to read from discountMethodUType + fixedAmount.amount / rateBased.rate instead of flat fields.

3. Banking Product Rate Tiers – Numeric Bounds → String Equivalents

Old (v1.2.0):

{
  "name": "Term 12-24 Months",
  "unitOfMeasure": "MONTH",
  "minimumValue": 12,
  "maximumValue": 24,
  "minimumValueString": "12",
  "maximumValueString": "24",
  "applicabilityConditions": {
    "rateApplicabilityType": "OTHER",
    "additionalInfo": "..."
  },
  "applicabilityConditionList": [
    {
      "rateApplicabilityType": "OTHER",
      "additionalInfo": "..."
    }
  ]
}

New (v2.0.0):

{
  "name": "Term 12-24 Months",
  "unitOfMeasure": "MONTH",
  "minimumValueString": "12",
  "maximumValueString": "24",
  "applicabilityConditionList": [
    {
      "rateApplicabilityType": "OTHER",
      "additionalInfo": "..."
    }
  ]
}

Fields Removed (required migration):

minimumValue (numeric, deprecated)
maximumValue (numeric, deprecated)
applicabilityConditions (singular, deprecated)

Required Field Added:

minimumValueString (string, required — no longer optional)

Fields Added:

maximumValueString (string)
applicabilityConditionList (array of conditions, replaces singular)

Action: Consumers must:

Change numeric parsing of tier bounds to string parsing
Support tiers with non-numeric bounds (e.g., “1 - 2 months”)
Update condition logic to iterate applicabilityConditionList (array) instead of reading singular applicabilityConditions

4. Banking Product Detail – Instalments Field (Additive)

Field: BankingProductDetail.instalments (new, optional in v2.0.0)

Status: Not present in v1.2.0 (api-specs); added in v2.0.0 (draft)
Schema: References existing BankingProductInstalments type
Purpose: Specify instalment options available for lending products
Action: Consumers can optionally parse; not required for core functionality. SDK regeneration captures this field; code updates optional.

5. Error Response Format – Generator-Level Change

Field: SecuredCdsDataApiError references to EnergyPlanContractV2

Change: Wrapped in allOf (was only $ref previously)
Impact: Some OpenAPI generators emit inline vs. reference types differently
Action: Regenerate SDKs; verify generated code compiles and type structures match expectations

6. Removed Unused Query Parameter Types (Non-Breaking)

Schemas in v1.2.0:

QueryPlanIds
QueryPlanTypes
QueryPlanFuelTypes
QueryPlanEffective
QueryPlanUpdatedSince

Status in v2.0.0: Removed — not present in v2.0.0 spec

Action: No impact on live API; these parameter types were never referenced in active endpoints. Removal is spec cleanup only.

Migration Steps

All Consumers

Regenerate SDK from v2.0.0 spec
Update code to use feeMethodUType/discountMethodUType discriminators + nested objects for fees/discounts
Update tier parsing: string bounds + array of conditions

Optional Features

Instalments: Parse BankingProductDetail.instalments if present