Introduction

In AWS SAM and CloudFormation nested stacks, the root stack cannot directly Ref a resource defined inside a child stack. If the child stack creates an API Gateway that the root stack needs to know about, the usual solution is to export the relevant values from the nested stack as outputs and then consume those outputs from the parent stack.

Understand the Stack Boundary

A nested SAM application is still a separate CloudFormation stack. That means resource names and logical IDs defined inside the child template are scoped to that child stack.

So this kind of direct reference from the root stack does not work conceptually:

Ref: MyNestedApi

if MyNestedApi is defined only inside the nested template.

The parent must communicate with the child through parameters and outputs.

Define the API in the Nested Stack

Suppose the nested stack defines the API and a function behind it.

1AWSTemplateFormatVersion: '2010-09-09'
2Transform: AWS::Serverless-2016-10-31
3Resources:
4  NestedApi:
5    Type: AWS::Serverless::Api
6    Properties:
7      StageName: Prod
8
9  HelloFunction:
10    Type: AWS::Serverless::Function
11    Properties:
12      Runtime: python3.11
13      Handler: app.lambda_handler
14      CodeUri: src/
15      Events:
16        ApiEvent:
17          Type: Api
18          Properties:
19            RestApiId: !Ref NestedApi
20            Path: /hello
21            Method: get
22Outputs:
23  ApiId:
24    Value: !Ref NestedApi
25  ApiUrl:
26    Value: !Sub 'https://${NestedApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/'

The important part is the Outputs section. That is the official way for the nested stack to expose values upward.

Reference the Nested Outputs from the Root Stack

The root SAM template includes the nested application and reads its outputs through GetAtt on the nested stack resource.

1AWSTemplateFormatVersion: '2010-09-09'
2Transform: AWS::Serverless-2016-10-31
3Resources:
4  ApiChild:
5    Type: AWS::Serverless::Application
6    Properties:
7      Location: nested/api-stack.yaml
8
9Outputs:
10  ChildApiId:
11    Value: !GetAtt ApiChild.Outputs.ApiId
12  ChildApiUrl:
13    Value: !GetAtt ApiChild.Outputs.ApiUrl

That is the standard pattern. The parent is not looking inside the child’s logical resource IDs directly. It is consuming named outputs from the child stack resource.

Pass API Information Back Into Other Nested Stacks

Sometimes the parent needs to pass the child API identifier into another nested application. The parent can do that by taking the output from the first child and passing it as a parameter to the second.

1Resources:
2  ApiChild:
3    Type: AWS::Serverless::Application
4    Properties:
5      Location: nested/api-stack.yaml
6
7  ConsumerChild:
8    Type: AWS::Serverless::Application
9    Properties:
10      Location: nested/consumer-stack.yaml
11      Parameters:
12        ApiId: !GetAtt ApiChild.Outputs.ApiId

Then the second nested template declares an ApiId parameter and uses it normally.

This parent-mediated wiring is the clean way to share resources across nested applications.

Root Stack Functions and Child APIs

If the root stack itself defines a function or permission that depends on the nested API, the same output pattern applies. For example, if a root resource needs the API id or invoke URL, expose that value in the nested template and consume it from the root.

Do not try to infer it from the nested logical name, and do not assume CloudFormation will flatten nested resource references across stack boundaries.

Keep the Interface Small and Explicit

Treat the nested stack like a module with a public interface.

Good interface values to output include:

• API id
• invoke URL
• ARN if needed for permissions
• stage name if the parent must compose URLs

This keeps the child reusable and avoids leaking internal implementation details into the parent template.

Common Pitfalls

The most common mistake is trying to Ref or GetAtt a resource inside the nested stack directly from the root template, which is not how nested stack boundaries work. Another is forgetting to declare an output in the child stack and then wondering why the parent has nothing to consume. Teams also sometimes output too little information, such as only the API id when the parent really needs the invoke URL or stage as well. A final issue is tightly coupling the parent to a child’s internal resource naming instead of exposing a small explicit contract through outputs.

Summary

• The root stack cannot directly reference a resource defined only inside a nested stack.
• Expose API Gateway values from the child stack through Outputs.
• Read those values in the parent with !GetAtt NestedStackResource.Outputs.OutputName.
• Pass child outputs into other nested stacks through parent parameters when needed.
• Treat nested stacks as modules with explicit interfaces rather than as flattened templates.