Add Custom Fields API Reference Documentation

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

@@ -0,0 +1,34 @@
+---
+og:title: Create Container Custom Field | Terminal49 API Documentation
+og:description: Create or update a custom field on a container using Terminal49's API.
+openapi: post /containers/{container_id}/custom_fields
+---
+
+Creates or updates a custom field on a container. If a custom field with the specified `api_slug` already exists, it will be updated.
+
+## Path parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `container_id` | Yes | The ID of the container |
+
+## Request body
+
+| 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) |
+
+## Authorization
+
+Requires `update` permission on the container.
+
+## Response
+
+Returns `201 Created` with the custom field resource on success.
+
+## Behavior
+
+- 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

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

@@ -0,0 +1,22 @@
+---
+og:title: Delete Container Custom Field | Terminal49 API Documentation
+og:description: Delete a specific custom field from a container by its api_slug using Terminal49's API.
+openapi: delete /containers/{container_id}/custom_fields/{api_slug}
+---
+
+Deletes a specific custom field from a container by its `api_slug`.
+
+## Path parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `container_id` | Yes | The ID of the container |
+| `api_slug` | Yes | The api_slug of the custom field definition |
+
+## Authorization
+
+Requires `update` permission on the container.
+
+## Response
+
+Returns `204 No Content` on success.

docs/api-docs/api-reference/containers/list-container-custom-fields.mdx

@@ -0,0 +1,24 @@
+---
+og:title: List Container Custom Fields | Terminal49 API Documentation
+og:description: List all custom fields for a specific container using Terminal49's API.
+openapi: get /containers/{container_id}/custom_fields
+---
+
+Lists all custom fields attached to a specific container.
+
+## Path parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `container_id` | Yes | The ID of the container |
+
+## Authorization
+
+Requires `show` permission on the container.
+
+## Response
+
+Returns a JSONAPI array of custom field resources including:
+- `value` - The raw stored value
+- `display_value` - Formatted value for display
+- Relationships to the definition and user who last updated the field

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

@@ -0,0 +1,28 @@
+---
+og:title: Update Container Custom Field | Terminal49 API Documentation
+og:description: Update a specific custom field on a container by its api_slug using Terminal49's API.
+openapi: patch /containers/{container_id}/custom_fields/{api_slug}
+---
+
+Updates a specific custom field on a container by its `api_slug`.
+
+## Path parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `container_id` | Yes | The ID of the container |
+| `api_slug` | Yes | The api_slug of the custom field definition |
+
+## Request body
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `value` | Yes | The new value to set |
+
+## Authorization
+
+Requires `update` permission on the container.
+
+## Response
+
+Returns `200 OK` with the updated custom field resource on success.

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

@@ -0,0 +1,33 @@
+---
+og:title: Create a Custom Field | Terminal49 API Documentation
+og:description: Create a custom field value on a shipment or container using Terminal49's API.
+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.
+
+## 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) |
+
+## Value formats by data type
+
+| Data type | Expected value format |
+|-----------|----------------------|
+| `short_text` | Any string |
+| `number` | Numeric value |
+| `date` | Date string (parsed using definition's `default_format` or flexible parsing) |
+| `datetime` | DateTime string |
+| `boolean` | `true` or `false` |
+| `enum` | String matching one of the definition's option values |
+| `enum_multi` | Array of strings matching the definition's option values |
+
+## Validation
+
+- Values are validated against the definition's data type
+- Enum values must match one of the definition's configured options
+- The `api_slug` must reference a definition belonging to your account or a Terminal49 template

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

@@ -0,0 +1,18 @@
+---
+og:title: Delete a Custom Field | Terminal49 API Documentation
+og:description: Delete a custom field value using Terminal49's API.
+openapi: delete /custom_fields/{id}
+---
+
+Use this endpoint to delete a custom field value from a shipment or container.
+
+## Path parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `id` | The unique identifier of the custom field value to delete |
+
+## Behavior
+
+- The custom field value is removed from the associated entity
+- Deleting a custom field value does not affect the underlying custom field definition

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

@@ -0,0 +1,34 @@
+---
+og:title: Get a Custom Field | Terminal49 API Documentation
+og:description: Retrieve a single custom field by ID using Terminal49's API.
+openapi: get /custom_fields/{id}
+---
+
+Use this endpoint to retrieve a single custom field value by its ID.
+
+## Path parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `id` | The unique identifier of the custom field value |
+
+## Response
+
+The response includes:
+- `value` - The raw stored value (type depends on the field's data type)
+- `display_value` - Human-readable formatted value
+- Relationships to the associated entity (shipment or container), definition, and the user who last updated it
+
+## Data types
+
+Custom fields support these data types, each with specific value handling:
+
+| Data type | Storage | Display format |
+|-----------|---------|----------------|
+| `short_text` | String | As-is |
+| `number` | Decimal (precision: 18, scale: 6) | Formatted per `default_format` |
+| `date` | Date | `YYYY-MM-DD` or custom format |
+| `datetime` | DateTime | `YYYY-MM-DD HH:MM:SS` or custom format |
+| `boolean` | Boolean | `Yes` or `No` |
+| `enum` | String | Option label |
+| `enum_multi` | Comma-separated string | Comma-separated labels |

docs/api-docs/api-reference/custom-fields/list-custom-fields.mdx

@@ -0,0 +1,24 @@
+---
+og:title: List Custom Fields | Terminal49 API Documentation
+og:description: List custom fields with filters using Terminal49's API. Retrieve metadata attached to shipments and containers.
+openapi: get /custom_fields
+---
+
+Use this endpoint to retrieve custom field values attached to your shipments and containers. Custom fields let you store additional metadata on entities to support your business workflows.
+
+## Query filters
+
+Filter results using these query parameters:
+
+| Filter | Description |
+|--------|-------------|
+| `filter[entity_type]` | Filter by entity type (`Shipment` or `Cargo`) |
+| `filter[entity_id]` | Filter by the ID of the shipment or container |
+| `filter[definition_id]` | Filter by custom field definition ID |
+
+## Response
+
+The response includes:
+- `value` - The raw stored value
+- `display_value` - Formatted value for display (e.g., formatted numbers, date strings, enum labels)
+- Relationships to the entity, definition, and user who last updated the field

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

@@ -0,0 +1,26 @@
+---
+og:title: Update a Custom Field | Terminal49 API Documentation
+og:description: Update an existing custom field value using Terminal49's API.
+openapi: patch /custom_fields/{id}
+---
+
+Use this endpoint to update an existing custom field value.
+
+## Path parameters
+
+| Parameter | Description |
+|-----------|-------------|
+| `id` | The unique identifier of the custom field value to update |
+
+## Request body
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `value` | Yes | The new field value (must match the definition's data type) |
+
+## Behavior
+
+- The new value is validated against the field definition's data type
+- For enum fields, the value must match one of the definition's configured options
+- The `updated_by` user is recorded for audit purposes
+- Update pathway tracking records the source of the change

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

@@ -0,0 +1,34 @@
+---
+og:title: Create Shipment Custom Field | Terminal49 API Documentation
+og:description: Create or update a custom field on a shipment using Terminal49's API.
+openapi: post /shipments/{shipment_id}/custom_fields
+---
+
+Creates or updates a custom field on a shipment. If a custom field with the specified `api_slug` already exists, it will be updated.
+
+## Path parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `shipment_id` | Yes | The ID of the shipment |
+
+## Request body
+
+| 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) |
+
+## Authorization
+
+Requires `update` permission on the shipment.
+
+## Response
+
+Returns `201 Created` with the custom field resource on success.
+
+## Behavior
+
+- 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

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

@@ -0,0 +1,22 @@
+---
+og:title: Delete Shipment Custom Field | Terminal49 API Documentation
+og:description: Delete a specific custom field from a shipment by its api_slug using Terminal49's API.
+openapi: delete /shipments/{shipment_id}/custom_fields/{api_slug}
+---
+
+Deletes a specific custom field from a shipment by its `api_slug`.
+
+## Path parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `shipment_id` | Yes | The ID of the shipment |
+| `api_slug` | Yes | The api_slug of the custom field definition |
+
+## Authorization
+
+Requires `update` permission on the shipment.
+
+## Response
+
+Returns `204 No Content` on success.

docs/api-docs/api-reference/shipments/list-shipment-custom-fields.mdx

@@ -0,0 +1,24 @@
+---
+og:title: List Shipment Custom Fields | Terminal49 API Documentation
+og:description: List all custom fields for a specific shipment using Terminal49's API.
+openapi: get /shipments/{shipment_id}/custom_fields
+---
+
+Lists all custom fields attached to a specific shipment.
+
+## Path parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `shipment_id` | Yes | The ID of the shipment |
+
+## Authorization
+
+Requires `show` permission on the shipment.
+
+## Response
+
+Returns a JSONAPI array of custom field resources including:
+- `value` - The raw stored value
+- `display_value` - Formatted value for display
+- Relationships to the definition and user who last updated the field

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

@@ -0,0 +1,28 @@
+---
+og:title: Update Shipment Custom Field | Terminal49 API Documentation
+og:description: Update a specific custom field on a shipment by its api_slug using Terminal49's API.
+openapi: patch /shipments/{shipment_id}/custom_fields/{api_slug}
+---
+
+Updates a specific custom field on a shipment by its `api_slug`.
+
+## Path parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `shipment_id` | Yes | The ID of the shipment |
+| `api_slug` | Yes | The api_slug of the custom field definition |
+
+## Request body
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `value` | Yes | The new value to set |
+
+## Authorization
+
+Requires `update` permission on the shipment.
+
+## Response
+
+Returns `200 OK` with the updated custom field resource on success.

docs/mint.json

@@ -119,7 +119,11 @@
         "api-docs/api-reference/shipments/get-a-shipment",
         "api-docs/api-reference/shipments/edit-a-shipment",
         "api-docs/api-reference/shipments/stop-tracking-shipment",
-        "api-docs/api-reference/shipments/resume-tracking-shipment"
+        "api-docs/api-reference/shipments/resume-tracking-shipment",
+        "api-docs/api-reference/shipments/list-shipment-custom-fields",
+        "api-docs/api-reference/shipments/create-shipment-custom-field",
+        "api-docs/api-reference/shipments/update-shipment-custom-field",
+        "api-docs/api-reference/shipments/delete-shipment-custom-field"
       ]
     },
     {
@@ -159,7 +163,21 @@
         "api-docs/api-reference/containers/refresh-container",
         "api-docs/api-reference/containers/get-container-route",
         "api-docs/api-reference/containers/get-a-containers-raw-events",
-        "api-docs/api-reference/containers/get-a-containers-transport-events"
+        "api-docs/api-reference/containers/get-a-containers-transport-events",
+        "api-docs/api-reference/containers/list-container-custom-fields",
+        "api-docs/api-reference/containers/create-container-custom-field",
+        "api-docs/api-reference/containers/update-container-custom-field",
+        "api-docs/api-reference/containers/delete-container-custom-field"
+      ]
+    },
+    {
+      "group": "Custom Fields",
+      "pages": [
+        "api-docs/api-reference/custom-fields/list-custom-fields",
+        "api-docs/api-reference/custom-fields/get-a-custom-field",
+        "api-docs/api-reference/custom-fields/create-a-custom-field",
+        "api-docs/api-reference/custom-fields/update-a-custom-field",
+        "api-docs/api-reference/custom-fields/delete-a-custom-field"
       ]
     },
     {