Add custom field support for sub-resources

CHANGELOG.md

@@ -1,3 +1,9 @@
+### v4.0.3 (2026-02-05)
+* * *
+
+### New Features:
+* Add custom field support for sub-resources in HostedPage, PricingPageSession, Quote, Subscription, and Gift operations.
+
 ### v4.0.2 (2026-01-30)
 * * *
 

VERSION

@@ -1 +1 @@
-4.0.2
+4.0.3

build.gradle.kts

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

src/main/java/com/chargebee/v4/models/addon/params/AddonListParams.java

@@ -11,7 +11,6 @@
 import com.chargebee.v4.filters.StringFilter;
 import com.chargebee.v4.filters.NumberFilter;
 import com.chargebee.v4.filters.TimestampFilter;
-
 import com.chargebee.v4.filters.CustomFieldSelector;
 
 import java.util.Collections;

src/main/java/com/chargebee/v4/models/coupon/params/CouponListParams.java

@@ -10,7 +10,6 @@
 import com.chargebee.v4.internal.Recommended;
 import com.chargebee.v4.filters.StringFilter;
 import com.chargebee.v4.filters.TimestampFilter;
-
 import com.chargebee.v4.filters.CustomFieldSelector;
 
 import java.util.Collections;

src/main/java/com/chargebee/v4/models/customer/params/CustomerListParams.java

@@ -10,7 +10,6 @@
 import com.chargebee.v4.internal.Recommended;
 import com.chargebee.v4.filters.StringFilter;
 import com.chargebee.v4.filters.TimestampFilter;
-
 import com.chargebee.v4.filters.CustomFieldSelector;
 
 import java.util.Collections;

src/main/java/com/chargebee/v4/models/feature/params/FeatureListParams.java

@@ -9,7 +9,6 @@
 
 import com.chargebee.v4.internal.Recommended;
 import com.chargebee.v4.filters.StringFilter;
-
 import com.chargebee.v4.filters.CustomFieldSelector;
 
 import java.util.Collections;

src/main/java/com/chargebee/v4/models/gift/params/GiftCreateParams.java

@@ -9,6 +9,7 @@
 import com.chargebee.v4.internal.Recommended;
 import com.chargebee.v4.internal.JsonUtil;
 
+import java.util.Collections;
 import java.util.LinkedHashMap;
 import java.util.Map;
 import java.util.List;
@@ -1107,13 +1108,20 @@ public static final class SubscriptionParams {
 
     private final String planQuantityInDecimal;
 
+    private final Map<String, String> customFields;
+
     private SubscriptionParams(SubscriptionBuilder builder) {
 
       this.planId = builder.planId;
 
       this.planQuantity = builder.planQuantity;
 
       this.planQuantityInDecimal = builder.planQuantityInDecimal;
+
+      this.customFields =
+          builder.customFields.isEmpty()
+              ? Collections.emptyMap()
+              : Collections.unmodifiableMap(new LinkedHashMap<>(builder.customFields));
     }
 
     public String getPlanId() {
@@ -1128,6 +1136,10 @@ public String getPlanQuantityInDecimal() {
       return planQuantityInDecimal;
     }
 
+    public Map<String, String> customFields() {
+      return customFields;
+    }
+
     /** Get the form data for this request. */
     public Map<String, Object> toFormData() {
       Map<String, Object> formData = new LinkedHashMap<>();
@@ -1147,6 +1159,8 @@ public Map<String, Object> toFormData() {
         formData.put("plan_quantity_in_decimal", this.planQuantityInDecimal);
       }
 
+      formData.putAll(customFields);
+
       return formData;
     }
 
@@ -1164,6 +1178,8 @@ public static final class SubscriptionBuilder {
 
       private String planQuantityInDecimal;
 
+      private Map<String, String> customFields = new LinkedHashMap<>();
+
       private SubscriptionBuilder() {}
 
       public SubscriptionBuilder planId(String value) {
@@ -1181,6 +1197,42 @@ public SubscriptionBuilder planQuantityInDecimal(String value) {
         return this;
       }
 
+      /**
+       * Add a custom field to the request. Custom fields must start with "cf_".
+       *
+       * @param fieldName the name of the custom field (e.g., "cf_custom_field_name")
+       * @param value the value of the custom field
+       * @return this builder
+       * @throws IllegalArgumentException if fieldName doesn't start with "cf_"
+       */
+      public SubscriptionBuilder customField(String fieldName, String value) {
+        if (fieldName == null || !fieldName.startsWith("cf_")) {
+          throw new IllegalArgumentException("Custom field name must start with 'cf_'");
+        }
+        this.customFields.put(fieldName, value);
+        return this;
+      }
+
+      /**
+       * Add multiple custom fields to the request. All field names must start with "cf_".
+       *
+       * @param customFields map of custom field names to values
+       * @return this builder
+       * @throws IllegalArgumentException if any field name doesn't start with "cf_"
+       */
+      public SubscriptionBuilder customFields(Map<String, String> customFields) {
+        if (customFields != null) {
+          for (Map.Entry<String, String> entry : customFields.entrySet()) {
+            if (entry.getKey() == null || !entry.getKey().startsWith("cf_")) {
+              throw new IllegalArgumentException(
+                  "Custom field name must start with 'cf_': " + entry.getKey());
+            }
+            this.customFields.put(entry.getKey(), entry.getValue());
+          }
+        }
+        return this;
+      }
+
       public SubscriptionParams build() {
         return new SubscriptionParams(this);
       }

src/main/java/com/chargebee/v4/models/hostedPage/params/HostedPageCheckoutExistingForItemsParams.java

@@ -8,6 +8,7 @@
 
 import com.chargebee.v4.internal.Recommended;
 
+import java.util.Collections;
 import java.util.LinkedHashMap;
 import java.util.Map;
 import java.util.List;
@@ -752,6 +753,8 @@ public static final class SubscriptionParams {
 
     private final Integer contractTermBillingCycleOnRenewal;
 
+    private final Map<String, String> customFields;
+
     private SubscriptionParams(SubscriptionBuilder builder) {
 
       this.id = builder.id;
@@ -771,6 +774,11 @@ private SubscriptionParams(SubscriptionBuilder builder) {
       this.invoiceNotes = builder.invoiceNotes;
 
       this.contractTermBillingCycleOnRenewal = builder.contractTermBillingCycleOnRenewal;
+
+      this.customFields =
+          builder.customFields.isEmpty()
+              ? Collections.emptyMap()
+              : Collections.unmodifiableMap(new LinkedHashMap<>(builder.customFields));
     }
 
     public String getId() {
@@ -809,6 +817,10 @@ public Integer getContractTermBillingCycleOnRenewal() {
       return contractTermBillingCycleOnRenewal;
     }
 
+    public Map<String, String> customFields() {
+      return customFields;
+    }
+
     /** Get the form data for this request. */
     public Map<String, Object> toFormData() {
       Map<String, Object> formData = new LinkedHashMap<>();
@@ -859,6 +871,8 @@ public Map<String, Object> toFormData() {
             "contract_term_billing_cycle_on_renewal", this.contractTermBillingCycleOnRenewal);
       }
 
+      formData.putAll(customFields);
+
       return formData;
     }
 
@@ -888,6 +902,8 @@ public static final class SubscriptionBuilder {
 
       private Integer contractTermBillingCycleOnRenewal;
 
+      private Map<String, String> customFields = new LinkedHashMap<>();
+
       private SubscriptionBuilder() {}
 
       public SubscriptionBuilder id(String value) {
@@ -937,6 +953,42 @@ public SubscriptionBuilder contractTermBillingCycleOnRenewal(Integer value) {
         return this;
       }
 
+      /**
+       * Add a custom field to the request. Custom fields must start with "cf_".
+       *
+       * @param fieldName the name of the custom field (e.g., "cf_custom_field_name")
+       * @param value the value of the custom field
+       * @return this builder
+       * @throws IllegalArgumentException if fieldName doesn't start with "cf_"
+       */
+      public SubscriptionBuilder customField(String fieldName, String value) {
+        if (fieldName == null || !fieldName.startsWith("cf_")) {
+          throw new IllegalArgumentException("Custom field name must start with 'cf_'");
+        }
+        this.customFields.put(fieldName, value);
+        return this;
+      }
+
+      /**
+       * Add multiple custom fields to the request. All field names must start with "cf_".
+       *
+       * @param customFields map of custom field names to values
+       * @return this builder
+       * @throws IllegalArgumentException if any field name doesn't start with "cf_"
+       */
+      public SubscriptionBuilder customFields(Map<String, String> customFields) {
+        if (customFields != null) {
+          for (Map.Entry<String, String> entry : customFields.entrySet()) {
+            if (entry.getKey() == null || !entry.getKey().startsWith("cf_")) {
+              throw new IllegalArgumentException(
+                  "Custom field name must start with 'cf_': " + entry.getKey());
+            }
+            this.customFields.put(entry.getKey(), entry.getValue());
+          }
+        }
+        return this;
+      }
+
       public SubscriptionParams build() {
         return new SubscriptionParams(this);
       }
@@ -1035,6 +1087,8 @@ public static final class CustomerParams {
 
     private final String entityIdentifierStandard;
 
+    private final Map<String, String> customFields;
+
     private CustomerParams(CustomerBuilder builder) {
 
       this.vatNumber = builder.vatNumber;
@@ -1046,6 +1100,11 @@ private CustomerParams(CustomerBuilder builder) {
       this.entityIdentifierScheme = builder.entityIdentifierScheme;
 
       this.entityIdentifierStandard = builder.entityIdentifierStandard;
+
+      this.customFields =
+          builder.customFields.isEmpty()
+              ? Collections.emptyMap()
+              : Collections.unmodifiableMap(new LinkedHashMap<>(builder.customFields));
     }
 
     public String getVatNumber() {
@@ -1068,6 +1127,10 @@ public String getEntityIdentifierStandard() {
       return entityIdentifierStandard;
     }
 
+    public Map<String, String> customFields() {
+      return customFields;
+    }
+
     /** Get the form data for this request. */
     public Map<String, Object> toFormData() {
       Map<String, Object> formData = new LinkedHashMap<>();
@@ -1097,6 +1160,8 @@ public Map<String, Object> toFormData() {
         formData.put("entity_identifier_standard", this.entityIdentifierStandard);
       }
 
+      formData.putAll(customFields);
+
       return formData;
     }
 
@@ -1118,6 +1183,8 @@ public static final class CustomerBuilder {
 
       private String entityIdentifierStandard;
 
+      private Map<String, String> customFields = new LinkedHashMap<>();
+
       private CustomerBuilder() {}
 
       public CustomerBuilder vatNumber(String value) {
@@ -1145,6 +1212,42 @@ public CustomerBuilder entityIdentifierStandard(String value) {
         return this;
       }
 
+      /**
+       * Add a custom field to the request. Custom fields must start with "cf_".
+       *
+       * @param fieldName the name of the custom field (e.g., "cf_custom_field_name")
+       * @param value the value of the custom field
+       * @return this builder
+       * @throws IllegalArgumentException if fieldName doesn't start with "cf_"
+       */
+      public CustomerBuilder customField(String fieldName, String value) {
+        if (fieldName == null || !fieldName.startsWith("cf_")) {
+          throw new IllegalArgumentException("Custom field name must start with 'cf_'");
+        }
+        this.customFields.put(fieldName, value);
+        return this;
+      }
+
+      /**
+       * Add multiple custom fields to the request. All field names must start with "cf_".
+       *
+       * @param customFields map of custom field names to values
+       * @return this builder
+       * @throws IllegalArgumentException if any field name doesn't start with "cf_"
+       */
+      public CustomerBuilder customFields(Map<String, String> customFields) {
+        if (customFields != null) {
+          for (Map.Entry<String, String> entry : customFields.entrySet()) {
+            if (entry.getKey() == null || !entry.getKey().startsWith("cf_")) {
+              throw new IllegalArgumentException(
+                  "Custom field name must start with 'cf_': " + entry.getKey());
+            }
+            this.customFields.put(entry.getKey(), entry.getValue());
+          }
+        }
+        return this;
+      }
+
       public CustomerParams build() {
         return new CustomerParams(this);
       }