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.

POST /shipments/{shipment_id}/custom_fields

Create a shipment custom field

cURL

curl --request POST \
  --url https://api.terminal49.com/v2/shipments/{shipment_id}/custom_fields \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "data": {
    "type": "custom_field",
    "attributes": {
      "api_slug": "customer_reference_number",
      "value": "ABC124"
    }
  }
}
'

201

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "type": "custom_field",
    "attributes": {
      "api_slug": "<string>",
      "value": "<string>",
      "display_value": "<string>"
    },
    "relationships": {
      "entity": {
        "data": {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        }
      },
      "definition": {
        "data": {
          "type": "custom_field_definition",
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        }
      }
    }
  },
  "links": {
    "self": "<string>"
  }
}

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

{
  "data": {
    "type": "custom_field",
    "attributes": {
      "api_slug": "customer_reference_number",
      "value": "ABC124"
    }
  }
}

Example response

{
  "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"
        }
      }
    }
  }
}

Authorizations

Authorization · string · header · required

Use a Terminal49 API key in the Authorization header with the Token prefix.

Authorization: Token YOUR_API_KEY

Path Parameters

shipment_id · string · required

Shipment ID

Body

application/json

data · object

Show child attributes

Response

201 - application/json

Created

data · Custom field · object

Show child attributes

links · link · object

Show child attributes