📘

Buy with Prime API is now available for early access

Sign up for early access to the Buy with Prime API using the 'Sign Up' button below. The API may change as Amazon receives feedback and iterates on it.

Sign Up

The event consumer SDK for Buy with Prime helps the Salesforce OMS receive updates from the backend related to order fulfillment.

Prerequisites

Before configuring the event consumer SDK, do the following.

Create a connected app for Buy with Prime

In your Salesforce organization, create a Salesforce connected app for Buy with Prime. For details, see Create Your Salesforce Connected App for Buy with Prime.

Log in to the AWS Management Console

In a browser, log in to the Amazon Web Services (AWS) Management Console and keep the console open for next steps.

Install NPM

Install Node.js version 14.19 or later. For details about downloading and installing Node.js, see the Node.js website.

The codebase for the event consumer SDK uses TypeScript, compiled using tools managed by Node Package Manager (NPM).

Install the AWS CDK CLI tool

To prepare for deploying the event consumer SDK to your AWS instance, install the AWS Cloud Development Kit (CDK) CLI tool. For details about installing the AWS CDK CLI, see What is the AWS CDK?

Authenticate to the AWS CDK CLI

Generate tokens for the AWS Identity and Access Management (IAM) user that is to deploy the event consumer SDK, and use the tokens for authentication to the AWS CDK CLI. For details, see Authenticating using IAM user credentials for the AWS CLI.

Upload credentials for the Salesforce OMS to AWS Secrets Manager

To upload credentials for the Salesforce OMS to AWS Secrets Manager, do the following:

1. In your Salesforce organization, retrieve your consumer key, consumer secret, and the domain URL. For details, see Create Your Salesforce Connected App for Buy with Prime.
2. In the AWS Management Console, navigate to AWS Secrets Manager, and then choose Store a new Secret.
3. For Secret Type, choose Other type of secret.
4. Add the following key-value pairs:
   • Enter a consumerKey key with a value equal to your consumer key.
   • Enter a consumerSecret key with a value equal to your consumer secret.
   • Enter a destinationUrl key with a value equal to the domain URL for your Salesforce organization.
5. (Optional) To manage the encryption yourself, choose an encryption key, otherwise leave the default encryption key.
6. Choose Next, and then for Secret Name enter SFOMSDestinationCredentials-{stageName}, where {stageName} is the name of the deployment stage, for example SFOMSDestinationCredentials-dev or SFOMSDestinationCredentials-prod. If you want, add a description and tags.
7. Choose Next, and then skip the Configure Rotation step by choosing Next.
8. Choose Store.

Clone the event consumer SDK

The event consumer SDK for Buy with Prime is available from a repository on GitHub.

1. To get access to the repository, reach out to your Buy with Prime solutions architect.
2. After you have access, open the following repository:
   Text

   https://github.com/Buy-with-Prime/buy-with-prime-event-hydrator
   

3. Clone the repository.

Update the destination configuration

To update the destination for the event consumer SDK to the Salesforce OMS, do the following:

1. Open the AWS Management Console.
2. Navigate to AWS Secrets Manager.
3. Open the secret that you created, and then copy the Secret ARN.
4. In your buy-with-prime-event-hydrator repository, in the configuration directory, open the destination_config.ts file.
5. Replace <SF_OMS_DESTINATION_API_SECRETS_ARN> with the ARN.
6. Save the destination_config.ts file.

Update the source configuration

To update the source configuration for the event consumer SDK, do the following:

1. In the AWS Management Console, navigate to Amazon EventBridge, and then choose the Event Buses tab.
2. In the Custom event bus table, find the row for your Buy with Prime event bus, for example a name starting with aws.partner/buywithprime/.
3. Copy the ARN for the event bus.
4. In your buy-with-prime-event-hydrator repository, in the configuration directory, open the source_config.ts file.
5. In the sampleSourceConfig variable, for the BWP_EVENT_BUS_ARN property, replace the string with the ARN for the event bus.
6. Navigate to AWS Secrets Manager, and then choose the Secrets tab.
7. Open the secret that contains your Buy with Prime client credentials, and then copy the Secret ARN.
8. In the source_config.ts file, for the BWP_API_SECRETS_ARN property, replace <BWP_API Secrets_ARN> with the ARN for your client credentials.
9. Save the source_config.ts file.

Update the stack configuration

To update the stack configuration for the event consumer SDK, update the configuration in the stages variable by doing the following:

1. In the buy-with-prime-event-hydrator repository, in the configuration directory, open the stack_config.ts file.
2. Change the value for the stageName property to your choice of stage. For example, consider using staging for testing and prod for going live with shoppers.
3. If you're testing and want to view debug logs in the AWS CloudWatch console, change the logLevel property to StageLogLevel.DEBUG. If you're going live with shoppers, change the isProd property to true.
4. In the AWS Management Console, from the menu in the upper right corner, copy your AWS account ID.
5. In the stack_config.ts file, for the account property, replace <AWS_ACCOUNT_ID> with your AWS account ID.
6. In the region property, replace <AWS_REGION> with the region where you want to deploy the event consumer SDK.
7. In the destinationConfig property, remove any destinations that you want to avoid using.
8. Save the stack_config.ts file.

Deploy the event consumer SDK

After you configure the code for your SDK, do the following to deploy the stack to your AWS account:

1. Open a command prompt window, and then change directory to the root directory of the buy-with-prime-event-hydrator repository.
2. Run npm install. If an error occurs, do the following:
   • Verify that NPM is installed.
   • Verify that you surrounded with quotation marks the values that you copied while configuring the event consumer SDK.
   • Verify that you avoided deleting any trailing commas.
3. Run cdk synth. If an error occurs, verify that the AWS CDK CLI tool is installed.
4. Run cdk deploy. If an error occurs, do the following:
   • Verify that you authenticated the IAM user to the AWS CDK CLI.
   • Verify that the IAM user has permissions to deploy an AWS CloudFormation stack, permissions to create secret values in AWS Secrets Manager, and permissions to create queues in Amazon Simple Queue Service (Amazon SQS).

Verify the deployment

After running cdk deploy, verify that the AWS CloudFormation stack exists in your AWS instance by doing the following:

1. In the AWS Management Console, navigate to AWS CloudFormation.
2. Click the BwpEventConsumerSdkStack-stageName stack, where stageName is the value you specified for stageName in the stack_config.ts file.
3. Verify that the status of the stack automatically updates to become CREATE_COMPLETE or UPDATE_COMPLETE.

Troubleshooting: Destination doesn't receive order updates

If the destination that you configured in the event consumer SDK doesn't receive order updates, deploy the SDK with isProd set to false, and logLevel set to StageLogLevel.DEBUG, and then check the AWS CloudWatch logs.

View the AWS CloudWatch logs

To view the AWS CloudWatch logs, do the following:

1. In the AWS Management Console, navigate to AWS CloudWatch.
2. In the navigation, under Logs, choose Log groups.
3. Find the log group for the destination and stage that you want to investigate. See the following names of the log groups for prebuilt destinations, where stageName is the value that you specified for the stageName property in the stack_config.ts file:
   • Amazon S3: /aws/lambda/s3-destination-lambda-stageName
   • Salesforce Commerce Cloud: /aws/lambda/sfcc-destination-labmda-stageName
   • Salesforce OMS: /aws/lambda/sf-oms-destination-lambda-stageName
4. Click the log group for the destination that you want to troubleshoot.
5. Under the Log Streams table, click the log stream with the most recent Last event time, which is often the first event in the list.
6. When reviewing the logs, browse the ERROR logs first.

Troubleshooting: Larger batch size for Amazon SQS isn't supported

If you configure the Amazon SQS batch size in lib/constructs/sf_oms_destination_infrastructure.ts, avoid configuring the batch size to a value greater than 20. The Salesforce implementation handles a maximum of 20 events at a time.

Related topics

Configure the Salesforce OMS Package for Buy with Prime