The Sub-Items field allows you to model one-to-many relationships by nesting related records under a parent record. While this approach has been useful in the past, Sub-Items are now being deprecated in favor of a more flexible and scalable data model based on Linked Records.

Existing Sub-Items fields will continue to work, but they are being automatically upgraded to Linked Records as part of an ongoing platform evolution.

Important Notice: Sub-Items Are Being Deprecated

SmartSuite is upgrading how Sub-Items work to provide a more consistent, scalable, and future-ready experience.

New Sub-Items fields are no longer recommended for new builds
Existing Sub-Items fields will be automatically converted to Linked Records
No data loss or manual action is required for existing solutions

For any new solutions or designs, we strongly recommend using Linked Records instead of Sub-Items.

What’s Changing

Sub-Items Will Become Linked Records

Each existing Sub-Items field in your solution will be converted into:

A dedicated table created automatically by SmartSuite
A Linked Record field connecting the parent table to the new table
A bi-directional relationship, allowing navigation from parent to child and back again

Records that previously appeared as Sub-Items will now exist as standard records in the new table and will be linked to their parent records.

Your Data Will Stay Intact

All existing Sub-Items data is preserved during this upgrade:

All records and field values remain unchanged
Metadata such as Created Date and Last Updated are preserved
No records are deleted or modified during migration

This upgrade changes how the data is modeled, not what data you have.

Legacy Sub-Items Fields Will Be Hidden

After migration:

Legacy Sub-Items fields will no longer appear in the UI or API
You will interact only with the new Linked Records–based structure
Workflows, automations, and relationships will continue to function, now backed by a more flexible relational model

What You’ll See in SmartSuite

After your Sub-Items fields are upgraded:

A new table will appear for each former Sub-Items field
Linked Record fields will connect parent records to their related records
Related data will appear in standard table and grid views, just like other Linked Records

This provides a cleaner, more consistent experience across your solution.

Why Linked Records Are Recommended Going Forward

Linked Records are the foundation for modeling related data in SmartSuite. Compared to legacy Sub-Items, they offer:

More powerful and reliable formula support
Greater flexibility for data loading, updates, and integrations
Full support for all field types
Better scalability and performance as solutions grow

For new builds, Linked Records combined with table views or embedded views provide the same functional outcomes as Sub-Items, with significantly more long-term flexibility.

Notes for API Users

If your solution integrates with SmartSuite via the API, there are a few important changes to be aware of.

Sub-Items Are Now Separate Applications

After migration:

Former Sub-Items are represented as records in newly created tables
You should create and update records in these tables directly
Parent-child relationships are maintained using Linked Record fields

You can retrieve the relevant table and field IDs using the Get Table API endpoint:

params.linked_application - ID of the new table
params.symmetric_field - the linked record field in the new table (on the "other side" of the connection)

You can create linked records using our standard API endpoints:

Simply ensure that when you create a new record in the table, you include a reference to the parent record using the appropriate Linked Record field.

API Response Changes

Previously, Sub-Items were returned as full embedded objects in API responses. After migration:

Sub-Items fields now return Linked Record IDs only
To retrieve full record data, make an additional request to the related table and filter by the parent record using the linked field

Example:

curl -X POST https: //app.smartsuite.com/api/v1/applications/<PARENT_APP>/records/list/ \
-H "Authorization: Token YOUR_API_KEY" \
-H "ACCOUNT-ID: WORKSPACE_ID" \
-H "Content-Type: application/json" \
--data '{
    "sort": [],
    "filter": {
        "operator": "and",
        "conditions": [
            {
                "comparison": "has_any_of",
                "field": "<symmetric_lr_field_slug>",
                "value": [
                    "<parent_record_id>"
                ]
            }
        ]
    }
}'

This aligns Sub-Items behavior with all other Linked Record relationships in SmartSuite.

Summary

Sub-Items are being deprecated and upgraded to Linked Records
Existing data is automatically migrated with no loss or required action
Legacy Sub-Items fields are hidden after migration
Linked Records are the recommended and supported approach for all new builds

If you need help redesigning an existing solution or planning a Linked Records–based architecture, our team is happy to help.

Table Overview

Creating/Connecting a SmartSuite Form in Fillout

Sub Items Field (Deprecated)