Custom Report Type
A Custom Report Type is a Salesforce metadata definition that exposes a set of objects, their relationships, and their fields as a foundation for building reports.
Definition
A Custom Report Type is a Salesforce metadata definition that exposes a set of objects, their relationships, and their fields as a foundation for building reports. Where standard Report Types ship with Salesforce and cover the most common analytical patterns (Accounts with Contacts, Opportunities with Products), Custom Report Types let admins build the cross-object combinations that are unique to each org. They are how teams expose junction objects, custom objects, and non-standard relationship paths to the report builder.
Every Custom Report Type starts with a primary object and adds related objects through their relationship fields. The admin picks which fields are exposed for filtering, grouping, and display. They can also configure default columns, group columns into logical sections, and set the report type as Deployed (visible to users) or In Development (admin-only). Without the right Custom Report Type, certain reports cannot exist at all because the data path the analyst needs is not available through any standard type.
How Custom Report Types unlock cross-object reporting
When standard Report Types are not enough
Standard Report Types cover the common cases: Accounts and Contacts, Opportunities with Products, Cases with Solutions. They do not cover custom objects, custom relationships, or non-standard paths between standard objects. A Custom Report Type is required for any report that includes a custom object, joins through a custom lookup field, exposes data on a junction object, or filters records by the absence of a related record on a relationship the standard types do not surface. Most production orgs end up with dozens of Custom Report Types over time.
Primary object, related objects, and the A-B-C levels
Each Custom Report Type starts with a primary object. Up to three related (child) objects can be added, producing A, A-B, A-B-C levels of joining. Each related object joins through a specific relationship field. For each related-object level, the admin picks whether records with no related records should appear (left outer join semantics) or only records with at least one related child (inner join). Get this wrong and the row count comes out very different from what the analyst expects.
Field selection and the layout designer
The Report Type detail page has a Fields Available For Reports section. The admin chooses which fields from each object are exposed, groups them into logical sections, and sets defaults for column display. Fields not included are not available in the report builder, even if they exist on the underlying object. This is how Custom Report Types control the analyst experience: a clean field list with only relevant fields beats an overwhelming list with everything. Plan the field selection deliberately, including which fields appear by default.
Deployed versus In Development status
Custom Report Types have a status field: In Development (visible only to admins) or Deployed (visible to all users with access to the underlying objects). Build the type In Development, test it by creating sample reports, then flip to Deployed once it works. Forgetting to deploy is the most common Custom Report Type bug; users report that the type does not appear in the report builder picker because it is still in development.
Filtering semantics on related objects
Custom Report Types support a related-object configuration option: "Each A record must have at least one related B record" (inner join) or "B records may or may not have related A records" (left outer). The choice changes which rows appear in the report. Inner join produces a list of A records that have at least one B; left outer shows all A records including those with no B. Cross-filters in the report layer also let analysts filter on the presence or absence of related records, but the Custom Report Type configuration determines the baseline join semantics.
Performance considerations
Custom Report Types that join multiple large objects can produce slow reports. Each join multiplies row counts in the result set before aggregation. A Custom Report Type joining Accounts, Opportunities, Opportunity Line Items, and Products produces row counts that scale as the product of the four object sizes. Use the Report Type to expose only the fields that matter for analysis; large field sets do not slow queries directly but slow the report builder UI. Filter early in the report definition to keep row counts manageable.
Maintenance and the deprecation problem
Custom Report Types reference object and field metadata directly. When a field is renamed or deleted, every report built on the type may break or display unexpected results. Field-level security changes propagate through to the report. Maintain a Custom Report Type inventory and review it during quarterly cleanups. Orphan types from retired projects are common; deactivating or deleting them keeps the report builder picker clean.
How to build a Custom Report Type
Building a Custom Report Type takes deliberate design. The object combinations, join semantics, and field selection all need to match what analysts will actually need from the reports. Build in sandbox, test with realistic data, deploy thoughtfully, and review periodically as the data model evolves.
- Identify the report use case and required data path
List the questions analysts need to answer. Sketch the object path that connects the data: primary object, then related objects in order. If standard Report Types already cover the path, skip the Custom Report Type and use the standard one.
- Create the Custom Report Type
Setup > Report Types > New Custom Report Type. Pick the primary object, enter a label, plural label, description, and category (Sales, Service, Custom). Save and proceed to the detail page.
- Add related objects via the A-B-C relationship picker
From the Custom Report Type detail page, add up to three levels of related objects. Pick the relationship field that connects each level. Configure the join semantics: inner join (each primary must have a related) or left outer (primary records included regardless).
- Configure Fields Available for Reports
Click Edit Layout or the Field Layout link. Pick fields from each object, drag them into logical sections, and set defaults for column display. Exclude fields that do not help analysts; cleaner field lists produce better reports.
- Set the status to Deployed
Edit the Custom Report Type and change status from In Development to Deployed. This is the step that makes the type visible to analysts in the report builder. Forgetting it is the most common Custom Report Type bug.
- Build a sample report to validate
Open Reports > New Report > pick the new Custom Report Type. Add filters, groupings, and columns. Verify the row count matches expectation against a known reference. Confirm joins behave as configured.
- Document the type for analysts
Add a clear description, useful example use cases, and any quirks. Analysts who do not know the field exists or what it means will skip it. Documentation pays off through more adoption and less support load.
- Deploy through change set or metadata API
Custom Report Types deploy like other metadata. Include them in your deployment package. Test in the target org by building a sample report after deployment to confirm everything came through.
The root of the Custom Report Type. Every related object joins through a relationship field on the primary or a downstream relationship.
Up to three related objects, each joining through a specific relationship. Configure join semantics: inner or left outer.
Which fields are exposed for reporting and how they are grouped. Excluded fields cannot be added to reports built from the type.
- Custom Report Types default to In Development status. Forgetting to flip them to Deployed is the most common bug; analysts report that the type does not appear in the picker.
- Inner join versus left outer changes the row count significantly. Picking the wrong join semantics produces reports that exclude records analysts expected to see (or include records that should not appear).
- Field renames or deletions on the underlying objects can break reports built on the Custom Report Type. Maintain an inventory and review during quarterly schema cleanups.
- Up to three levels of related objects per type. Deeper relationships need to be modeled through a different primary object or through multiple Custom Report Types.
- Field-level security still applies. Users without read access to a field see it as blank in reports built from the Custom Report Type, even if the type exposes the field.
Trust & references
Cross-checked against the following references.
- Custom Report Types OverviewSalesforce Help
- Create a Custom Report TypeSalesforce Help
- Custom Report Type Field LayoutSalesforce Help
Straight from the source - Salesforce's reference material on Custom Report Type.
- Create a Custom Report TypeSalesforce Help
- Add Related Objects to a Custom Report TypeSalesforce Help
- Deploy a Custom Report TypeSalesforce Help
Hands-on resources to go deeper on Custom Report Type.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What does a Custom Report Type define?
Q2. How many levels of related objects can a Custom Report Type include?
Q3. What does a 'with or without' join enable?
Discussion
Loading discussion…