[CHORE] add sample custom fields json payloads

docs/api-docs/api-reference/containers/create-container-custom-field.mdx

@@ -18,8 +18,11 @@ Creates or updates a custom field on a container. If a custom field with the spe
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
-| `api_slug` | Yes | The slug of the custom field definition |
-| `value` | Yes | The value to set (type depends on the definition's data type) |
+| `data.type` | Yes | Must be `custom_field` |
+| `data.attributes.api_slug` | Yes | The slug of the custom field definition |
+| `data.attributes.value` | Yes | The value to set (type depends on the definition's data type) |
+
+The container is implied by the path, so do not send `data.relationships.entity` on this endpoint.
 
 ## Authorization
 
@@ -34,3 +37,47 @@ Returns `201 Created` with the custom field resource on success.
 - Uses `find_or_initialize_by` internally, so it creates if missing or updates if it exists
 - Values are validated against the definition's data type
 - For enum fields, values are validated against the definition's options
+
+## Example request
+
+```json
+{
+  "data": {
+    "type": "custom_field",
+    "attributes": {
+      "api_slug": "customer_reference_number",
+      "value": "ABC124"
+    }
+  }
+}
+```
+
+## Example response
+
+```json
+{
+  "data": {
+    "id": "YOUR_CUSTOM_FIELD_ID",
+    "type": "custom_field",
+    "attributes": {
+      "api_slug": "customer_reference_number",
+      "value": "ABC124",
+      "display_value": "ABC124"
+    },
+    "relationships": {
+      "entity": {
+        "data": {
+          "id": "YOUR_CONTAINER_ID",
+          "type": "container"
+        }
+      },
+      "definition": {
+        "data": {
+          "id": "YOUR_DEFINITION_ID",
+          "type": "custom_field_definition"
+        }
+      }
+    }
+  }
+}
+```

docs/api-docs/api-reference/custom-fields/create-a-custom-field.mdx

@@ -6,15 +6,17 @@ og:description: Create a custom field value on a shipment or container using the
 openapi: post /custom_fields
 ---
 
-Use this endpoint to create a custom field value on a shipment or container. The field must reference an existing custom field definition.
+Use this endpoint to create a custom field value on a shipment or container when you need to send the full JSON:API relationship payload yourself. The field must reference an existing custom field definition.
 
 ## Request body
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
-| `entity` | Yes | Polymorphic relationship to a Shipment or Container |
-| `api_slug` | Yes | The slug of the custom field definition |
-| `value` | Yes | The field value (must match the definition's data type) |
+| `data.type` | Yes | Must be `custom_field` |
+| `data.attributes.api_slug` | Yes | The slug of the custom field definition |
+| `data.attributes.value` | Yes | The field value (must match the definition's data type) |
+| `data.relationships.entity.data.type` | Yes | `shipment` or `container` |
+| `data.relationships.entity.data.id` | Yes | The shipment or container ID |
 
 ## Value formats by data type
 
@@ -35,3 +37,55 @@ Use this endpoint to create a custom field value on a shipment or container. The
 - Enum values must match one of the definition's configured options
 - Reference values must match the definition's configured `reference_type`
 - The `api_slug` must reference a definition belonging to your account or a Terminal49 template
+
+## Example request
+
+```json
+{
+  "data": {
+    "type": "custom_field",
+    "attributes": {
+      "api_slug": "customer_reference_number",
+      "value": "ABC124"
+    },
+    "relationships": {
+      "entity": {
+        "data": {
+          "type": "shipment",
+          "id": "YOUR_SHIPMENT_ID"
+        }
+      }
+    }
+  }
+}
+```
+
+## Example response
+
+```json
+{
+  "data": {
+    "id": "YOUR_CUSTOM_FIELD_ID",
+    "type": "custom_field",
+    "attributes": {
+      "api_slug": "customer_reference_number",
+      "value": "ABC124",
+      "display_value": "ABC124"
+    },
+    "relationships": {
+      "entity": {
+        "data": {
+          "id": "YOUR_SHIPMENT_ID",
+          "type": "shipment"
+        }
+      },
+      "definition": {
+        "data": {
+          "id": "YOUR_DEFINITION_ID",
+          "type": "custom_field_definition"
+        }
+      }
+    }
+  }
+}
+```

docs/api-docs/api-reference/shipments/create-shipment-custom-field.mdx

@@ -18,8 +18,11 @@ Creates or updates a custom field on a shipment. If a custom field with the spec
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
-| `api_slug` | Yes | The slug of the custom field definition |
-| `value` | Yes | The value to set (type depends on the definition's data type) |
+| `data.type` | Yes | Must be `custom_field` |
+| `data.attributes.api_slug` | Yes | The slug of the custom field definition |
+| `data.attributes.value` | Yes | The value to set (type depends on the definition's data type) |
+
+The shipment is implied by the path, so do not send `data.relationships.entity` on this endpoint.
 
 ## Authorization
 
@@ -34,3 +37,47 @@ Returns `201 Created` with the custom field resource on success.
 - Uses `find_or_initialize_by` internally, so it creates if missing or updates if it exists
 - Values are validated against the definition's data type
 - For enum fields, values are validated against the definition's options
+
+## Example request
+
+```json
+{
+  "data": {
+    "type": "custom_field",
+    "attributes": {
+      "api_slug": "customer_reference_number",
+      "value": "ABC124"
+    }
+  }
+}
+```
+
+## Example response
+
+```json
+{
+  "data": {
+    "id": "YOUR_CUSTOM_FIELD_ID",
+    "type": "custom_field",
+    "attributes": {
+      "api_slug": "customer_reference_number",
+      "value": "ABC124",
+      "display_value": "ABC124"
+    },
+    "relationships": {
+      "entity": {
+        "data": {
+          "id": "YOUR_SHIPMENT_ID",
+          "type": "shipment"
+        }
+      },
+      "definition": {
+        "data": {
+          "id": "YOUR_DEFINITION_ID",
+          "type": "custom_field_definition"
+        }
+      }
+    }
+  }
+}
+```

docs/api-docs/api-reference/tracking-requests/create-tracking-request-custom-field.mdx

@@ -18,8 +18,11 @@ Creates or updates a custom field on a tracking request. If a custom field with
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
-| `api_slug` | Yes | The slug of the custom field definition |
-| `value` | Yes | The value to set (type depends on the definition's data type) |
+| `data.type` | Yes | Must be `custom_field` |
+| `data.attributes.api_slug` | Yes | The slug of the custom field definition |
+| `data.attributes.value` | Yes | The value to set (type depends on the definition's data type) |
+
+The tracking request is implied by the path, so do not send `data.relationships.entity` on this endpoint.
 
 ## Authorization
 
@@ -34,3 +37,47 @@ Returns `201 Created` with the custom field resource on success.
 - Uses `find_or_initialize_by` internally, so it creates if missing or updates if it exists
 - Values are validated against the definition's data type
 - For enum fields, values are validated against the definition's options
+
+## Example request
+
+```json
+{
+  "data": {
+    "type": "custom_field",
+    "attributes": {
+      "api_slug": "customer_reference_number",
+      "value": "ABC124"
+    }
+  }
+}
+```
+
+## Example response
+
+```json
+{
+  "data": {
+    "id": "YOUR_CUSTOM_FIELD_ID",
+    "type": "custom_field",
+    "attributes": {
+      "api_slug": "customer_reference_number",
+      "value": "ABC124",
+      "display_value": "ABC124"
+    },
+    "relationships": {
+      "entity": {
+        "data": {
+          "id": "YOUR_TRACKING_REQUEST_ID",
+          "type": "tracking_request"
+        }
+      },
+      "definition": {
+        "data": {
+          "id": "YOUR_DEFINITION_ID",
+          "type": "custom_field_definition"
+        }
+      }
+    }
+  }
+}
+```