From b9c2fdf00be3c0438594fc480d0ea7dc4e64769c Mon Sep 17 00:00:00 2001
From: Nick Schimek <19519317+NickSchimek@users.noreply.github.com>
Date: Fri, 13 Mar 2026 20:06:28 +0900
Subject: [PATCH] Add metadata field to client endpoints

Document the new metadata JSONB field on client API endpoints.
The metadata field allows integration partners to store custom
key-value data (e.g. external system IDs) on client records.

Added to GET response examples, Create, and Update parameter
tables with a note that updates replace the entire object.
---
 source/includes/customers/_clients.md | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/source/includes/customers/_clients.md b/source/includes/customers/_clients.md
index d88e0f9..ba58eae 100644
--- a/source/includes/customers/_clients.md
+++ b/source/includes/customers/_clients.md
@@ -32,6 +32,9 @@
     "external_ids": {
       "acumatica_id": "5"
     },
+    "metadata": {
+      "crm_id": "ABC123"
+    },
     "parent_id": 2345,
     "contacts": [
       {
@@ -73,6 +76,7 @@
         "zipcode": "32312",
         "country": "US",
         "external_ids": null,
+        "metadata": {},
       },
       {
         ...
@@ -132,7 +136,8 @@ ID | The ID of the client to retrieve
       "state": "CA",
       "zipcode": "92626",
       "country": "US",
-      "parent_id": 456
+      "parent_id": 456,
+      "metadata": { "crm_id": "ABC123" }
     }
 %>
 <%= shell_example('/clients', command: 'POST', data: data) %>
@@ -162,6 +167,7 @@ website | A website for the client <small>string</small>
 phone | A phone number for the client <small>string</small>
 description | A description for the client <small>string</small>
 parent_id | The parent of the client <small>string</small>
+metadata | A JSON object for storing custom key-value data (e.g. external system IDs) <small>object</small>
 
 ## Update a client
 <%
@@ -175,7 +181,8 @@ parent_id | The parent of the client <small>string</small>
       "state": "CA",
       "zipcode": "92626",
       "country": "US",
-      "parent_id": 456
+      "parent_id": 456,
+      "metadata": { "crm_id": "ABC123" }
     }
 %>
 <%= shell_example('/clients/<ID>', command: 'PATCH', data: data) %>
@@ -206,6 +213,7 @@ website | A website for the client <small>string</small>
 phone | A phone number for the client <small>string</small>
 description | A description for the client <small>string</small>
 parent_id | The parent of the client <small>string</small>
+metadata | A JSON object for storing custom key-value data (e.g. external system IDs). Replaces the entire object on update. <small>object</small>
 
 ## Delete a client