---
title: "Create a shipment custom field"
method: POST
path: "/shipments/{shipment_id}/custom_fields"
tags: ["Shipments"]
---

# Create a shipment custom field

`POST /shipments/{shipment_id}/custom_fields`

## Request body

- object
  - `data` object
    - `type` 'custom_field', required
    - `attributes` object, required
      - `api_slug` string, required
      - `value` union, required — Raw custom field value (type depends on definition)
        - string
        - number
        - boolean
        - string[]
        - object

## Response `201`

Created

- object
  - `data` CustomField
    - `id` string, uuid, required
    - `type` 'custom_field', required
    - `attributes` object
      - `api_slug` string, required
      - `value` union — Raw custom field value (type depends on definition)
        - string
        - number
        - boolean
        - string[]
        - object
      - `display_value` string, nullable — Formatted value for display
    - `relationships` object
      - `entity` object
        - `data` object
          - `type` 'shipment' | 'container' | 'tracking_request', required
          - `id` string, uuid, required
      - `definition` object
        - `data` object
          - `type` 'custom_field_definition', required
          - `id` string, uuid, required
  - `links` LinkSelf
    - `self` string, uri

## Changes

- **2026-03-30** `ba531dc63989` — 1 warning
  - added the new `tracking_request` enum value to the `data/relationships/entity/data/type` response property for the response status `201`
- **2026-02-26** `c5b7c05cda4c` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/terminal49/apis/terminal49-api-reference/changes/shipments/:shipment_id/custom_fields/post.md)

---

[API](https://skmtc.dev/terminal49/apis/terminal49-api-reference.md) · [All operations](https://skmtc.dev/terminal49/apis/terminal49-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/terminal49/terminal49-api-reference/revisions/998a27e39c03/schema)