nested object deserialization

CHANGELOG.md

@@ -1,3 +1,13 @@
+### v4.8.0 (2026-06-02)
+* * *
+### Enhancements:
+* Added a `fromJson(Map<String, Object>)` overload to all models, so nested map entities can be converted to a typed model directly (e.g. `Subscription.fromJson(subscription)`).
+
+
+### Bug Fixes:
+* Fixed deserialization of nested JSON in dynamic `Map<String, Object>` fields (for example [`HostedPage.getContent()`](https://apidocs.chargebee.com/docs/api/hosted_pages/hosted-page-object#content) and [`HostedPage.getCheckoutInfo()`](https://apidocs.chargebee.com/docs/api/hosted_pages/hosted-page-object#checkout_info)). Nested objects and arrays are now returned as `Map` and `List` instead of JSON strings, which resolves `ClassCastException` when casting nested entities such as `customer`, `subscription`, and `invoice` to `Map<String, Object>`. The same parsing behavior applies to other map attributes including [`Event.getContent()`](https://apidocs.chargebee.com/docs/api/events/event-object#content), `meta_data`, and `consent_fields`. If your integration previously parsed nested map values as JSON strings, use the returned `Map`/`List` directly or branch on `instanceof` during upgrade.
+
+
 ### v4.7.0 (2026-05-04)
 * * *
 ### New Resources:
@@ -86,7 +96,6 @@
 - `mada` has been added as a new value to enum request body parameter `card.brand` in [`create_using_permanent_token`](https://apidocs.chargebee.com/docs/api/payment_sources/create-using-permanent-token) of [`PaymentSource`](https://apidocs.chargebee.com/docs/api/payment_sources).
 
 
-
 ### v4.6.0 (2026-03-27)
 * * *
 ### New Resources:

README.md

@@ -221,6 +221,24 @@ future.thenAccept(resp -> {
 });
 ```
 
+### Dynamic map fields (`Map<String, Object>`)
+
+Some attributes are returned as `Map<String, Object>` for schema-less JSON (for example `HostedPage.getContent()`, `HostedPage.getCheckoutInfo()`, `Event.getContent()`, `meta_data`). Nested JSON objects become `Map`, and nested JSON arrays become `List`:
+
+```java
+Map<String, Object> content = client.hostedPages().retrieve(hostedPageId).getHostedPage().getContent();
+
+@SuppressWarnings("unchecked")
+Map<String, Object> subscription = (Map<String, Object>) content.get("subscription");
+String subscriptionId = (String) subscription.get("id");
+```
+
+Every model exposes a `fromJson(Map<String, Object>)` overload, so a nested entity can be converted into a typed model by passing the map directly—no JSON string round-trip needed:
+
+```java
+Subscription typedSubscription = Subscription.fromJson(subscription);
+```
+
 ### Custom Field Filtering
 
 Filter list operations by custom fields using type-safe filters (`stringFilter()`, `numberFilter()`, `timestampFilter()`, `booleanFilter()`):
@@ -679,6 +697,7 @@ public class Sample {
 - Immutable `ChargebeeClient` with fluent builder
 - Direct property naming (e.g., `.apiKey()`, `.siteName()`)
 - Type-safe request models and responses
+- Dynamic `Map<String, Object>` fields deserialize nested JSON as maps and lists (see [Dynamic map fields](#dynamic-map-fields-mapstring-object))
 - Sync and async APIs with retry/backoff
 - Per-request options and headers
 - Enhanced error handling and debugging

VERSION

@@ -1 +1 @@
-4.7.0
+4.8.0

build.gradle.kts

@@ -7,7 +7,7 @@ plugins {
 }
 
 group = "com.chargebee"
-version = "4.7.0"
+version = "4.8.0"
 description = "Java client library for ChargeBee"
 
 // Project metadata

src/main/java/com/chargebee/v4/internal/JsonUtil.java

@@ -149,7 +149,7 @@ public static boolean hasValue(JsonObject obj, String key) {
 
     // --- JsonObject to Map conversion ---
 
-    /** Converts a JsonObject to a Map; primitives become Java types, nested structures become JSON strings. */
+    /** Converts a JsonObject to a Map; primitives become Java types, nested objects become nested maps, arrays become lists. */
     public static Map<String, Object> parseJsonObjectToMap(JsonObject obj) {
         Map<String, Object> map = new HashMap<>();
         if (obj == null) return map;
@@ -357,8 +357,11 @@ private static Object toJavaValue(JsonElement value) {
                 return prim.getAsLong();
             }
         }
-        if (value.isJsonObject() || value.isJsonArray()) {
-            return value.toString();
+        if (value.isJsonObject()) {
+            return parseJsonObjectToMap(value.getAsJsonObject());
+        }
+        if (value.isJsonArray()) {
+            return mapArrayToObjects(value.getAsJsonArray());
         }
         return null;
     }

src/main/java/com/chargebee/v4/models/addon/Addon.java

@@ -549,6 +549,10 @@ public static Addon fromJson(String json) {
     return fromJson(JsonUtil.parse(json));
   }
 
+  public static Addon fromJson(java.util.Map<String, Object> map) {
+    return fromJson(JsonUtil.toJson(map));
+  }
+
   public static Addon fromJson(JsonObject jsonObj) {
     Addon obj = new Addon();
 
@@ -1021,6 +1025,10 @@ public static Tiers fromJson(String json) {
       return fromJson(JsonUtil.parse(json));
     }
 
+    public static Tiers fromJson(java.util.Map<String, Object> map) {
+      return fromJson(JsonUtil.toJson(map));
+    }
+
     public static Tiers fromJson(JsonObject jsonObj) {
       Tiers obj = new Tiers();
 
@@ -1118,6 +1126,10 @@ public static TaxProvidersFields fromJson(String json) {
       return fromJson(JsonUtil.parse(json));
     }
 
+    public static TaxProvidersFields fromJson(java.util.Map<String, Object> map) {
+      return fromJson(JsonUtil.toJson(map));
+    }
+
     public static TaxProvidersFields fromJson(JsonObject jsonObj) {
       TaxProvidersFields obj = new TaxProvidersFields();
 

src/main/java/com/chargebee/v4/models/address/Address.java

@@ -129,6 +129,10 @@ public static Address fromJson(String json) {
     return fromJson(JsonUtil.parse(json));
   }
 
+  public static Address fromJson(java.util.Map<String, Object> map) {
+    return fromJson(JsonUtil.toJson(map));
+  }
+
   public static Address fromJson(JsonObject jsonObj) {
     Address obj = new Address();
 

src/main/java/com/chargebee/v4/models/advanceInvoiceSchedule/AdvanceInvoiceSchedule.java

@@ -66,6 +66,10 @@ public static AdvanceInvoiceSchedule fromJson(String json) {
     return fromJson(JsonUtil.parse(json));
   }
 
+  public static AdvanceInvoiceSchedule fromJson(java.util.Map<String, Object> map) {
+    return fromJson(JsonUtil.toJson(map));
+  }
+
   public static AdvanceInvoiceSchedule fromJson(JsonObject jsonObj) {
     AdvanceInvoiceSchedule obj = new AdvanceInvoiceSchedule();
 
@@ -187,6 +191,10 @@ public static FixedIntervalSchedule fromJson(String json) {
       return fromJson(JsonUtil.parse(json));
     }
 
+    public static FixedIntervalSchedule fromJson(java.util.Map<String, Object> map) {
+      return fromJson(JsonUtil.toJson(map));
+    }
+
     public static FixedIntervalSchedule fromJson(JsonObject jsonObj) {
       FixedIntervalSchedule obj = new FixedIntervalSchedule();
 
@@ -267,6 +275,10 @@ public static SpecificDatesSchedule fromJson(String json) {
       return fromJson(JsonUtil.parse(json));
     }
 
+    public static SpecificDatesSchedule fromJson(java.util.Map<String, Object> map) {
+      return fromJson(JsonUtil.toJson(map));
+    }
+
     public static SpecificDatesSchedule fromJson(JsonObject jsonObj) {
       SpecificDatesSchedule obj = new SpecificDatesSchedule();
 

src/main/java/com/chargebee/v4/models/alert/Alert.java

@@ -122,6 +122,10 @@ public static Alert fromJson(String json) {
     return fromJson(JsonUtil.parse(json));
   }
 
+  public static Alert fromJson(java.util.Map<String, Object> map) {
+    return fromJson(JsonUtil.toJson(map));
+  }
+
   public static Alert fromJson(JsonObject jsonObj) {
     Alert obj = new Alert();
 

src/main/java/com/chargebee/v4/models/alertStatus/AlertStatus.java

@@ -66,6 +66,10 @@ public static AlertStatus fromJson(String json) {
     return fromJson(JsonUtil.parse(json));
   }
 
+  public static AlertStatus fromJson(java.util.Map<String, Object> map) {
+    return fromJson(JsonUtil.toJson(map));
+  }
+
   public static AlertStatus fromJson(JsonObject jsonObj) {
     AlertStatus obj = new AlertStatus();
 

src/main/java/com/chargebee/v4/models/attachedItem/AttachedItem.java

@@ -224,6 +224,10 @@ public static AttachedItem fromJson(String json) {
     return fromJson(JsonUtil.parse(json));
   }
 
+  public static AttachedItem fromJson(java.util.Map<String, Object> map) {
+    return fromJson(JsonUtil.toJson(map));
+  }
+
   public static AttachedItem fromJson(JsonObject jsonObj) {
     AttachedItem obj = new AttachedItem();
 

src/main/java/com/chargebee/v4/models/attribute/Attribute.java

@@ -27,6 +27,10 @@ public static Attribute fromJson(String json) {
     return fromJson(JsonUtil.parse(json));
   }
 
+  public static Attribute fromJson(java.util.Map<String, Object> map) {
+    return fromJson(JsonUtil.toJson(map));
+  }
+
   public static Attribute fromJson(JsonObject jsonObj) {
     Attribute obj = new Attribute();
 

src/main/java/com/chargebee/v4/models/billingConfiguration/BillingConfiguration.java

@@ -29,6 +29,10 @@ public static BillingConfiguration fromJson(String json) {
     return fromJson(JsonUtil.parse(json));
   }
 
+  public static BillingConfiguration fromJson(java.util.Map<String, Object> map) {
+    return fromJson(JsonUtil.toJson(map));
+  }
+
   public static BillingConfiguration fromJson(JsonObject jsonObj) {
     BillingConfiguration obj = new BillingConfiguration();
 
@@ -83,6 +87,10 @@ public static BillingDates fromJson(String json) {
       return fromJson(JsonUtil.parse(json));
     }
 
+    public static BillingDates fromJson(java.util.Map<String, Object> map) {
+      return fromJson(JsonUtil.toJson(map));
+    }
+
     public static BillingDates fromJson(JsonObject jsonObj) {
       BillingDates obj = new BillingDates();
 

src/main/java/com/chargebee/v4/models/brand/Brand.java

@@ -27,6 +27,10 @@ public static Brand fromJson(String json) {
     return fromJson(JsonUtil.parse(json));
   }
 
+  public static Brand fromJson(java.util.Map<String, Object> map) {
+    return fromJson(JsonUtil.toJson(map));
+  }
+
   public static Brand fromJson(JsonObject jsonObj) {
     Brand obj = new Brand();
 

src/main/java/com/chargebee/v4/models/businessEntity/BusinessEntity.java

@@ -81,6 +81,10 @@ public static BusinessEntity fromJson(String json) {
     return fromJson(JsonUtil.parse(json));
   }
 
+  public static BusinessEntity fromJson(java.util.Map<String, Object> map) {
+    return fromJson(JsonUtil.toJson(map));
+  }
+
   public static BusinessEntity fromJson(JsonObject jsonObj) {
     BusinessEntity obj = new BusinessEntity();
 

src/main/java/com/chargebee/v4/models/businessEntityTransfer/BusinessEntityTransfer.java

@@ -112,6 +112,10 @@ public static BusinessEntityTransfer fromJson(String json) {
     return fromJson(JsonUtil.parse(json));
   }
 
+  public static BusinessEntityTransfer fromJson(java.util.Map<String, Object> map) {
+    return fromJson(JsonUtil.toJson(map));
+  }
+
   public static BusinessEntityTransfer fromJson(JsonObject jsonObj) {
     BusinessEntityTransfer obj = new BusinessEntityTransfer();
 

src/main/java/com/chargebee/v4/models/card/Card.java

@@ -478,6 +478,10 @@ public static Card fromJson(String json) {
     return fromJson(JsonUtil.parse(json));
   }
 
+  public static Card fromJson(java.util.Map<String, Object> map) {
+    return fromJson(JsonUtil.toJson(map));
+  }
+
   public static Card fromJson(JsonObject jsonObj) {
     Card obj = new Card();
 

src/main/java/com/chargebee/v4/models/comment/Comment.java

@@ -140,6 +140,10 @@ public static Comment fromJson(String json) {
     return fromJson(JsonUtil.parse(json));
   }
 
+  public static Comment fromJson(java.util.Map<String, Object> map) {
+    return fromJson(JsonUtil.toJson(map));
+  }
+
   public static Comment fromJson(JsonObject jsonObj) {
     Comment obj = new Comment();
 

src/main/java/com/chargebee/v4/models/configuration/Configuration.java

@@ -95,6 +95,10 @@ public static Configuration fromJson(String json) {
     return fromJson(JsonUtil.parse(json));
   }
 
+  public static Configuration fromJson(java.util.Map<String, Object> map) {
+    return fromJson(JsonUtil.toJson(map));
+  }
+
   public static Configuration fromJson(JsonObject jsonObj) {
     Configuration obj = new Configuration();
 

src/main/java/com/chargebee/v4/models/contact/Contact.java

@@ -62,6 +62,10 @@ public static Contact fromJson(String json) {
     return fromJson(JsonUtil.parse(json));
   }
 
+  public static Contact fromJson(java.util.Map<String, Object> map) {
+    return fromJson(JsonUtil.toJson(map));
+  }
+
   public static Contact fromJson(JsonObject jsonObj) {
     Contact obj = new Contact();
 

src/main/java/com/chargebee/v4/models/contractTerm/ContractTerm.java

@@ -142,6 +142,10 @@ public static ContractTerm fromJson(String json) {
     return fromJson(JsonUtil.parse(json));
   }
 
+  public static ContractTerm fromJson(java.util.Map<String, Object> map) {
+    return fromJson(JsonUtil.toJson(map));
+  }
+
   public static ContractTerm fromJson(JsonObject jsonObj) {
     ContractTerm obj = new ContractTerm();
 

src/main/java/com/chargebee/v4/models/coupon/Coupon.java

@@ -468,6 +468,10 @@ public static Coupon fromJson(String json) {
     return fromJson(JsonUtil.parse(json));
   }
 
+  public static Coupon fromJson(java.util.Map<String, Object> map) {
+    return fromJson(JsonUtil.toJson(map));
+  }
+
   public static Coupon fromJson(JsonObject jsonObj) {
     Coupon obj = new Coupon();
 
@@ -877,6 +881,10 @@ public static ItemConstraints fromJson(String json) {
       return fromJson(JsonUtil.parse(json));
     }
 
+    public static ItemConstraints fromJson(java.util.Map<String, Object> map) {
+      return fromJson(JsonUtil.toJson(map));
+    }
+
     public static ItemConstraints fromJson(JsonObject jsonObj) {
       ItemConstraints obj = new ItemConstraints();
 
@@ -979,6 +987,10 @@ public static ItemConstraintCriteria fromJson(String json) {
       return fromJson(JsonUtil.parse(json));
     }
 
+    public static ItemConstraintCriteria fromJson(java.util.Map<String, Object> map) {
+      return fromJson(JsonUtil.toJson(map));
+    }
+
     public static ItemConstraintCriteria fromJson(JsonObject jsonObj) {
       ItemConstraintCriteria obj = new ItemConstraintCriteria();
 
@@ -1115,6 +1127,10 @@ public static CouponConstraints fromJson(String json) {
       return fromJson(JsonUtil.parse(json));
     }
 
+    public static CouponConstraints fromJson(java.util.Map<String, Object> map) {
+      return fromJson(JsonUtil.toJson(map));
+    }
+
     public static CouponConstraints fromJson(JsonObject jsonObj) {
       CouponConstraints obj = new CouponConstraints();
 

src/main/java/com/chargebee/v4/models/couponCode/CouponCode.java

@@ -72,6 +72,10 @@ public static CouponCode fromJson(String json) {
     return fromJson(JsonUtil.parse(json));
   }
 
+  public static CouponCode fromJson(java.util.Map<String, Object> map) {
+    return fromJson(JsonUtil.toJson(map));
+  }
+
   public static CouponCode fromJson(JsonObject jsonObj) {
     CouponCode obj = new CouponCode();
 

src/main/java/com/chargebee/v4/models/couponSet/CouponSet.java

@@ -52,6 +52,10 @@ public static CouponSet fromJson(String json) {
     return fromJson(JsonUtil.parse(json));
   }
 
+  public static CouponSet fromJson(java.util.Map<String, Object> map) {
+    return fromJson(JsonUtil.toJson(map));
+  }
+
   public static CouponSet fromJson(JsonObject jsonObj) {
     CouponSet obj = new CouponSet();
 

src/main/java/com/chargebee/v4/models/cpqQuoteSignature/CpqQuoteSignature.java

@@ -175,6 +175,10 @@ public static CpqQuoteSignature fromJson(String json) {
     return fromJson(JsonUtil.parse(json));
   }
 
+  public static CpqQuoteSignature fromJson(java.util.Map<String, Object> map) {
+    return fromJson(JsonUtil.toJson(map));
+  }
+
   public static CpqQuoteSignature fromJson(JsonObject jsonObj) {
     CpqQuoteSignature obj = new CpqQuoteSignature();