From fac3d5b1bf707dbb466742f0400147b984214272 Mon Sep 17 00:00:00 2001 From: Sinan Keskin Date: Wed, 8 Jul 2026 21:51:03 +0300 Subject: [PATCH] Add sample custom fields json payloads --- .../create-container-custom-field.mdx | 51 ++++++++++++++- .../custom-fields/create-a-custom-field.mdx | 62 +++++++++++++++++-- .../create-shipment-custom-field.mdx | 51 ++++++++++++++- .../create-tracking-request-custom-field.mdx | 51 ++++++++++++++- 4 files changed, 205 insertions(+), 10 deletions(-) diff --git a/docs/api-docs/api-reference/containers/create-container-custom-field.mdx b/docs/api-docs/api-reference/containers/create-container-custom-field.mdx index 64686103..ef659e5c 100644 --- a/docs/api-docs/api-reference/containers/create-container-custom-field.mdx +++ b/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" + } + } + } + } +} +``` diff --git a/docs/api-docs/api-reference/custom-fields/create-a-custom-field.mdx b/docs/api-docs/api-reference/custom-fields/create-a-custom-field.mdx index d508c439..88e8c659 100644 --- a/docs/api-docs/api-reference/custom-fields/create-a-custom-field.mdx +++ b/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" + } + } + } + } +} +``` diff --git a/docs/api-docs/api-reference/shipments/create-shipment-custom-field.mdx b/docs/api-docs/api-reference/shipments/create-shipment-custom-field.mdx index 7abe3b6d..5a6ea926 100644 --- a/docs/api-docs/api-reference/shipments/create-shipment-custom-field.mdx +++ b/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" + } + } + } + } +} +``` diff --git a/docs/api-docs/api-reference/tracking-requests/create-tracking-request-custom-field.mdx b/docs/api-docs/api-reference/tracking-requests/create-tracking-request-custom-field.mdx index d0d82d6e..fc4b0394 100644 --- a/docs/api-docs/api-reference/tracking-requests/create-tracking-request-custom-field.mdx +++ b/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" + } + } + } + } +} +```