# Using the AWS Partner Central Selling API Using the Selling API This AWS Partner Central API reference is designed to help [AWS Partners](https://aws.amazon.com/partners/programs/) integrate customer relationship management (CRM) systems with Partner Central. The API automates interactions with Partner Central, which helps to ensure effective engagements in joint business activities. The API provides standard AWS API functionality. Access it by either using API [Actions](https://docs.aws.amazon.com/partner-central/latest/selling-api/API_Operations.html) or by using an AWS SDK that's tailored to your programming language or platform. For more information, see [Getting Started with AWS](https://aws.amazon.com/getting-started) and [Tools to Build on AWS](https://aws.amazon.com/developer/tools/). ## Features offered by AWS Partner Central API 1. **Opportunity management:** Facilitates the management of coselling opportunities with AWS using API actions such as `CreateOpportunity`, `UpdateOpportunity`, `ListOpportunities`, `GetOpportunity`, and `AssignOpportunity`. 1. **AWS referral management:** Facilitates receiving referrals shared by AWS using actions like `ListEngagementInvitations`, `GetEngagementInvitation`, `StartEngagementByAcceptingInvitation`, and `RejectEngagementInvitation`. 1. **Entity association:** Associate related entities such as *AWS Products*, *Partner Solutions*, and *AWS Marketplace Private Offers* with opportunities using the actions `AssociateOpportunity` and `DisassociateOpportunity`. 1. **View AWS opportunity details:** Use the `GetAWSOpportunitySummary` action to retrieve real-time summaries of AWS opportunities that are linked to your opportunities. 1. **List solutions:** Provides list APIs for listing solutions partners offer using `ListSolutions`. 1. **Event subscription:** Partners can subscribe to real-time updates on opportunities by listening to events such as *Opportunity Created*, *Opportunity Updated*, *Engagement Invitation Accepted*, *Engagement Invitation Rejected* and *Engagement Invitation Created* using Amazon EventBridge. ## Supported Regions and endpoints The AWS Partner Central API is available in the US East (N. Virginia) Region. | Region | Endpoint | | --- | --- | | us-east-1 | partnercentral-selling.us-east-1.api.aws | Partners can test and validate API integrations in a secure sandbox environment. This allows you to test API actions without affecting live data. For more information, see [Testing in a sandbox for the AWS Partner Central Selling API](testing-sandbox.md). ## Selling API entities AWS Partner Central entities represent key business components used in coselling engagements between partners and AWS. These entities encapsulate information related to opportunities, solutions, products, and offers, enabling smooth collaboration and management of joint sales activities. The following sections provide descriptions of the core entities in the Partner Central Selling API. ### Opportunity An opportunity is a potential sale or deal that a business identifies and actively pursues. It's a qualified prospect or lead with a specific need that the company's products or services can address. Opportunities are typically tracked in a sales pipeline or CRM system and form the foundation of future revenue. Effective opportunity management involves nurturing leads through the sales process, from the initial qualification to closing. For more information, see [Working with your opportunities](working-with-your-opportunities.md) and [Data types](API_Types.md) ### Partner Solutions Represents a Partner Solution (referred to as offering on AWS Partner Central), which is a software product or consulting practice created and delivered by AWS Partners. Partner Solutions help customers address specific business challenges or achieve particular goals using AWS services. For more information, see [What is a solution?](https://docs.aws.amazon.com/partner-central/latest/builder-guide/what-is-a-solution.html) ### AWS product Represents a specific AWS service or product. AWS offers a wide range of products and services designed to provide scalable, reliable, and cost-effective infrastructure solutions. Partners can obtain the latest list of AWS Products from the [bulk import page on Partner Central ](https://partnercentral.awspartner.com/OpportunityBulkImportPage) (Start Import > AWS Products and Solutions). For more information, you can [learn about AWS Products ](https://aws.amazon.com/products) or [view the list of all AWS Products](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/resources/aws_products.json). ### AWS Marketplace private offer AWS Marketplace private offer is a feature that allows AWS Marketplace sellers to offer specific pricing and terms to individual AWS customers. Through private offers, sellers can negotiate custom prices, payment schedules, and end user license terms. AWS customers can obtain software solutions that meet their specific requirements, while also possibly benefiting from more favorable terms or pricing compared to standard offerings. The private offer process involves the seller creating a unique offer with tailored terms, which is then shared privately with the designated AWS customer for their review and acceptance. For more information, see [Private offers in AWS Marketplace](https://docs.aws.amazon.com/marketplace/latest/buyerguide/buyer-private-offers.html). ### Engagement invitation Engagement Invitation refers to a formal request from AWS for partners to collaborate on a specific referral. This allows AWS and the partner to work together to drive the opportunity forward. The invitation can be accepted or rejected by the partner. **Topics** + [ ## Features offered by AWS Partner Central API ](#features-offered-by-aws-partner-central-api) + [ ## Supported Regions and endpoints ](#supported-regions-and-endpoints) + [ ## Selling API entities ](#selling-api-entities) + [ # Working with your opportunities ](working-with-your-opportunities.md) + [ # Working with opportunities from AWS ](working-with-opportunities-from-aws.md) + [ # Working with opportunity updates ](working-with-opportunity-updates.md) + [ # Working with multipartner opportunities ](working-with-multi-partner-opportunities.md) + [ # Associating, disassociating and assigning opportunities ](associating-disassociating-assigning-opportunities.md) + [ # Working with your leads ](working-with-your-leads.md) + [ # Working with deal sizing insights ](working-with-deal-sizing-insights.md) + [ # Best practices ](best-practices.md) # Working with your opportunities ## What is an Opportunity? During the initial stages of the sales process, a sales representative assesses whether an interested individual (called *lead*) has the potential to become a customer. This assessment and validation phase is referred to as *Qualification*. Once a lead is deemed qualified and is considered to have a higher probability of converting to a customer, it is then classified as an *Opportunity*. ## Working with Your Opportunities Partners can manage opportunities created within their CRM systems and synchronize them with AWS Partner Central using the AWS Partner Central Selling API. This allows partners to track and manage opportunities from initiation to closure. ### Creating an Opportunity The first step in managing opportunities is creating an opportunity using the `CreateOpportunity` action. This creates an opportunity with the `Lifecycle.ReviewStatus` set to `Pending Submission`. However, the opportunity is not yet submitted to AWS for validation. Once created, partners must associate at least one Partner Solution with the opportunity using the `AssociateOpportunity` action. This action clearly defines what the opportunity is attempting to sell. Partners can view the complete list of available solutions in their account using the `ListSolutions` API, and they can associate between one and ten solutions. Optionally, partners can also associate relevant AWS Products with the opportunity using the `AssociateOpportunity` action. This step helps AWS sales teams understand what AWS products are expected to be sold in conjunction with the opportunity. Once the required Partner Solution is associated and, optionally, AWS Products are linked, partners can start engagement on the opportunity by using the `StartEngagementFromOpportunityTask` action. The is when the opportunity gets submitted for starting an engagement. ### Review Process After starting the engagement on the opportunity using the `StartEngagementFromOpportunityTask` action, the opportunity enters the AWS validation phase, and its `Lifecycle.ReviewStatus` is set to `Submitted`. No changes can be made to the opportunity until the review process is complete. During this validation phase, AWS ensures that the opportunity details are accurate and complete. While the validation is in progress, the `Lifecycle.ReviewStatus` is set to `In-Review`. If there are changes or additional details required from the partner, AWS sets the `Lifecycle.ReviewStatus` to `Action Required`, and any required updates are communicated via the `Lifecycle.ReviewComments` field. Once the opportunity passes validation, the `Lifecycle.ReviewStatus` changes to `Approved`, making the opportunity ready for co-selling activities. Partners should monitor the `Opportunity Updated` event using Amazon EventBridge. This will notify them of any status changes or feedback from AWS. Upon receiving the event, partners can use the `GetOpportunity` API action to fetch the latest opportunity details and verify the `Lifecycle.ReviewStatus` field. ### Resolving Validation Issues If the `Lifecycle.ReviewStatus` is set to `Action Required`, partners need to address the issues highlighted by AWS. To resolve these, partners can update the opportunity using the `UpdateOpportunity` API action. During the `Action Required` state, only certain fields are editable. These fields include: 1. `Customer.Account.Address.City` 1. `Customer.Account.Address.Country` 1. `Customer.Account.Address.PostalCode` 1. `Customer.Account.Address.StateOrRegion` 1. `Customer.Account.Address.StreetAddress` 1. `Customer.Account.WebsiteUrl` 1. `LifeCycle.TargetCloseDate` 1. `Project.ExpectedCustomerSpend.Amount` 1. `Project.ExpectedCustomerSpend.Currency` 1. `Project.CustomerBusinessProblem` 1. `PartnerOpportunityIdentifier` After making the necessary changes, the opportunity re-enters the validation phase, and the process repeats until the opportunity's `Lifecycle.ReviewStatus` is set to `Approved` or `Disqualified`. ### Post-Approval Updates Once the opportunity is `Approved`, partners can continue to update the opportunity as needed using the `UpdateOpportunity` action, facilitating seamless co-selling activities. Partners should continue monitoring the `Opportunity Updated` events through Amazon EventBridge to remain updated on any changes. For more information on tracking AWS updates, refer to the "Working with opportunity updates" section. Partners can also update select fields based on the business validation rules. # Working with opportunities from AWS ## 1. Receiving the AWS Opportunity Opportunities are shared with partners when an AWS sales executive attaches a partner to an opportunity in AWS's CRM system. These are referred to as AWS Opportunities, distinct from opportunities created in the partner's own account. When an AWS Opportunity has a partner attached, AWS creates an Engagement Invitation containing a subset of data from the AWS Opportunity. Partners will receive an *Engagement Invitation Created* event. ## 2. Reviewing the Engagement Invitation The Engagement Invitation contains essential information such as `Project.Title`, `Project.CustomerUseCase`, `Lifecycle.Stage`, `Project.CustomerBusinessProblem`, and a few additional fields. Partners can use this data to decide whether to pursue the opportunity. However, the following fields from the AWS Opportunity are not included in the Engagement Invitation: ``` Customer.Account.Address.StreetAddress Customer.Account.Address.City Customer.Account.Address.PostalCode Customer.Contact Customer.Account.AWSAccountId Project.OtherSolutionDescription RelatedEntityIdentifiers ``` ## 3. Handling the Engagement Invitation Upon receiving an *Engagement Invitation Created* event, partners can use the `GetEngagementInvitation` action to retrieve details of the AWS Opportunity. If the partner decides not to pursue the opportunity, they can reject the invitation using the `RejectEngagementInvitation` action, along with the required `RejectionReason`. Once rejected, access to the opportunity is lost. To accept the invitation and proceed, partners should use the `StartEngagementByAcceptingInvitationTask` action. This is an asynchronous action that sequentially performs the following tasks: 1. Accepts the Engagement Invitation. 1. Creates a new opportunity in the partner's account using data from the AWS Opportunity. 1. Includes additional details required to identify the customer in the partner's account. Upon completion, an *Opportunity Created* event is triggered with the corresponding Opportunity ID. Partners can then use this ID in the `GetOpportunity` action to retrieve full details of the opportunity. If the partner is not using events, they can call `StartEngagementByAcceptingInvitationTask` again with the same payload to check the latest status. ## 4. Managing the AWS Opportunity Post-Acceptance Once the opportunity is in the partner's account, it can be managed and updated like any other opportunity in the system. Partners can use actions like `UpdateOpportunity` to make any necessary changes. For more details on how to track AWS updates and manage opportunity updates, refer to the [Working with opportunity updates](working-with-opportunity-updates.md) section. # Working with opportunity updates ## Updating opportunities Partners can use the `UpdateOpportunity` action to update opportunities, with specific rules governing which fields are updated, and when they're updated: 1. Updates cannot be made if the `Lifecycle.ReviewStatus` is `Submitted` or `In-Review`. 1. Before submission, partners can make updates, but AWS will not process them unless the `StartEngagementFromOpportunityTask` action is invoked. 1. When the opportunity is in `Submitted` or `In-review` status, all updates are blocked. 1. If the opportunity is in `Action Required` status, AWS opens select fields for updates. These fields include: + `Customer.Account.Address.City` + `Customer.Account.Address.Country` + `Customer.Account.Address.PostalCode` + `Customer.Account.Address.StateOrRegion` + `Customer.Account.Address.StreetAddress` + `Customer.Account.WebsiteUrl` + `LifeCycle.TargetCloseDate` + `Project.ExpectedCustomerSpend.Amount` + `Project.ExpectedCustomerSpend.CurrencyCode` + `Project.ExpectedCustomerSpend.EstimationURL` + `Project.ExpectedCustomerSpend.Frequency` + `Project.ExpectedCustomerSpend.TargetCompany` + `Project.CustomerBusinessProblem` + `PartnerOpportunityIdentifier` 1. After the review process (i.e., when `Lifecycle.ReviewStatus` is set to `Approved`), the following fields cannot be updated: + `Customer.Account.Address.Country` + `Customer.Account.Address.PostalCode` + `Customer.Account.Industry` + `Customer.Account.WebsiteUrl` + `Project.CustomerBusinessProblem` + `PartnerOpportunityIdentifier` + `Project.Title` 1. For all other fields, updates can be made using the `UpdateOpportunity` action. However, additional restrictions may apply based on business rules for the specific program or opportunity type. For more details, refer to field-level validations. 1. For all updates made through both the UI and API, the *Opportunity Updated* event is generated. ## Receiving updates from AWS on opportunities AWS typically updates AWS opportunities, and each time an update is made, an *Opportunity Updated* event is generated. **To retrieve the latest updates from AWS, partners need to invoke two separate actions** 1. `GetOpportunity` to retrieve details of the partner's opportunity. 1. `GetAWSOpportunitySummary` to retrieve real-time summaries of the AWS opportunity data. Most regular updates from AWS will be available through the `GetAWSOpportunitySummary` response. However, AWS may occasionally update attributes in the partner's opportunity directly. **To consume updates from AWS** 1. Invoke the `GetAWSOpportunitySummary` action to retrieve the latest details of the AWS Opportunity. 1. If changes need to be reflected in the partner's opportunity, use the `UpdateOpportunity` action to copy the relevant data onto the partner's opportunity. Partners can choose to automate this process as a direct update mechanism or implement a manual review process to validate and update the data. # Working with multipartner opportunities AWS Partners can work together on opportunities with AWS as an active participant. **Topics** + [ ## Engagements and snapshots ](#engagements-and-snapshots) + [ ## Creating a custom policy for ResourceSnapshotJobRole ](#creating-custom-policy-resourcesnapshotjobrole) + [ ## Inviting partners to an opportunity ](#inviting-partners-to-an-opportunity) + [ ## Retrieving engagement invitation details ](#retrieving-invitation-details) + [ ## Responding to an engagement invitation ](#responding-engagement-invitation) + [ ## Reviewing and updating multipartner opportunities ](#reviewing-and-updating-multipartner-opportunities) + [ ## Using snapshots to receive partner updates ](#using-snapshots-to-receive-partner-updates) + [ ## Viewing engagement members ](#viewing-engagement-members) + [ ## Monitoring resource snapshot job status ](#monitoring-resource-snapshot-job-status) ## Engagements and snapshots An *engagement* is a resource owned by AWS for collaboration between multiple AWS Partner accounts and AWS on a customer opportunity. Engagements facilitate secure information sharing among partners and collaboration while maintaining individual opportunity ownership and control. Engagements encompass opportunities that originate from both AWS and partners, with AWS as an active participant. Partners can invite AWS or other partners to join an engagement using `EngagementInvitations`. When invited partners accept, they receive their own opportunity within the same engagement. Engagement members share progress through snapshots—point in time, immutable copies of specific fields from an underlying resource such as an opportunity. Snapshots are created within the engagement and shared with members. When the underlying resource changes, the owner can create a new snapshot revision to reflect updates. AWS provides snapshot jobs—customer-owned jobs that automatically create new revisions when the resource changes. Once shared, snapshots remain permanently accessible to engagement members. ## Creating a custom policy for ResourceSnapshotJobRole Collaborating on multi-partner opportunities requires sharing snapshots of your opportunities with other partners in an engagement. To maintain access to the latest opportunity details, you need to create a custom role called `ResourceSnapshotJobRole`. This role allows the system to create snapshots of your opportunities on your behalf and retrieve snapshots from other partners in the same engagement. Without this role, any updates you make to your opportunity will not be visible to other partners in the engagement, and they will continue to see outdated snapshots of your opportunity data. **Note** You can use a name other than `ResourceSnapshotJobRole`. If you use a different name, replace all instances of `ResourceSnapshotJobRole` in the following policies with your policy name. To create this role, go to your IAM console and create the `ResourceSnapshotJobRole` role with the following custom trust policy: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "resource-snapshot-job.partnercentral-selling.amazonaws.com" }, "Action": "sts:AssumeRole" } ] } ``` ------ After creating this role, you need to attach the [https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSPartnerCentralSellingResourceSnapshotJobExecutionRolePolicy.html](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSPartnerCentralSellingResourceSnapshotJobExecutionRolePolicy.html) AWS managed policy, or attach the following permissions policy: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "partnercentral:CreateResourceSnapshot" ], "Resource": [ "arn:aws:partnercentral:*::catalog/AWS/engagement/*" ] }, { "Effect": "Allow", "Action": [ "partnercentral:GetOpportunity" ], "Resource": [ "arn:aws:partnercentral:*:111122223333:catalog/AWS/opportunity/*" ] } ] } ``` ------ Replace `{account}` with your AWS account ID. After you create the `ResourceSnapshotJobRole` role and attach the permissions, you need to set the `ResourceSnapshotJobRole` for your organization. Use the [PutSellingSystemSettings](API_PutSellingSystemSettings.md) action to set the role you created as the `ResourceSnapshotJobRole` for your company (identified by your AWS account): ``` aws-cli/2.13.5 Python/3.11.4 Linux/4.14.255-314-253.539.amzn2.x86_64 Host: partner-central.aws.amazon.com Content-Type: application/json { "ResourceSnapshotJobRoleIdentifier": "arn:aws:iam::{account}:role/ResourceSnapshotJobRole" } ``` Replace `{account}` with your AWS account ID, and `ResourceSnapshotJobRole` with the name of the role you created. This role will be implicitly assumed by the resource snapshot jobs to access your opportunities and create snapshots for sharing with other partners in the engagement. ## Inviting partners to an opportunity Partners can collaborate on opportunities that originate from both partners and AWS by initiating an engagement invitation. You can invite a maximum of nine partners to an opportunity. **To invite partners to an opportunity** 1. Follow the steps in [Finding and connecting with partners](https://docs.aws.amazon.com/partner-central/latest/sales-guide/partner-connections.html#finding-connecting-partners) in the *AWS Partner Central Sales Guide*. You must connect with partners before you can invite them to opportunities. This connection grants mutual access to each other's account IDs, ensuring invitations reach the intended partner account. 1. Use the [StartEngagementFromOpportunityTask](API_StartEngagementFromOpportunityTask.md) action to create an engagement and associate an opportunity with it. This asynchronous action performs the following tasks sequentially: 1. Creates an engagement. 1. Associates the opportunity with the engagement. 1. Invokes the [CreateEngagementInvitation](API_CreateEngagementInvitation.md) action to AWS. 1. Submits the opportunity to AWS. 1. Starts the `ResourceSnapshotJob` to create snapshots. 1. Invite other partners to join. 1. To get the engagement ID associated with your opportunity, use the [ListEngagementFromOpportunityTasks](API_ListEngagementFromOpportunityTasks.md) action, filtered by the `TaskIdentifier` returned in the previous step. 1. Use the receiving partner's engagement ID and account ID to send an invitation with `CreateEngagementInvitation`. A successful invitation sends an engagement invitation created event to the receiving partner. ## Retrieving engagement invitation details When you receive an engagement invitation created event, use the [GetEngagementInvitation](API_GetEngagementInvitation.md) action to retrieve the invitation details. The response includes essential information about the customer opportunity associated with the engagement. Review the invitation details, particularly the `InvitationMessage`, `Project.Title`, `Project.CustomerUseCase`, and `Project.CustomerBusinessProblem` fields. This information provides context about the customer opportunity and the inviting partner's expectations for collaboration. Use these details to evaluate if you want to pursue the opportunity by accepting or declining the engagement invitation. ## Responding to an engagement invitation When a partner sends you an engagement invitation, it creates an engagement invitation created event that notifies you of the invitation. You have the option to accept or reject the invitation. This decision determines your involvement in the multipartner opportunity. **To reject an engagement invitation:** Use the [RejectEngagementInvitation](API_RejectEngagementInvitation.md) action to reject the invitation. You must provide a `RejectionReason` parameter explaining your decision. Once rejected, you lose access to the invitation details, and an engagement invitation rejected event notifies the sending partner that you have rejected their invitation. **To accept an engagement invitation:** To accept the invitation and proceed with the multipartner opportunity, use the [StartEngagementByAcceptingInvitationTask](API_StartEngagementByAcceptingInvitationTask.md) action. This asynchronous action performs the following tasks sequentially: 1. Accepts the engagement invitation. 1. Creates a new opportunity in your partner account using data from the sending partner's opportunity. You will receive an opportunity created event. 1. Includes additional details required to identify the customer in your account. 1. Publishes an engagement invitation accepted event which notifies the partner that you have accepted the invitation and have been added to the engagement. **Expired engagement invitation** If you do not respond to an engagement invitation within fifteen days, it expires, and you cannot participate in the multipartner opportunity. An engagement invitation expired event notifies the sending partner that the invitation expired. **Note** If you still want to collaborate, the sending partner must initiate a new engagement invitation. ## Reviewing and updating multipartner opportunities When a partner initiates an engagement on an opportunity, the review status of the newly created opportunity in the receiving partner's account is determined by the sending partner's opportunity status. **Opportunity with submitted review status:** If the sending partner's opportunity has `Lifecycle.ReviewStatus` set to `Submitted`, the following process occurs: 1. The new opportunity created in the receiving partner's account will have `Lifecycle.ReviewStatus` set to `Submitted`. 1. The `Submitted` status remains until the sending partner's opportunity is `Approved`. 1. Once the sending partner's opportunity is validated and the `Lifecycle.ReviewStatus` is set to `Approved`, the other partners' opportunities will automatically inherit the `Approved` status. This process ensures consistent opportunity details across multipartner opportunities, eliminating the need for multiple reviews. Once complete, an opportunity created event is triggered with the corresponding opportunity ID. Partners can use this ID with the `GetOpportunity` action to retrieve the full opportunity details. **Opportunity with approved review status:** If the sending partner initiates an engagement on an opportunity with `Lifecycle.ReviewStatus` set to `Approved`, the following process occurs: 1. The new opportunity created in the receiving partner's account will have `Lifecycle.ReviewStatus` set to `Approved`. 1. An opportunity created event is triggered with the corresponding opportunity ID. 1. Partners can use the [GetOpportunity](API_GetOpportunity.md) action with the opportunity ID to retrieve the full opportunity details. However, the approved opportunity may not have some partner-specific details that were not copied from the sending partner's opportunity. The receiving partner should update these details using the [UpdateOpportunity](API_UpdateOpportunity.md) action when the opportunity stage is updated to `Qualified` or a later stage: + `Project.CustomerUseCase` + `Project.DeliveryModels` + `Solution` + `PrimaryNeedsFromAws` + `LifeCycle.TargetCloseDate` + `Project.ExpectedCustomerSpend.Amount` + `Project.ExpectedCustomerSpend.Currency` + `Marketing.source` + `Marketing.AwsFundingUsed` Once the opportunity is created in the receiving partner's account, it can be managed and updated like any other opportunity within the partner's system. Partners can use the [UpdateOpportunity](API_UpdateOpportunity.md) action to make changes or provide more information about their involvement in the opportunity. ## Using snapshots to receive partner updates Within an engagement, partners maintain and update their opportunities independently. When someone revises an engagement's resources, such as adding an opportunity, an engagement resource snapshot created event is published. To stay informed about changes and access the most current information from other partners' opportunities, you can use the following actions: + [ListEngagementResourceAssociations](API_ListEngagementResourceAssociations.md) – Use this action to retrieve the engagement ID associated with the opportunity. + [ListResourceSnapshots](API_ListResourceSnapshots.md) – Use this action to retrieve a comprehensive list of all opportunity snapshots associated with the engagement, providing an overview of available snapshots across all partners. + [GetResourceSnapshot](API_GetResourceSnapshot.md) – Use this action to obtain real-time summaries of specific opportunity snapshots, allowing you to view the most up-to-date information without directly accessing another partner's opportunity. If you identify relevant changes or updates from another partner's opportunity that should be reflected in your own, use the [UpdateOpportunity](API_UpdateOpportunity.md) action. This action facilitates selectively incorporating pertinent data into your opportunity, ensuring alignment and consistency across the engagement. ## Viewing engagement members An engagement on a multipartner opportunity can have up to ten partners. Whenever a new partner accepts the engagement invitation, an engagement member added event is published, notifying all current members about the change. To view all members collaborating within an engagement, follow these steps: 1. Use the [ListEngagementResourceAssociations](API_ListEngagementResourceAssociations.md) action to retrieve the engagement ID associated with the opportunity. 1. Provide the ID from step 1 to the [ListEngagementMembers](API_ListEngagementMembers.md) action to fetch the partner details of engagement members. **Note** Only members of an engagement can invoke the `ListEngagementMembers` action. ## Monitoring resource snapshot job status When working with multipartner opportunities, you must create a role that allows you to create snapshots of your opportunities for other partners and retrieve opportunity snapshots from other partners in an engagement. Without this role, any updates you make to your opportunity will not be available to other partners in the engagement, and they will continue to see outdated snapshots of your opportunity. To track the status of resource snapshot jobs associated with a multipartner opportunity in an engagement, follow these steps: 1. Use the [ListEngagementResourceAssociations](API_ListEngagementResourceAssociations.md) action to retrieve the engagement ID associated with the opportunity. 1. Provide the ID from step 1 to the [ListResourceSnapshotJobs](API_ListResourceSnapshotJobs.md) action to generate a list of all snapshot jobs owned by the caller in the engagement. Retrieve the job ID from the response. 1. Provide the job ID to the [GetResourceSnapshotJob](API_GetResourceSnapshotJob.md) action to track the job status and see if it's running. The `ResourceSnapshotJob` operation publishes metrics to Amazon CloudWatch for its asynchronous operations. CloudWatch processes the data into readable, near real-time metrics to help you monitor the performance and health of the service. The following metrics are available: + **Faults** – Counts internal issues during job execution. Use this metric to monitor service stability and set alarms for fault thresholds. + **Errors** – Tracks customer-related issues during job processing. This metric helps identify problems with customer inputs or configurations. + **Invocations** – Represents the total number of job invocations, including both successful and failed attempts. Use this to track service usage trends over time. **Note** Metrics are reported to CloudWatch only when there is activity in the `ResourceSnapshotJob` service. If there are no jobs or no data for a specific metric, that metric isn't reported. To ensure smooth operation of the `ResourceSnapshotJob` operation: + Use the metrics to verify that the service performs as expected. + Create CloudWatch alarms to monitor metrics and trigger actions (such as sending notifications) when metrics exceed acceptable ranges. + Set up proactive monitoring to Identify and resolve issues. For more information about using CloudWatch metrics, see the [Amazon CloudWatch User Guide](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/). # Associating, disassociating and assigning opportunities Opportunities can be associated or disassociated with Partner Solutions, AWS Products, AWS Marketplace Offers, and AWS Marketplace Offer Sets throughout the opportunity lifecycle. ## Associating opportunities with other entities The associated entities are retrieved from the `GetOpportunity` method within the `RelatedEntityIdentifiers` object. The `RelatedEntityIdentifiers` can be updated using `AssociateOpportunity`. Note that this field cannot be updated using the `UpdateOpportunity` or `CreateOpportunity` method. ## Solutions Before an engagement with AWS is started using the `StartEngagementFromOpportunityTask` action, it is mandatory to associate at least one and up to ten Partner Solutions. An AWS Referral may or may not contain a Partner Solution. To view your existing solutions, use the `ListSolutions` action. Partners can create, update, and manage their solutions in the `Build` section on [AWS Partner Central](https://aws.amazon.com/partners/). ## AWS products Up to 20 AWS Products can be associated with an opportunity. To view a list of available AWS Products, use the list of [AWS Products hosted on GitHub](https://github.com/aws-samples/partner-crm-integration-samples/blob/main/resources/aws_products.json). Association with AWS Products is exclusively done using the `AssociateOpportunity` action. To replace or remove a Product, use the `DisassociateOpportunity` action. ## AWS Marketplace offers and offer sets ### AWS Marketplace offers Opportunities can be tied to an AWS Marketplace Private Offer. To view available offers, use the ListEntities from the AWS Marketplace Catalog API. Currently, you can only associate offers from the AWS Marketplace Seller account linked to AWS Partner Central. For associating a private offer ARN is required. Sample: ``` arn:aws:aws-marketplace:us-east-1:123123123123:AWSMarketplace/Offer/offer-dtn3example1tg ``` ### AWS Marketplace offer sets Opportunities can also be associated with AWS Marketplace Offer Sets. Offer sets enable the grouping of multiple related marketplace offers together for comprehensive solution packaging. To view available offer sets, use the ListEntities from the AWS Marketplace Catalog API. For associating an offer set, an ARN is required. Sample: ``` arn:aws:aws-marketplace:us-east-1:123123123123:AWSMarketplace/OfferSet/offerset-dtn3example1tg ``` **Important:** An opportunity can be associated with either **one Offer** OR **one Offer Set**, but not both. Only one of these entity types can be associated with an opportunity at a time. ## Disassociating opportunities from other entities Use the `DisassociateOpportunity` action to unlink the Opportunity from Solutions, AWS Products, AWS Marketplace Offers and AWS Marketplace Offer Sets. Depending on the state of the Opportunity, different validation rules apply for unlinking the related objects. ## Assigning opportunities Use `AssignOpportunity` to change the opportunity's owner. You can set any of your Partner Central users to be the opportunity owner. # Working with your leads ## What is a Lead? In business-to-business (B2B) sales, a lead represents a potential customer who has expressed interest in a company's products or services but has not yet been fully qualified as a sales opportunity. Leads are the initial stage of the sales pipeline and require nurturing and qualification before they can be converted into opportunities for active co-selling with AWS. In , leads are shared by AWS with partners based on customer engagement signals such as webinar attendance, campaign participation, or partner solution inquiries. These leads include valuable context like customer company information, business problems, and engagement details to help partners prioritize and qualify potential opportunities. ## Working with Lead Invitations Partners receive lead invitations from AWS when potential customers express interest in partner solutions or services. The lead invitation process allows partners to evaluate leads before committing to engagement, ensuring efficient resource allocation and higher conversion rates. ### Receiving Lead Invitations AWS creates lead invitations and shares them with partners through the Selling API. When a new lead invitation is available, AWS sends an Engagement Invitation with the Lead context to eligible partners. Partners should monitor the `Engagement Invitation Created` event using Amazon EventBridge. This event notification includes the `payloadType` field set to `LeadInvitation`, allowing partners to distinguish lead invitations from opportunity invitations. Upon receiving the event, partners can retrieve invitation details to evaluate the lead. ### Listing Lead Invitations Partners can view all their lead invitations using the `ListEngagementInvitations` API action. This action retrieves invitations where the calling principal is either a sender or receiver. To filter specifically for lead invitations, partners should use the `payloadType` filter with the value `LeadInvitation`. This filter ensures that only lead invitations are returned, excluding opportunity invitations from the results. Lead invitations can be in the following states: + **Pending**: Awaiting partner acceptance or rejection + **Accepted**: Partner has accepted the invitation and gained access to full lead details + **Rejected**: Partner has declined the invitation + **Expired**: Invitation has passed its expiration date without action ## Evaluating Lead Invitations Before accepting a lead invitation, partners should retrieve detailed invitation information using the `GetEngagementInvitation` API action. This provides essential context for making informed accept or reject decisions. The lead invitation payload includes: **Customer Information (available pre-acceptance):** + Company name, industry, and country + Website URL + Market segment (Enterprise, Large, Medium, Small, Micro) + AWS maturity level (Evaluating, Single-Account, Multi-Account) **Customer Interactions:** + Source type and campaign information + Customer action taken (form completion, webinar attendance, etc.) + Business problem description provided by the customer + Use case category + Contact title (provides Authority context for BANT qualification) **Important** Customer contact information (name, email, phone number) is not visible at the invitation stage. Contact details become available only after accepting the invitation, ensuring customer privacy and preventing lead farming behavior. ## Accepting Lead Invitations When a partner decides to pursue a lead, they must accept the invitation using the `AcceptEngagementInvitation` API action. This action adds the partner to the engagement and grants access to full lead details, including customer contact information. After acceptance: + The partner is added as a member of the engagement + Customer contact information becomes visible through the engagement Lead context + The lead is classified as a Partner Qualified Lead (PQL) in AWS systems + The lead appears in the partner's active leads list + Partners can begin nurturing the lead and establishing customer contact Partners can accept multiple lead invitations programmatically by calling `AcceptEngagementInvitation` for each invitation, enabling efficient bulk processing of high-quality leads. ## Rejecting Lead Invitations If a lead does not align with the partner's capabilities, capacity, or business focus, partners can decline the invitation using the `RejectEngagementInvitation` API action. When rejecting a lead invitation, partners should provide a rejection reason to help AWS improve lead routing and matching. Common rejection reasons include: + Lack of geographic coverage + Insufficient technical expertise for the use case + Current capacity constraints + Customer industry mismatch + Budget misalignment After rejection: + The lead is removed from the partner's pending invitations queue + Customer contact information is never shared with the partner + The lead is classified as a Partner Rejected Lead (PRL) in AWS systems + The invitation remains visible in the partner's rejected invitations list for reference Rejected leads may be eligible for reassignment to other partners, provided customer consent requirements are met. ## Managing Accepted Leads After accepting a lead invitation, partners can access complete lead information, nurture customer relationships, and track the lead through qualification stages. ### Viewing Lead Details Partners access full lead details using the `GetEngagement` API action. The engagement contains a Lead context with comprehensive information about the customer and their interactions with AWS. The Lead context includes: **Complete Customer Profile:** + All company information from the original invitation + Full contact details for all customer interactions (name, email, phone, business title) + AWS maturity level and market segment **Interaction History:** + Multiple customer touch-points consolidated into a single engagement + Each interaction includes source information, customer action, business problem, and contact details + Interactions are listed chronologically to provide a complete customer journey view **Qualification Status:** + Current state of lead qualification (Unqualified, Qualified, Disqualified, or custom status) + Partners can update this status as they progress through their qualification process This comprehensive view enables partners to understand the customer's complete engagement history across multiple AWS campaigns and touchpoints, rather than treating each interaction as a separate lead. ### Listing Active Leads Partners can retrieve all their active leads using the `ListEngagements` API action with the `contextType` filter set to `Lead`. This returns engagements where the partner is a member and the engagement contains a Lead context. The list response includes key information such as: + Engagement ID and title + Customer company name + Current engagement score + Qualification status + Number of interactions + Creation and modification timestamps Partners can use this list to build dashboards, track lead pipeline health, and identify leads requiring attention. ### Updating Lead Information As partners nurture leads and gather additional information, they can update lead details using the `UpdateEngagementContext` API action. This action allows partners to modify the Lead context within the engagement. Partners can update: **Qualification Status:** Partners should update the qualification status as they progress through their internal qualification process: + **Unqualified**: Default status after accepting a lead; indicates the lead requires evaluation + **Qualified**: Lead meets qualification criteria and shows high potential for conversion to an opportunity + **Disqualified**: Lead does not meet criteria or is not a good fit for the partner's solutions + **Custom States**: Partners can define their own qualification states to match their internal processes **Lead Metadata:** Partners can add or update additional information relevant to their qualification and nurturing processes. Updating qualification status helps partners track lead progression, generate accurate pipeline reports, and identify leads ready for conversion to opportunities. ### Monitoring AWS Updates AWS may update lead information based on new customer engagement signals or refined engagement scoring. When AWS updates the engagement, partners receive an `Engagement Updated` event via Amazon EventBridge. These updates may include: + Refined engagement scores based on new customer activity + Additional customer interactions from new campaigns or touch-points + Updated customer information Partners should monitor these events and call `GetEngagement` to retrieve the latest lead details. This ensures partners have the most current information for prioritizing and nurturing leads. The `Engagement Updated` event includes the `contextTypes` field, allowing partners to filter specifically for leads (engagements with Lead context). ## Converting a Lead to an Opportunity When a lead has been qualified and demonstrates serious buying intent, partners can convert it into an opportunity for formal co-selling collaboration with AWS. This conversion marks the transition from lead nurturing (primarily partner-driven) to opportunity management (collaborative with AWS). ### Recommended Approach: Convenience API Partners can streamline the opportunity creation and linking process by using the `StartOpportunityFromEngagementTask` convenience API action. This task API orchestrates multiple actions automatically: 1. Creates a draft opportunity with preliminary information from the lead context 1. Links the opportunity to the source engagement via resource snapshot 1. Adds the CustomerProject context to the engagement This convenience method reduces the number of API calls required and ensures proper attribution tracking. Partners using this approach still need to: + Complete opportunity details using `UpdateOpportunity` + Associate Partner Solutions using `AssociateOpportunity` + Submit the opportunity using `StartEngagementFromOpportunityTask` when ready The convenience API is particularly useful for partners with automated lead-to-opportunity workflows who want to minimize integration complexity. ### Alternative Approach: Step-by-step API **Creating a Draft Opportunity** The first step in converting a lead is creating a draft opportunity using the `CreateOpportunity` API action. This creates an opportunity with the `Lifecycle.ReviewStatus` set to `Pending Submission`. At this stage, the opportunity is not yet submitted to AWS for validation. Partners should populate the opportunity with information gathered during lead nurturing, including: + Customer account details + Project information and business problem + Expected customer spend + Target close date + Any other relevant details collected during qualification The draft opportunity allows partners to prepare complete information before submitting to AWS, ensuring higher approval rates and faster validation. **Linking Opportunity to Lead Engagement** After creating the draft opportunity, partners must link it to the source lead engagement using the `CreateResourceSnapshot` API action. This step is critical for: + **Attribution Tracking**: Establishes the provenance chain from lead invitation through opportunity closure, enabling accurate ROI calculation for marketing campaigns and lead sources. + **Conversion Metrics**: Allows AWS and partners to measure lead-to-opportunity conversion rates and identify successful lead sources. + **Context Preservation**: Maintains the complete customer journey history, including all original interactions and engagement signals. When creating the resource snapshot, partners specify: + The engagement ID (source lead engagement) + The opportunity identifier + The resource type (Opportunity) This action automatically adds a CustomerProject context to the engagement, signaling that the lead has been converted to an active opportunity. The engagement now contains both the original Lead context (preserving history) and the new CustomerProject context (indicating active opportunity). **Completing Opportunity Details** Once the opportunity is created and linked, partners must complete additional opportunity requirements before submission. See the `AssociateOpportunity` API action for details. Updating Project Details: Partners can use the `UpdateOpportunity` API action to refine project information, customer business problems, expected spend, and other relevant details gathered during lead qualification. **Submitting the Opportunity** Once all required information is complete, partners submit the opportunity for AWS validation using the `StartEngagementFromOpportunityTask` convenience API. This transitions the opportunity from draft status to the AWS review process. Validation Requirement: The engagement must have a CustomerProject context before submission. This context is automatically created when using `CreateResourceSnapshot` to link the opportunity to the engagement. If this context is missing, the submission will fail. After submission: + The opportunity's `Lifecycle.ReviewStatus` changes to `Submitted` + The lead is classified as a Partner Sales Qualified Lead (PSQL) in AWS systems + AWS begins validation to ensure opportunity details are accurate and complete + No changes can be made to the opportunity until the review process is complete The opportunity then follows the standard validation workflow described in the "Working with your opportunities" documentation, progressing through states such as In-Review, Action Required, Approved, or Disqualified. # Working with deal sizing insights ## What is Deal Sizing? Deal Sizing is a capability within the APN Customer Engagements (ACE) Opportunities in AWS Partner Central that uses AI to provide automated deal size estimates and AWS service recommendations when Partners create or update opportunities. ### AI forecasted MRR estimates Deal sizing insights provide the median of the forecasted monthly recurring revenue (MRR) ranges based on Partners' historical AWS opportunities, use cases, and business descriptions. Partners should review and update the total MRR as Partners gather more information about the deal and progress through the sales cycle. ### AI-Recommended AWS Products AI-recommended products are identified based on customer business problem descriptions and opportunity details. The AI recommends relevant AWS products aligned with technical requirements and use cases. Partners should review these suggestions and customize the product selection to match the customer's specific needs. ### Enhanced Insights with Pricing Calculator URLs Partners can also import AWS Pricing Calculator URLs to automatically populate service selections and receive enhanced insights including Migration Acceleration Program (MAP) eligibility indicators, optimization recommendations, and potential cost savings analysis. ## Understanding Source-Separated Data Deal Sizing provides insights from two separate sources to give you comprehensive visibility into opportunity value: + **AWS Source:** AI-recommended products based on patterns from similar historical opportunities + **Partner Source:** Your own estimates imported from AWS Pricing Calculator ### Handling Variance Between Sources When partner-provided estimates differ significantly from AWS recommendations, Partners should: 1. Review opportunity details to ensure all relevant information is captured 1. Verify Pricing Calculator URL configurations match actual requirements 1. Consider AWS recommendations as data points informed by similar historical opportunities 1. Make informed decisions based on specific customer context and requirements ## Accessing Deal Sizing Insights Partners access Deal Sizing data through the `GetAwsOpportunitySummary` API action, which returns an extended `AwsOpportunitySummary` object containing deal sizing forecasts, product recommendations, and optimization insights. ### When Deal Sizing Data Becomes Available Deal Sizing insights become available after an opportunity is created with sufficient customer and project details. The system analyzes the opportunity attributes and generates: 1. **AI forecasted MRR:** Automatically calculated based on opportunity characteristics 1. **AWS product recommendations:** Services relevant to the customer's business problem and technical requirements 1. **Enhanced insights (when Pricing Calculator URL provided):** MAP eligibility, optimization recommendations, and cost savings analysis **Note** Deal Sizing insights are not available for all opportunities. Eligibility depends on factors such as partner history and the completeness of opportunity details provided. ## Providing Deal Sizing Inputs Partners provide inputs for Deal Sizing through the `CreateOpportunity` and `UpdateOpportunity` API actions. The system uses opportunity attributes to generate recommendations. ### Providing Manual MRR Estimates Partners can manually enter MRR estimates using the `Project.ExpectedCustomerSpend[].Amount` field: **Note** The `CurrencyCode` field accepts `USD` and `EUR`. If the AWS Partition is `aws-eusc` (AWS European Sovereign Cloud), the currency code must be `EUR`. ``` { "Project": { "ExpectedCustomerSpend": [ { "Amount": "25000.00", "CurrencyCode": "USD", "Frequency": "Monthly", "TargetCompany": "AWS" } ] } } ``` This field is available to all Partners and can be used to accept AI forecasts by setting the same value or to override with Partner-provided values. ### Providing Pricing Calculator URLs Partners can optionally provide AWS Pricing Calculator URLs via the `Project.ExpectedCustomerSpend[].EstimationUrl` field to automatically import service configurations and receive enhanced insights including MAP eligibility indicators, optimization recommendations, and cost savings analysis. ``` { "Project": { "ExpectedCustomerSpend": [ { "Amount": null, "CurrencyCode": "USD", "EstimationUrl": "https://calculator.aws/#/estimate?id=abc123", "Frequency": "Monthly", "TargetCompany": "AWS" } ] } } ``` When a valid Pricing Calculator URL is provided, the system automatically calculates the MRR amount from the calculator configuration and populates both the Amount field and detailed product-level spend data in the Partner source of `AwsProductsSpendInsightsBySource`. Partners should set Amount to null when supplying an EstimationUrl - the system will calculate it automatically. URLs in invalid formats and URLs that cannot be resolved will be rejected with a `ValidationException`. ### How Amount and EstimationUrl Work Together You have flexibility in how you provide monthly recurring revenue (MRR) estimates for opportunities. The API intelligently handles various combinations of manual amounts and AWS Pricing Calculator URLs to ensure that your opportunities can always be created successfully. #### Using only a manual amount When you provide only the Amount field, the API saves your manual estimate and sets EstimationUrl to null. This approach is useful when you have a specific MRR estimate from customer conversations or your own calculations. Example request: ``` { "Project": { "ExpectedCustomerSpend": [{ "Amount": "25000.00", "CurrencyCode": "USD", "Frequency": "Monthly", "TargetCompany": "AWS" }] } } ``` #### Using only an AWS Pricing Calculator URL When you provide only the EstimationUrl field: + **Valid URL** – The API calculates the MRR amount from your calculator configuration and saves both the URL and calculated amount. + **Invalid URL** – The API returns a ValidationException with details about why the URL is invalid. Example request: ``` { "Project": { "ExpectedCustomerSpend": [{ "EstimationUrl": "https://calculator.aws/#/estimate?id=abc123", "CurrencyCode": "USD", "Frequency": "Monthly", "TargetCompany": "AWS" }] } } ``` Example error response (invalid URL): ``` { "ErrorList": [{ "Code": "INVALID_VALUE", "FieldName": "project.expectedCustomerSpend.estimationUrl", "Message": "Invalid Estimation URL: https://calculator.aws/#/estimate?id=invalid" }], "Message": "The provided Estimation URL is invalid", "Reason": "INVALID_VALUE" } ``` #### Providing both Amount and EstimationUrl When you provide both fields, the API prioritizes ensuring that your opportunity is created successfully: 1. If both values are unchanged – no update is performed on these fields 1. URL is invalid – The API saves your provided Amount and sets EstimationUrl to null, allowing your opportunity creation to proceed. 1. URL is valid and calculated amount matches your provided Amount – Both values are saved. 1. URL is valid but calculated amount doesn't match your provided Amount – The API saves your provided Amount and sets EstimationUrl to null without returning an error. **Note** When both values don't match existing ones, the API first attempts to calculate the amount from the URL. Your manually provided Amount always takes precedence when there's a mismatch or validation issue. **Key benefit: Invalid URLs never block opportunity creation** This approach ensures that invalid or inaccessible AWS Pricing Calculator URLs never prevent you from creating or updating opportunities. Your manually provided Amount always takes precedence when there's a conflict or validation issue, giving you full control over your opportunity data. ## Understanding the Extended AwsOpportunitySummary Data Model This section describes the response structure returned by the `GetAwsOpportunitySummary` API action. **Note** AI-forecasted MRR is returned in `Project.ExpectedCustomerSpend[].Amount` The `GetAwsOpportunitySummary` API action returns deal sizing insights through the new `Insights.AwsProductsSpendInsightsBySource` structure that provides comprehensive spend analysis with source attribution. ### Source Separation: AWS vs Partner Data Deal Sizing separates insights by source to provide transparency and prevent double-counting: + **AWS Source:** AI product recommendations from AWS + **Partner Source:** Spend data and product details imported from partner-provided Pricing Calculator URLs This separation enables Partners to: 1. Compare their estimates against AWS recommendations 1. Validate their sizing assumptions 1. Avoid inflating totals by accidentally combining both sources 1. Maintain visibility into data provenance ### Structure Overview ``` { "Insights": { "AwsProductsSpendInsightsBySource": { "": { "CurrencyCode": "string", "Frequency": "string", "TotalAmount": "string", "TotalOptimizedAmount": "string", "TotalPotentialSavingsAmount": "string", "TotalAmountByCategory": { }, "AwsProducts": [ ] } } }, "Project": { "ExpectedCustomerSpend": [ ] }, "RelatedEntityIds": { "AwsProducts": [ ] } } ``` ### Field Reference #### AwsProductsSpendInsightsBySource Map Source-separated spend insights that provide independent analysis for AWS recommendations and partner estimates. The `Insights.AwsProductsSpendInsightsBySource` field is a map containing up to two keys: | Key | Type | Description | | --- | --- | --- | | AWS | AwsProductsSpendInsights | AI-generated insights including recommended products from AWS | | Partner | AwsProductsSpendInsights | Partner-sourced insights derived from Pricing Calculator URLs including detailed service costs and optimizations | **Note** Only sources with available data are included in the response. New opportunities typically start with only the AWS source populated. #### AwsProductInsights Object Comprehensive spend analysis for a single source (AWS or Partner) including total amounts, optimization savings, program category breakdowns, and detailed product-level insights. Each source object contains the following fields: | Field | Type | Description | | --- | --- | --- | | CurrencyCode | string | ISO 4217 currency code. Supported values are "USD" and "EUR". | | Frequency | string | Indicates how frequently the customer is expected to spend the projected amount. Only the value Monthly is allowed for the Frequency field, representing recurring monthly spend. | | TotalAmount | string | Total estimated spend for this source before optimizations | | TotalOptimizedAmount | string | Total estimated spend after applying recommended optimizations | | TotalPotentialSavingsAmount | string | Quantified savings achievable through implementing optimizations | | TotalAmountByCategory | object | Spend amounts mapped to AWS programs and modernization pathways | | AwsProducts | array | Product-level details including costs and optimization recommendations | **Current State Limitation:** For the AWS source, TotalAmount, TotalOptimizedAmount, and TotalPotentialSavingsAmount may be omitted when per-product spend recommendations are not available. Partners should reference `Project.ExpectedCustomerSpend[].Amount` for the total AWS MRR estimate in these cases. #### TotalAmountByCategory Object Maps spend amounts to AWS programs and strategic initiatives: | Category Key | Description | | --- | --- | | MAP Eligible | Spend on services eligible for Migration Acceleration Program funding | | CAT Eligible | Services supporting cost allocation and tracking | | Pathway - Move to Cloud Native | Services aligned with cloud-native modernization | | Pathway - Move to Managed Services | Services supporting managed service adoption | | Pathway - Move to Open Source | Open source service alternatives | | Pathway - Move to Containers | Container-based service options | | Pathway - Move to Serverless | Serverless computing services | | Pathway - Move to Databases | Database modernization services | | Pathway - Move to Analytics | Analytics and data processing services | **Note** Total category amounts may exceed TotalAmount because individual products can belong to multiple categories. #### AwsProducts Array List of AWS services with program eligibility indicators (MAP, modernization pathways), cost estimates, and optimization recommendations. Each product object contains: | Field | Type | Required | Description | | --- | --- | --- | --- | | ProductCode | string | Yes | AWS Partner Central product identifier used for opportunity association | | ServiceCode | string | No | Pricing Calculator service code (links to original calculator URL) | | Categories | array | Yes | List of program and pathway categories this product is eligible for | | Amount | string | No | Baseline service cost before optimizations (may be null for AWS-sourced recommendations) | | OptimizedAmount | string | No | Service cost after applying optimizations (may be null for AWS-sourced recommendations) | | PotentialSavingsAmount | string | No | Service-specific cost reduction through optimizations (may be null for AWS-sourced recommendations) | | Optimizations | array | No | List of specific optimization recommendations for this product | **Null Handling:** For AWS-sourced products, Amount, OptimizedAmount, and PotentialSavingsAmount fields may be null when per-product spend recommendations are not available. The system provides total MRR via `Project.ExpectedCustomerSpend[0].Amount` instead. #### Optimization Object Each optimization recommendation contains: | Field | Type | Description | | --- | --- | --- | | Description | string | Human-readable explanation of the optimization strategy | | SavingsAmount | string | Quantified cost savings achievable by implementing this optimization | ### Examples #### Example 1: AWS recommendations Only (Current State) This example shows the typical response when only AI recommendations are available and per-product spend amounts cannot yet be recommended. ``` { "Catalog": "AWS", "Insights": { "AwsProductsSpendInsightsBySource": { "AWS": { "CurrencyCode": "USD", "Frequency": "Monthly", "AwsProducts": [ { "ProductCode": "AmazonEC2", "Categories": ["MAP Eligible", "Cost Allocation Tagging"], "Amount": null, "OptimizedAmount": null, "PotentialSavingsAmount": null, "Optimizations": [] }, { "ProductCode": "AWSLambda", "Categories": ["Cost Allocation Tagging", "Pathway - Move to Cloud Native"], "Amount": null, "OptimizedAmount": null, "PotentialSavingsAmount": null, "Optimizations": [] }, { "ProductCode": "AmazonRDS", "Categories": ["MAP Eligible", "Cost Allocation Tagging", "Pathway - Move to Managed Services"], "Amount": null, "OptimizedAmount": null, "PotentialSavingsAmount": null, "Optimizations": [] } ] } } }, "Project": { "ExpectedCustomerSpend": [ { "Amount": "28000.00", "CurrencyCode": "USD", "EstimationUrl": null, "Frequency": "Monthly", "TargetCompany": "AWS" } ] }, "RelatedEntityIds": { "AwsProducts": [ "AmazonEC2", "AWSLambda", "AmazonRDS" ] } } ``` **Key Points:** AWS source shows recommended products with categories but no per-product amounts. Total MRR estimate available via `Project.ExpectedCustomerSpend[].Amount`. #### Example 2: Partner Pricing Calculator Import This example shows enhanced insights when a partner has provided a valid Pricing Calculator URL. ``` { "Catalog": "AWS", "Insights": { "AwsProductsSpendInsightsBySource": { "Partner": { "CurrencyCode": "USD", "Frequency": "Monthly", "TotalAmount": "32500.00", "TotalOptimizedAmount": "30000.00", "TotalPotentialSavingsAmount": "2500.00", "TotalAmountByCategory": { "MAP Eligible": "22500.00", "Cost Allocation Tagging": "32500.00", "Pathway - Move to Cloud Native": "5000.00", "Pathway - Move to Managed Services": "7500.00" }, "AwsProducts": [ { "ServiceCode": "ec2", "Categories": ["MAP Eligible", "Cost Allocation Tagging"], "Amount": "15000.00", "OptimizedAmount": "13500.00", "PotentialSavingsAmount": "1500.00", "Optimizations": [ { "Description": "Convert to 3-year reserved instances", "SavingsAmount": "1000.00" }, { "Description": "Migrate to Graviton-based instances", "SavingsAmount": "500.00" } ] }, { "ServiceCode": "lambda", "Categories": ["Cost Allocation Tagging", "Pathway - Move to Cloud Native"], "Amount": "5000.00", "OptimizedAmount": "5000.00", "PotentialSavingsAmount": "0.00", "Optimizations": [] }, { "ServiceCode": "AmazonRDS", "Categories": ["MAP Eligible", "Cost Allocation Tagging", "Pathway - Move to Managed Services"], "Amount": "7500.00", "OptimizedAmount": "6500.00", "PotentialSavingsAmount": "1000.00", "Optimizations": [ { "Description": "Optimize Multi-AZ for dev/test environments", "SavingsAmount": "1000.00" } ] }, { "ServiceCode": "AmazonS3", "Categories": ["MAP Eligible", "Cost Allocation Tagging"], "Amount": "5000.00", "OptimizedAmount": "5000.00", "PotentialSavingsAmount": "0.00", "Optimizations": [] } ] } } }, "Project": { "ExpectedCustomerSpend": [ { "Amount": "32500.00", "CurrencyCode": "USD", "EstimationUrl": "https://calculator.aws/#/estimate?id=abc123", "Frequency": "Monthly", "TargetCompany": "AWS" } ] }, "RelatedEntityIds": { "AwsProducts": [] } } ``` **Key Points:** Partner source contains complete spend details with per-product amounts. Optimization recommendations provide actionable cost reduction strategies. Category breakdowns show MAP eligibility (\$122,500 of \$132,500 total). Products include ServiceCode linking back to Pricing Calculator configuration. #### Example 3: Both Sources Present (Comparison Scenario) This example demonstrates how both AWS recommendations and partner estimates appear together, enabling comparison. ``` { "Catalog": "AWS", "Insights": { "AwsProductsSpendInsightsBySource": { "AWS": { "CurrencyCode": "USD", "Frequency": "Monthly", "AwsProducts": [ { "ProductCode": "AmazonEC2", "Categories": ["MAP Eligible", "Cost Allocation Tagging"], "Amount": null, "OptimizedAmount": null, "PotentialSavingsAmount": null, "Optimizations": [] }, { "ProductCode": "AWSLambda", "Categories": ["Cost Allocation Tagging", "Pathway - Move to Cloud Native"], "Amount": null, "OptimizedAmount": null, "PotentialSavingsAmount": null, "Optimizations": [] }, { "ProductCode": "EBS", "Categories": ["MAP Eligible", "Cost Allocation Tagging"], "Amount": null, "OptimizedAmount": null, "PotentialSavingsAmount": null, "Optimizations": [] }, { "ProductCode": "RDS", "Categories": ["MAP Eligible", "Cost Allocation Tagging", "Pathway - Move to Managed Services"], "Amount": null, "OptimizedAmount": null, "PotentialSavingsAmount": null, "Optimizations": [] } ] }, "Partner": { "CurrencyCode": "USD", "Frequency": "Monthly", "TotalAmount": "32500.00", "TotalOptimizedAmount": "30000.00", "TotalPotentialSavingsAmount": "2500.00", "TotalAmountByCategory": { "MAP Eligible": "22500.00", "Cost Allocation Tagging": "32500.00", "Pathway - Move to Cloud Native": "5000.00", "Pathway - Move to Managed Services": "7500.00" }, "AwsProducts": [ { "ServiceCode": "ec2", "Categories": ["MAP Eligible", "Cost Allocation Tagging"], "Amount": "15000.00", "OptimizedAmount": "13500.00", "PotentialSavingsAmount": "1500.00", "Optimizations": [ { "Description": "Convert to 3-year reserved instances", "SavingsAmount": "1000.00" } ] }, { "ServiceCode": "lambda", "Categories": ["Cost Allocation Tagging", "Pathway - Move to Cloud Native"], "Amount": "5000.00", "OptimizedAmount": "5000.00", "PotentialSavingsAmount": "0.00", "Optimizations": [] }, { "ServiceCode": "amazonRDS", "Categories": ["MAP Eligible", "Cost Allocation Tagging", "Pathway - Move to Managed Services"], "Amount": "7500.00", "OptimizedAmount": "6500.00", "PotentialSavingsAmount": "1000.00", "Optimizations": [ { "Description": "Optimize Multi-AZ for dev/test environments", "SavingsAmount": "1000.00" } ] }, { "ServiceCode": "amazonS3", "Categories": ["MAP Eligible", "Cost Allocation Tagging"], "Amount": "5000.00", "OptimizedAmount": "5000.00", "PotentialSavingsAmount": "0.00", "Optimizations": [] } ] } } }, "Project": { "ExpectedCustomerSpend": [ { "Amount": "28000.00", "CurrencyCode": "USD", "EstimationUrl": "https://calculator.aws/#/estimate?id=abc123", "Frequency": "Monthly", "TargetCompany": "AWS" } ] }, "RelatedEntityIds": { "AwsProducts": [ "AmazonEC2", "AWSLambda", "EBS", "RDS" ] } } ``` **Key Points:** Both sources present: AWS recommendations (\$128K total) and Partner calculator (\$132.5K total). AWS recommendations show 4 products; Partner calculator shows 4 products (3 overlapping). Partners can compare AWS recommendations against their detailed estimates. AWS total available via `Project.ExpectedCustomerSpend[].Amount`. ### Best Practices #### Handling Null Values 1. **EstimationUrl Field:** Expect EstimationUrl to be null for most Partners. This is standard behavior and should not be treated as an error. Display manual MRR entry options as the primary path. 1. **Missing Categories:** If TotalAmountByCategory is not present for the AWS source, this indicates per-product recommendations are not available. Category breakdowns are available for Partner-sourced data when Pricing Calculator URLs are provided. #### Optimization Recommendations 1. **Display Actionable Insights:** Show optimization descriptions and savings amounts prominently to help Partners understand cost reduction opportunities. 1. **Aggregate Savings:** Sum PotentialSavingsAmount across products to show total optimization potential. 1. **Prioritize by Impact:** Sort optimizations by SavingsAmount to help Partners focus on highest-impact recommendations. #### Monitoring for Updates 1. **Poll Periodically:** Poll `GetAwsOpportunitySummary` periodically (recommended: every 5 minutes) during opportunity creation workflows. 1. **Handle Async Generation:** Deal Sizing insights may not be immediately available after opportunity creation. Implement appropriate loading states and retry logic. #### API Integration Patterns 1. **Leverage Existing Integrations:** Partners already calling `GetAwsOpportunitySummary` only need to consume additional fields in the response—no new API calls required. 1. **Graceful Degradation:** Design UIs to handle scenarios where Deal Sizing data is not yet available or incomplete. #### Data Quality and Accuracy 1. **Validate Pricing Calculator URLs:** Ensure URLs are valid before submission to avoid null EstimationUrl responses. 1. **Provide Rich Opportunity Details:** More complete opportunity information (customer details, project description, technical requirements) yields more accurate AI recommendations. 1. **Review Variance:** When partner estimates differ significantly from AWS recommendations, review opportunity details to ensure all relevant context is captured. # Best practices ## Reacting to events When handling events from AWS Partner Central API, ensure that your processing logic is idempotent to handle duplicate events. Instead of making immediate [GetOpportunity](API_Operations.md) calls for each event, consider batching or selectively fetching details based on your application's needs. For uninterrupted operations, beware of [Quotas](quotas.md). ## Implementing optimistic locking Optimistic locking prevents unintended data overrides during concurrent updates. Here's a typical scenario: 1. Partner retrieves an opportunity from their CRM system. 1. User `A` updates the opportunity on AWS Partner Central. 1. User `B` updates the same opportunity at the same time through the CRM integration. 1. If the data changes, the CRM system attempts to upload the data but returns a `ConflictException`. 1. User reviews the error and manually resolves conflicting data. To avoid this scenario, all [UpdateOpportunity](API_UpdateOpportunity.md) requests must include the `LastModifiedDate` parameter, which you can obtain from previous [CreateOpportunity](API_CreateOpportunity.md), [UpdateOpportunity](API_UpdateOpportunity.md), and [GetOpportunity](API_GetOpportunity.md) actions. The update succeeds only if `LastModifiedDate` matches our system. If it doesn't, you must fetch the latest `LastModifiedDate` using [GetOpportunity](API_GetOpportunity.md) and reattempt the update. ## Synchronizing data between CRM and AWS Partner Central It is essential to keep your system synced with the latest data from Partner Central. The following are two strategies to ensure your system reflects the latest data: ### Using events (recommended) 1. Load data using [ListOpportunities](API_ListOpportunities.md). 1. Subscribe to opportunity events. 1. Respond to new opportunities or changes. + When you receive `Opportunity Created`, `Opportunity Updated`, or `Engagement Invitation Accepted` events, use `GetOpportunity` to fetch the latest data. + When you receive `Engagement Invitation Rejected` events, remove the corresponding opportunities. ### Using ListOpportunities polling 1. Load data using [ListOpportunities](API_ListOpportunities.md). 1. Choose a polling frequency, ensuring it is not too frequent to avoid exhausting your daily [ read quota](quotas.md). 1. Identify the latest `LastModifiedDate` from your stored data, ensuring it originates from AWS. 1. Use the timestamp in the `AfterLastModifiedDate` filter when calling [ListOpportunities](API_ListOpportunities.md). ``` { "FilterList": [ { "Name": "AfterLastModifiedDate", "ValueList": [ "2023-05-01T20:37:46Z" ] // Replace with actual timestamp of your last synced data } ] } ``` 1. AWS will return opportunities created or updated after the value indicated on the timestamp. 1. Iterate over all returned pages using `NextToken`, and update your system's data using [GetOpportunity](API_GetOpportunity.md). ``` { "NextToken": "AAMA-EFRSN...PZa942D", "FilterList": [ { "Name": "AfterLastModifiedDate", "ValueList": [ "2023-05-01T20:37:46Z" ] // Replace with actual timestamp of your last synced data } ] } ```