Support overrides and historical values on customer, contact and attributes endpoints

README.md

@@ -134,6 +134,13 @@ chartmogul.DataSource.destroy(config, uuid='ds_5915ee5a-babd-406b-b8ce-d207133fb
 chartmogul.Customer.create(config, data={})
 chartmogul.Customer.all(config, cursor='cursor==', per_page=20)
 chartmogul.Customer.retrieve(config, uuid='cus_5915ee5a-babd-406b-b8ce-d207133fb4cb')
+chartmogul.Customer.retrieve(config, uuid='cus_5915ee5a-babd-406b-b8ce-d207133fb4cb',
+                             with_overrides=True, attributes_with_history='company,custom.channel')
+# with_overrides and attributes_with_history only work on retrieve; list and search endpoints ignore them
+# attributes_with_history is a comma-separated string of case-sensitive names;
+# custom attributes take the custom. prefix; unknown names return a 422
+# Overrides and history live at the top level of the customer (customer.overrides,
+# customer.historical_values); customer.attributes.overrides is never populated
 chartmogul.Customer.search(config, email='email@email.com')
 chartmogul.Customer.merge(config, data={
   'from': {'customer_uuid': 'cus_5915ee5a-babd-406b-b8ce-d207133fb4cb'},
@@ -150,6 +157,20 @@ chartmogul.Customer.modify(config, uuid='cus_5915ee5a-babd-406b-b8ce-d207133fb4c
   "country": "US",
   "state": "CA",
 })
+chartmogul.Customer.modify(config, uuid='cus_5915ee5a-babd-406b-b8ce-d207133fb4cb', data={
+  "company": "Pinata Technologies",
+  "overrides": {
+    "company": True,
+    "address": True,
+    "attributes": {"custom": {"channel": True}}
+  }
+})
+# An overrides flag set to True protects the value written by the request from
+# later updates; False removes an existing override and restores the field's
+# most recent value from edit history. API writes to an overridden field are
+# reverted unless the request carries a flag for that field. All write calls accept an overrides entry in data:
+# Customer and Contact create/modify, Customer.createContact, and
+# CustomAttributes add/update/remove (including add by email).
 chartmogul.Customer.destroy(config, uuid='cus_5915ee5a-babd-406b-b8ce-d207133fb4cb')
 chartmogul.Customer.subscriptions(config, uuid='cus_5915ee5a-babd-406b-b8ce-d207133fb4cb')
 chartmogul.Customer.connectSubscriptions(config, uuid='cus_5915ee5a-babd-406b-b8ce-d207133fb4cb', data={
@@ -196,11 +217,18 @@ chartmogul.Customer.createTask(config, uuid='cus_5915ee5a-babd-406b-b8ce-d207133
 chartmogul.Contact.create(config, data={})
 chartmogul.Contact.all(config, cursor='aabbcc', per_page=20, customer_uuid='cus_5915ee5a-babd-406b-b8ce-d207133fb4cb', data_source_uuid='ds_fef05d54-47b4-431b-aed2-eb6b9e545430', email='test@example.com', customer_external_id='cus_0001', external_id='con_0001')
 chartmogul.Contact.retrieve(config, uuid='con_5915ee5a-babd-406b-b8ce-d207133fb4cb')
+chartmogul.Contact.retrieve(config, uuid='con_5915ee5a-babd-406b-b8ce-d207133fb4cb',
+                            with_overrides=True, attributes_with_history='title,email')
+# with_overrides and attributes_with_history only work on retrieve; list endpoints ignore them
 chartmogul.Contact.merge(config, into_uuid='con_5915ee5a-babd-406b-b8ce-d207133fb4cb', from_uuid='con_2123290f-09c8-4628-a205-db5596bd58f7')
 chartmogul.Contact.modify(config, uuid='con_5915ee5a-babd-406b-b8ce-d207133fb4cb', data={
   "email": "test@example.com",
   "last_seen": "2025-04-01T12:00:00Z"
 })
+chartmogul.Contact.modify(config, uuid='con_5915ee5a-babd-406b-b8ce-d207133fb4cb', data={
+  "title": "CTO",
+  "overrides": {"title": True}
+})
 chartmogul.Contact.destroy(config, uuid='con_5915ee5a-babd-406b-b8ce-d207133fb4cb')
 chartmogul.Contact.tasks(config, uuid='con_5915ee5a-babd-406b-b8ce-d207133fb4cb', cursor='aabbcc', per_page=20)
 chartmogul.Contact.createTask(config, uuid='con_5915ee5a-babd-406b-b8ce-d207133fb4cb', data={})
@@ -290,10 +318,14 @@ Date filters take ISO 8601 strings. `Task.patch` returns `None` when the API rep
 
 #### [Customer Attributes](https://dev.chartmogul.com/reference/customers/attributes/)
 
-Note that the returned attributes of type date are not parsed and stay in string.
+Note that the returned attributes of type date are not parsed and stay in string. The same applies inside `historical_values` entries: `update_performed_at` stays an ISO 8601 string.
 
 ```python
 chartmogul.Attributes.retrieve(config, uuid='cus_5915ee5a-babd-406b-b8ce-d207133fb4cb')
+chartmogul.Attributes.retrieve(config, uuid='cus_5915ee5a-babd-406b-b8ce-d207133fb4cb',
+                               with_overrides=True, attributes_with_history='custom.channel')
+# attributes_with_history accepts custom attributes only on this endpoint;
+# standard field names like 'company' return a 422
 ```
 
 #### [Tags](https://dev.chartmogul.com/reference/customers/tags/)
@@ -325,6 +357,15 @@ chartmogul.CustomAttributes.add(config, data={
     {'type': 'Integer', 'key': 'age', 'value': 8}
   ]
 })
+chartmogul.CustomAttributes.add(config, uuid='cus_5915ee5a-babd-406b-b8ce-d207133fb4cb', data={
+  'custom': [
+    {'type': 'String', 'key': 'channel', 'value': 'Facebook'}
+  ],
+  'overrides': {'custom': {'channel': True}}
+})
+# Note the overrides shape here is {'custom': {...}} — on Customer create/modify
+# and in Customer.retrieve responses the same flags nest under 'attributes':
+# {'attributes': {'custom': {...}}}
 chartmogul.CustomAttributes.update(config, uuid='cus_5915ee5a-babd-406b-b8ce-d207133fb4cb', data={
   'custom': {
     'age': 20,
@@ -334,6 +375,12 @@ chartmogul.CustomAttributes.update(config, uuid='cus_5915ee5a-babd-406b-b8ce-d20
 chartmogul.CustomAttributes.remove(config, uuid='cus_5915ee5a-babd-406b-b8ce-d207133fb4cb', data={
   'custom': ['CAC']
 })
+chartmogul.CustomAttributes.remove(config, uuid='cus_5915ee5a-babd-406b-b8ce-d207133fb4cb', data={
+  'custom': ['CAC'],
+  'overrides': {'custom': {'CAC': False}}
+})
+# remove keeps overridden attributes unless the request carries a False flag
+# for them; the response message names the ones kept.
 ```
 
 #### [Plans](https://dev.chartmogul.com/reference/plans/)

chartmogul/api/attributes.py

@@ -8,12 +8,17 @@ class Attributes(Resource):
     """
 
     _path = "/customers{/uuid}/attributes"
+    _bool_query_params = ["with_overrides"]
 
     class _Schema(Schema):
         tags = fields.List(fields.String())
         stripe = fields.Dict()
         clearbit = fields.Dict()
         custom = fields.Dict()
+        # load_default=None ensures these attributes are always present; the API
+        # omits the keys unless with_overrides / attributes_with_history is passed
+        overrides = fields.Dict(load_default=None)
+        historical_values = fields.Dict(load_default=None)
 
         @post_load
         def make(self, data, **kwargs):

chartmogul/api/contact.py

@@ -12,6 +12,7 @@ class Contact(Resource):
 
     _path = "/contacts{/uuid}"
     _root_key = "entries"
+    _bool_query_params = ["with_overrides"]
     _many = namedtuple("Contacts", [_root_key, "has_more", "cursor"])
 
     class _Schema(Schema):
@@ -33,6 +34,11 @@ class _Schema(Schema):
         external_id = fields.String(allow_none=True, load_default=None)
         last_seen = fields.DateTime(allow_none=True)
         custom = fields.Dict(allow_none=True)
+        # load_default=None ensures these attributes are always present; on
+        # retrieve the API omits the keys unless with_overrides /
+        # attributes_with_history is passed
+        overrides = fields.Dict(load_default=None)
+        historical_values = fields.Dict(load_default=None)
 
         @post_load
         def make(self, data, **kwargs):

chartmogul/api/custom_attrs.py

@@ -12,7 +12,12 @@ class CustomAttributes(Resource):
     _path = "/customers{/uuid}/attributes/custom"
 
     class _Schema(Schema):
-        custom = fields.Dict()
+        # load_default=None ensures these attributes are always present; the API
+        # omits custom when a DELETE removes the last custom attribute, and
+        # returns message only on DELETE responses
+        custom = fields.Dict(load_default=None)
+        overrides = fields.Dict(load_default=None)
+        message = fields.String(load_default=None)
 
         @post_load
         def make(self, data, **kwargs):

chartmogul/api/customer.py

@@ -36,6 +36,7 @@ class Customer(Resource):
 
     _path = "/customers{/uuid}"
     _root_key = "entries"
+    _bool_query_params = ["with_overrides"]
     _many = namedtuple("Customers", [_root_key, "has_more", "cursor"], defaults=[None, None])
 
     class _Schema(Schema):
@@ -71,6 +72,11 @@ class _Schema(Schema):
         currency_sign = fields.String(data_key="currency-sign")
         address = fields.Nested(Address._Schema, allow_none=True, unknown=EXCLUDE)
         website_url = fields.String(allow_none=True)
+        # load_default=None ensures these attributes are always present; on
+        # retrieve the API omits the keys unless with_overrides /
+        # attributes_with_history is passed
+        overrides = fields.Dict(load_default=None)
+        historical_values = fields.Dict(load_default=None)
 
         @post_load
         def make(self, data, **kwargs):

test/api/test_attributes.py

@@ -0,0 +1,72 @@
+import unittest
+from chartmogul import Attributes, Config
+import requests_mock
+
+attributesResponse = {
+    "tags": ["engage", "unit loss"],
+    "stripe": {"uid": 7, "coupon": True},
+    "custom": {"CAC": 213, "salesRep": "Gabi"},
+    "overrides": {"custom": {"salesRep": True}},
+    "historical_values": {
+        "custom": {
+            "salesRep": [
+                {
+                    "value": "Gabi",
+                    "update_performed_at": "2026-01-01T16:58:58Z",
+                    "update_performed_by": "API",
+                    "initial": False,
+                }
+            ]
+        }
+    },
+}
+
+
+class AttributesTestCase(unittest.TestCase):
+    @requests_mock.mock()
+    def test_retrieve(self, mock_requests):
+        plainResponse = {key: attributesResponse[key] for key in ("tags", "stripe", "custom")}
+        mock_requests.register_uri(
+            "GET",
+            "https://api.chartmogul.com/v1/customers/CUSTOMER_UUID/attributes",
+            status_code=200,
+            json=plainResponse,
+        )
+
+        config = Config("token")
+        result = Attributes.retrieve(config, uuid="CUSTOMER_UUID").get()
+
+        self.assertEqual(mock_requests.call_count, 1, "expected call")
+        self.assertEqual(mock_requests.last_request.qs, {})
+        self.assertTrue(isinstance(result, Attributes))
+        self.assertEqual(result.custom, attributesResponse["custom"])
+        self.assertIsNone(result.overrides)
+        self.assertIsNone(result.historical_values)
+
+    # case_sensitive asserts that the SDK preserves attribute name casing in the query
+    @requests_mock.Mocker(case_sensitive=True)
+    def test_retrieve_with_overrides_and_history(self, mock_requests):
+        mock_requests.register_uri(
+            "GET",
+            "https://api.chartmogul.com/v1/customers/CUSTOMER_UUID/attributes",
+            status_code=200,
+            json=attributesResponse,
+        )
+
+        config = Config("token")
+        result = Attributes.retrieve(
+            config,
+            uuid="CUSTOMER_UUID",
+            with_overrides=True,
+            attributes_with_history="custom.salesRep",
+        ).get()
+
+        self.assertEqual(mock_requests.call_count, 1, "expected call")
+        self.assertEqual(
+            mock_requests.last_request.qs,
+            {"with_overrides": ["true"], "attributes_with_history": ["custom.salesRep"]},
+        )
+        self.assertTrue(isinstance(result, Attributes))
+        self.assertEqual(result.custom, attributesResponse["custom"])
+        self.assertEqual(result.overrides, attributesResponse["overrides"])
+        self.assertEqual(result.historical_values, attributesResponse["historical_values"])

test/api/test_contact.py

@@ -314,6 +314,8 @@ def test_retrieve(self, mock_requests):
         self.assertTrue(isinstance(expected, Contact))
         self.assertEqual(expected.email, "test@example.com")
         self.assertTrue(isinstance(expected.last_seen, datetime))
+        self.assertIsNone(expected.overrides)
+        self.assertIsNone(expected.historical_values)
 
     @requests_mock.mock()
     def test_tasks(self, mock_requests):
@@ -474,3 +476,77 @@ def test_destroy(self, mock_requests):
         self.assertEqual(mock_requests.call_count, 1, "expected call")
         self.assertEqual(mock_requests.last_request.qs, {})
         self.assertTrue(expected, {})
+
+    @requests_mock.mock()
+    def test_retrieve_with_overrides_and_history(self, mock_requests):
+        overrides = {"title": True}
+        historical_values = {
+            "title": [
+                {
+                    "value": "CEO",
+                    "update_performed_at": "2026-01-01T16:58:58Z",
+                    "update_performed_by": "API",
+                    "initial": False,
+                }
+            ]
+        }
+        mock_requests.register_uri(
+            "GET",
+            "https://api.chartmogul.com/v1/contacts/con_00000000-0000-0000-0000-000000000000",
+            status_code=200,
+            json={**contact, "overrides": overrides, "historical_values": historical_values},
+        )
+
+        config = Config("token")
+        result = Contact.retrieve(
+            config,
+            uuid="con_00000000-0000-0000-0000-000000000000",
+            with_overrides=True,
+            attributes_with_history="title",
+        ).get()
+
+        self.assertEqual(mock_requests.call_count, 1, "expected call")
+        self.assertEqual(
+            mock_requests.last_request.qs,
+            {"with_overrides": ["true"], "attributes_with_history": ["title"]},
+        )
+        self.assertEqual(result.overrides, overrides)
+        self.assertEqual(result.historical_values, historical_values)
+
+    @requests_mock.mock()
+    def test_modify_with_overrides(self, mock_requests):
+        overrides = {"title": True}
+        mock_requests.register_uri(
+            "PATCH",
+            "https://api.chartmogul.com/v1/contacts/con_00000000-0000-0000-0000-000000000000",
+            status_code=200,
+            json={**contact, "overrides": overrides},
+        )
+
+        jsonRequest = {"title": "CTO", "overrides": overrides}
+        config = Config("token")
+        result = Contact.modify(
+            config, uuid="con_00000000-0000-0000-0000-000000000000", data=jsonRequest
+        ).get()
+
+        self.assertEqual(mock_requests.call_count, 1, "expected call")
+        self.assertEqual(mock_requests.last_request.json(), jsonRequest)
+        self.assertEqual(result.overrides, overrides)
+
+    @requests_mock.mock()
+    def test_create_with_overrides(self, mock_requests):
+        overrides = {"title": True}
+        mock_requests.register_uri(
+            "POST",
+            "https://api.chartmogul.com/v1/contacts",
+            status_code=201,
+            json={**contact, "overrides": overrides},
+        )
+
+        jsonRequest = {**createContact, "overrides": overrides}
+        config = Config("token")
+        result = Contact.create(config, data=jsonRequest).get()
+
+        self.assertEqual(mock_requests.call_count, 1, "expected call")
+        self.assertEqual(mock_requests.last_request.json(), jsonRequest)
+        self.assertEqual(result.overrides, overrides)