> ## Documentation Index
> Fetch the complete documentation index at: https://terminal49-vorflux-dev-12120-supported-document-types.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create shipment custom field

> Create or update a custom field value on a shipment in the Terminal49 API. Attach internal metadata like PO numbers, customer codes, or workflow tags.

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                                                   |
| -------------------------- | -------- | ------------------------------------------------------------- |
| `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

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

## Example request

```json theme={null}
{
  "data": {
    "type": "custom_field",
    "attributes": {
      "api_slug": "customer_reference_number",
      "value": "ABC124"
    }
  }
}
```

## Example response

```json theme={null}
{
  "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"
        }
      }
    }
  }
}
```