Integrate your CRM system with AWS Partner Central using the AWS Partner Central API

Update changes on 01/16/2024

This blog has been updated to reflect recent changes. The diagram initially in the “Solution Overview” section has been updated and relocated to the “Listening to AWS Partner Central API events using AWS EventBridge” section for enhanced clarity. Additionally, the “Partner Originated (PO) opportunity workflow” diagram has been corrected, and a new “AWS Originated (AO) opportunity workflow” diagram has been included to provide a complete view of the opportunity workflows. AWS Partner Central API Postman collection and GitHub repository links, released around AWS re:Invent 2024, have also been added to support easier API integration.

AWS Partner Central is a self-service portal where AWS Partners manage their sales opportunities with AWS. Many AWS Partners find it beneficial to streamline the management of these engagements by integrating their Customer Relationship Management (CRM) systems with AWS Partner Central.

The AWS Partner Central API automates interactions with Partner Central, which helps partners track joint business activities efficiently. By integrating their CRM systems with AWS Partner Central using the API, partners can synchronize critical components of the sales process, including Opportunities, Engagements, Solutions, and Event Notifications, with real-time data from AWS Partner Central. Partners who integrate enjoy greater consistency and efficiency in managing their relationship with AWS.

In this post, we show you how to programmatically integrate your CRM systems with AWS Partner Central using the AWS Partner Central API. We also demonstrate how to create efficient workflows that provide real-time data synchronization, reduce manual effort, and improve collaboration.

Solution Overview

AWS Partner Central entities represent key business components used in co-selling 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 API.

• Opportunities encapsulates all relevant sales information, such as customer contact details, the business problem, and the proposed solution. For each opportunity in the partner account, there is a corresponding record in the AWS CRM, which is used by AWS sales representatives to manage their own opportunity lifecycle.
• Engagements represents the collaboration between AWS and the partner, where opportunities are shared with participants. Partners receive engagement invitations, which invite them to join these collaborations.
• Solutions are the partner’s offering. Partners can list all the solutions in their Partner Central account using the ListSolutions action.

In this solution, we use the AWS Partner Central API to view the opportunity pipeline. Then we explore actions for partner originated opportunities and AWS originated opportunities. Finally, we explain how to use the selling API events with Amazon EventBridge to receive real-time notifications about status or detail changes in opportunities.

Prerequisites

To enable CRM integration with Partner Central via AWS Partner Central API, you must meet the following prerequisites:

1. You must have an AWS Marketplace seller account
2. You need an AWS Identity and Access Management (IAM) role and/or an IAM user to make API calls. Associate the AWSPartnerCentralOpportunityManagement managed policy to gain access to the API.
3. Your AWS Marketplace Seller account (where you created the IAM role/user) must be linked to your AWS Partner Central account.

Streamlining CRM integration with AWS Partner Central

In the following examples, we demonstrate three actions required for streamlining CRM integration using the Partner Central API.

• Viewing the opportunity pipeline
• Working with Partner Originated opportunities
• Working with AWS Originated opportunities

To make requests using the API, you can use your preferred development tool configured with the following request parameters:

• API Endpoint URL – https://partnercentral-selling.us-east-1.api.aws
• Authorization
  • Type – AWS (Configure with the credentials you set up in prerequisites)
  • Service Name – partnercentral-selling
  • Region – us-east-1
• Headers – X-Amzn-User-Agent: CompanyName|ProductName|CRMName|ProductVersion

Before proceeding, understand that the API supports a Sandbox mode. When making API requests in this section, verify that the Catalog value is set to Sandbox to avoid making changes in production.

{
    "Catalog": "Sandbox",
    "Identifier": "01111111"
}

Viewing the opportunity pipeline

For partners managing a high volume of opportunities, the ListOpportunities action with filters enables rapid querying of opportunities in bulk, providing a seamless way to synchronize data with your CRM in near real-time. You can use the ListOpportunities action with the following JSON request payload:

{
   "Catalog": "AWS",
   "MaxResults": 20
}

For a complete list of filters, refer to ListOpportunities API action.

Working with Partner Originated opportunities

The following steps show, at a high level, how to create and submit a business opportunity to AWS.

1. Use CreateOpportunity to create the opportunity.
2. Use ListSolutions to get a complete list of solutions among which you can choose a Solution ID.
3. Use AssociateOpportunity to associate a solution with the opportunity.
4. Use StartEngagementFromOpportunityTask to submit the opportunity for review.

Step 1: CreateOpportunity

Use the sample JSON payload to create an opportunity using CreateOpportunity action.

This API call will return the following JSON response with an HTTP 200 status code:

{
	"Id": "O1111111,
	"LastModifiedDate": "2024-07-03T22:37:29Z",
	"PartnerOpportunityIdentifier": null
}

The ID field contains the newly created opportunity identifier. When you create an opportunity, it is added to your account but has not yet been submitted to AWS.

Step 2: Querying the list of solutions

Once you have the opportunity created in the Pending status, you will need to associate a solution. Use the ListSolutions action。

{ 
    "Catalog": "AWS",
    "MaxResults": 20
}

The response should be as follows:

{
	"NextToken": null,
	"SolutionSummaries": [
		{
			"Arn": "arn:aws:partnercentral:us-east-1:123456789012:catalog/AWS/solution/S-0000001",
			"Catalog": "AWS",
			"Category": "Software Product",
			"CreatedDate": "2024-01-24T07:08:31Z",
			"Id": "S-0000001",
			"Name": "SampleSolution1",
			"Status": "Inactive"
		},
. . .
	]
}

Step 3: Associating the solutions to the opportunity

Choose a solution from the solution list. Use the AssociateOpportunity action to associate the solution with the opportunity. Update the value in RelatedEntityIdentifier field with the solution ID you obtained earlier.

{
   "Catalog": "AWS",
   "OpportunityIdentifier": "O1111111",
   "RelatedEntityIdentifier": " S-0000002",
   "RelatedEntityType": "Solutions"
}

If the action is successful, the service sends back an HTTP 200 status code with an empty HTTP body. Optionally, you can associate AWS Products or AWS Marketplace private offers associated with this opportunity.

Step 4: Starting an Engagement with the Opportunity

Use StartEngagementFromOpportunityTask action to initiate the engagement process from an existing opportunity. This action creates an Engagement and invites AWS to collaborate on the opportunity. This is equivalent to submission.

{
   "AwsSubmission": { 
      "InvolvementType": "Co-Sell",
      “Visibility”: “Full”
   },
   "Catalog": "AWS",
   "ClientToken": "xyz9876-abcd-4321-efgh-5678ijklmnop",
   "Identifier": "O1111111"
}

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Once StartEngagementFromOpportunityTask action is initiated, the opportunity cannot be edited until the review is complete. For information on updating opportunity, please refer to the Working with Opportunity Updates in the API reference documentation.

Step 5: Getting opportunity details and updating

Once the opportunity is approved by AWS, partners can use GetOpportunity and GetAwsOpportunitySummary actions to retrieve the details of opportunity. Partners can also continue to update the opportunity as needed using the UpdateOpportunity action.

The GetAwsOpportunitySummary action allows partners to retrieve a summary of the opportunity details as recorded in the AWS CRM.

The diagram in Figure 1 maps the Partner Originated (PO) opportunity workflow and shows how events flow to Amazon EventBridge.

Figure 1: Partner Originated (PO) Opportunity workflow

Working with AWS Originated opportunities

When an AWS sales representative shares an opportunity with a partner, the partner receives an Engagement Invitation Created event notification from AWS. Partners can listen to this event. They can then programmatically accept the invitation and engage with AWS from within their CRM. Alternatively, partners can periodically poll for Engagement Invitations using the ListEngagementInvitations action. Let us look at how this works.

Step 1: Get the engagement invitation using the API

Listening to Amazon EventBridge Events for Selling API

Upon receiving an Engagement Invitation Created event, partners can get the EngagementInvitation ID Amazon Resource Name (ARN) from the Amazon EventBridge event. Listening to Selling API events requires setting up an EventBridge rule. For detailed information setting up an EventBridge rule, refer to the Working with selling API events reference.

Integrate with Partner Central API

Partners can use GetEngagementInvitation action to retrieve details of the AWS Opportunity with the following JSON request payload:

{
   "Catalog": "AWS",
   "Identifier": "arn:aws:partnercentral:us-east-1:aws:catalog/AWS/engagement-invitation/engi-zxCwxvAga"
}

The response provides the engagement invitation shared by AWS with the partner. This allows the partner to decide whether or not to accept the invitation to collaborate on the opportunity.

Partners can also use ListEngagementInvitations action to see all open invitations in their account. The ListEngagementInvitations action gives a range of filters that allow you to narrow the results to only those invitations that you wish to see. See the following JSON request payload:

{
    "Catalog": "AWS",
    "MaxResults": 20,
    "NextToken": null,
    "ParticipantType": "RECEIVER",
    "PayloadType": [
        "OpportunityInvitation"
    ],
    "Sort": {
        "SortBy": "InvitationDate",
        "SortOrder": "DESCENDING"
    }
}

You can find the Engagement Invitation ID from the list returned from the API request.

Step 2: Start the engagement by accepting invitation task

The partner can use the StartEngagementByAcceptingInvitationTask action to engage on the opportunity. This action accepts the engagement invitation, and starts the engagement with AWS. See the following JSON request payload:

{
	"Catalog": "AWS",
	"Identifier": "arn:aws:partnercentral:us-east-1:aws:catalog/AWS/engagement-invitation/engi-0000001abc3de",
	"ClientToken": "test-annjqwe"
}

The API request will return the following JSON payload:

{
    "EngagementInvitationId": "arn:aws:partnercentral:us-east-1::catalog/AWS/engagement-invitation/engi-0000001abc3de",
    "Message": null,
    "OpportunityId": "O1111111",
    "ReasonCode": null,
    "ResourceSnapshotJobId": null,
    "StartTime": "2024-11-15T00:00:25Z",
    "TaskArn": null,
    "TaskId": null,
    "TaskStatus": "COMPLETE"
}

Step 3: Updating the opportunity

In the case of partner needing to update the stage of the opportunity to Technical Validation, they can use UpdateOpportunity action to update the existing opportunity with this sample JSON payload.

The diagram in Figure 2 maps the AWS Originated (AO) opportunity workflow, and also shows how events flow to Amazon EventBridge.

Figure 2: AWS Originated (AO) Opportunity workflow

Listening to AWS Partner Central API events using AWS EventBridge

AWS Partner Central API events allow partners to automate and streamline their workflows. With these events, partners can trigger actions in their own systems, making their operations more efficient and responsive. For example, partners can use events to send automated emails, push notifications on Slack, or initiate workflows within their CRM systems.

Consider a scenario where an AWS referral comes in—partners can instantly identify the territory, assign the opportunity to the appropriate sales representative, and ensure immediate follow-up. In addition, a notification containing the most critical information can be sent to the relevant stakeholders, ensuring quick action. You can even prioritize opportunities based on the AWS Marketplace Engagement Score, focusing on high-potential leads.

The diagram in Figure 3 shows an example event flow between AWS Partner Central and the Partner CRM for AWS originated opportunities.

Figure 3: Example event flow between AWS Partner Central and Partner CRM for AWS originated opportunities

You can create an EventBridge rule using one of the following methods:

1. Using the Amazon EventBridge console

Follow the steps on Creating Amazon EventBridge rules that react to events in the Amazon EventBridge guide to set up an EventBridge rule through the AWS Management Console.

2. Using the AWS SDK

You can also create and manage EventBridge rules programmatically using the AWS SDKs. For an example on how to do this using the AWS SDK for Python (Boto3), refer to Working with selling API events.

Types of events

The following real-time notifications will be available to you through the AWS Partner Central API events:

• Opportunity Created: Triggered when a new opportunity is created.
• Opportunity Updated: Triggered when an opportunity (Opportunity or its corresponding AWS Opportunity Summary) is updated.
• Engagement Invitation Created: Triggered when an AWS Referral invitation is created.
• Engagement Invitation Accepted: This event is triggered when a partner accepts an AWS Engagement Invitation, confirming their interest in collaborating with AWS on the opportunity.
• Engagement Invitation Rejected: This event is triggered when an AWS Engagement Invitation is rejected.

Example “Opportunity Created” event

The following JSON shows a sample Opportunity Created event that will be triggered on opportunity creation:

{
    "version": "1",
    "id": "d1example-0c9c-4655-15bf-c5exampleb08",
    "source": "aws.partnercentral-selling",
    "detail-type": "Opportunity Created",
    "time": "2023-10-28T13:31:05Z",
    "region": "us-east-1",
    "account": "123456789123",
    "detail": { 
        "schemaVersion": "1",
        "catalog": "AWS",
        "opportunity": {
            "identifier": "O1234567"
        }
    }
}

Example EventBridge Rule

The following example rule can be used to receive all events from the Partner Central API:

{
    "source": ["aws.partnercentral-selling"]
}

For details on creating Amazon EventBridge rules, refer to Creating rules that react to events in Amazon EventBridge.

Example event processing Lambda

You can use a Lambda function to process the events from Amazon EventBridge. This sample code shows how to handle different event types and execute corresponding actions.

Cleanup

To avoid ongoing charges, delete the resources you created.

In the EventBridge console, select the rule you created and click Delete. In the Lambda console, select the Lambda function you created, select the Actions button, and delete it.

Conclusion

The AWS Partner Central API enables AWS Partners to seamlessly integrate and automate workflows within their own CRM systems. Whether coding directly to API endpoints or using AWS SDKs, Partners can tailor solutions to fit their platforms. Additionally, event-driven workflows provide further opportunities for automation. For practical examples and guidance, explore the AWS Partner Central API Sample Code Library repository, and refer to the AWS Partner Central API Documentation.

Additional Resources

• AWS Partner Central API Reference
• Linking AWS Partner Central accounts with AWS Marketplace Seller accounts
• AWS Marketplace product management for sellers using Postman API Collections
• AWS Partner Central API sample codes in GitHub
• AWS Partner Central API Collections on Postman Network

About the authors

Kenneth Walsh

Kenneth Walsh is a New York-based Solutions Architect whose focus is AWS Marketplace. Kenneth is passionate about cloud computing and loves being a trusted advisor for his customers. When he’s not working with customers on their journey to the cloud, he enjoys cooking, audio books, movies, and spending time with his family and dog.

Ming Zhu

Ming Zhu is a Marketplace Specialist Solution Architect who focuses on supporting sellers to list their products on AWS Marketplace. Her responsibilities focus on automating and streamlining the partners’ onboarding experience. Besides work, her favorite things to do are swimming, traveling and cooking.

Akshay Menon

Akshay Menon is a Senior Product Manager focused on building products that help AWS Partners streamline and automate their partnership activities with AWS. His work spans CRM Integration, AWS Partner Central APIs and Slack-based collaboration tools. Akshay is an avid podcast listener.