[CHORE] add sample custom fields json payloads

[sinankeskin]

Greptile Summary

This PR adds concrete JSON:API-shaped example request and response payloads to four custom-field documentation pages, and updates the request-body parameter tables to reflect the correct nested structure (data.type, data.attributes.*, data.relationships.*). It also adds a clarifying note on each path-based endpoint (shipments, containers, tracking requests) explaining that data.relationships.entity should be omitted because the entity is already implied by the URL.

• Four docs pages updated: create-a-custom-field, create-shipment-custom-field, create-container-custom-field, and create-tracking-request-custom-field — all now include matching example request/response blocks in valid JSON:API format.
• Generic vs. path-based distinction clarified: The generic /custom_fields page now explicitly notes it is for callers that need to send the full relationship payload, while the path-based pages note that the entity relationship must not be sent.

Confidence Score: 5/5

Pure documentation update — no code, migrations, or API behavior changed; safe to merge.

All four files are .mdx documentation pages. The example payloads are structurally correct JSON:API, the parameter tables accurately reflect the nested structure, and the entity-implied notes are consistent across the three path-based endpoints. No logic, schema, or runtime behavior is touched.

No files require special attention.

Important Files Changed

Filename	Overview
docs/api-docs/api-reference/custom-fields/create-a-custom-field.mdx	Updated request body params to JSON:API format and added example request/response payloads; also clarified this endpoint is for when a full relationship payload is needed.
docs/api-docs/api-reference/shipments/create-shipment-custom-field.mdx	Updated request body table to show JSON:API structure, added note that data.relationships.entity is not needed on this path-based endpoint, and added example payloads.
docs/api-docs/api-reference/containers/create-container-custom-field.mdx	Same pattern as shipment custom field: added JSON:API request body parameters, entity-implied note, and example payloads.
docs/api-docs/api-reference/tracking-requests/create-tracking-request-custom-field.mdx	Same pattern as the other entity-specific endpoints: added JSON:API request body table, path-implied entity note, and example payloads with correct tracking_request type in the response.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Client
    participant API as Terminal49 API

    Note over Client,API: Option A — Path-based (entity implied)
    Client->>API: "POST /shipments/{id}/custom_fields"
    API-->>Client: 201 Created — custom_field resource

    Client->>API: "POST /containers/{id}/custom_fields"
    API-->>Client: 201 Created — custom_field resource

    Client->>API: "POST /tracking_requests/{id}/custom_fields"
    API-->>Client: 201 Created — custom_field resource

    Note over Client,API: Option B — Generic endpoint (full relationship required)
    Client->>API: POST /custom_fields with relationships.entity
    API-->>Client: 201 Created — custom_field resource

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Client
    participant API as Terminal49 API

    Note over Client,API: Option A — Path-based (entity implied)
    Client->>API: "POST /shipments/{id}/custom_fields"
    API-->>Client: 201 Created — custom_field resource

    Client->>API: "POST /containers/{id}/custom_fields"
    API-->>Client: 201 Created — custom_field resource

    Client->>API: "POST /tracking_requests/{id}/custom_fields"
    API-->>Client: 201 Created — custom_field resource

    Note over Client,API: Option B — Generic endpoint (full relationship required)
    Client->>API: POST /custom_fields with relationships.entity
    API-->>Client: 201 Created — custom_field resource

Loading

_{Reviews (1): Last reviewed commit: "Add sample custom fields json payloads" | Re-trigger Greptile}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
api	Ready	Preview, Comment	Jul 8, 2026 6:52pm

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
terminal49	🟢 Ready	View Preview	Jul 8, 2026, 7:09 PM