Buy with Prime | Developer Documentation
Documentation

Install the Buy with Prime Cartridge

📘

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

Prerequisites

Complete the following prerequisites before starting the process of installing the Buy with Prime cartridge.

Set up your development environment

Set up your development environment with the following:

  • An integrated development environment (IDE) of your choice.
  • Node.js version 14.19 or later. For details about downloading and installing Node.js, see the Node.js website.
  • Tools configured to upload your cartridges to Salesforce Commerce Cloud. For details, see the Salesforce documentation at Upload and Configure Cartridges.

Install the SFRA cartridges and libraries

Verify that you've added the cartridges for your Salesforce Commerce Cloud site to your development environment. For details about Salesforce Reference Architecture (SFRA), see the Salesforce documentation at Get Started with Storefront Reference Architecture.

In your development environment, verify the following in the cartridges folder as part of your Salesforce Commerce Cloud installation:

  • app_storefront_base, the base cartridge provided with Storefront Reference Architecture (SFRA)
  • bm_app_storefront_base, the Business Manager cartridge provided with SFRA.
  • modules, the folder that contains globally shared modules.

Build the SFRA cartridge

If you haven't done so already, build SFRA as shown in the following procedure. You must build SFRA before building the Buy with Prime cartridge.

  1. At a command prompt, change directory to your storefront_reference_architecture_master directory.
  2. Run npm install.

Integrate with a PSP (optional)

If you don't have an existing integration with Amazon Pay or with another payment service provider (PSP), the Amazon Pay cartridge can be an integration option. For details about installing and configuring the Amazon Pay v2 cartridge, see the Amazon Pay documentation for Upgrading to Checkout v2.

Clone the Buy with Prime cartridge

Clone the Buy with Prime cartridge for Salesforce Commerce Cloud. For details about the Git repository that contains the Buy with Prime cartridge, see buy-with-prime-for-salesforce-commerce-cloud repository on GitHub.

To access the Git repository, work with your Buy with Prime solutions architect.

Install the Buy with Prime cartridge

Add the Buy with Prime cartridge to your workspace

Do the following to add the Buy with Prime cartridge to your workspace:

  1. Open your IDE.
  2. Navigate to the tools to add a directory to a workspace.
  3. Browse to the directory where you cloned the Buy with Prime cartridge.
  4. Add the buy-with-prime-for-salesforce-commerce-cloud root folder to your workspace.

Specify the path to your SFRA directory

The Buy with Prime cartridge assumes that your app_storefront_base cartridge is at the default path storefront-reference-architecture-master/cartridges, and that the root SFRA folder storefront-reference-architecture-master is side by side with the root folder for your Buy with Prime cartridge.

└── <Project name>
    ├── ...
    ├── buy-with-prime-for-salesforce-commerce-cloud/
    |   ├── cartridges/
    |   |   ├── int_buywithprime/
    |   |   └── int_buywithprime_sfra/
    |   ├── metadata/
    |   |   └── ...
    |   ├── test/
    |   |   └── ...
    |   └── ...
    ├── storefront-reference-architecture-master/
    |   ├── ...
    |   ├── cartridges/
    |   |   ├── app_storefront_base/
    |   |   └── ...
    |   └── ...
    └── ...

If you've modified the folder names or directory structure for your Salesforce Commerce Cloud site from the default SFRA paths, do the following to specify the path to your app_storefront_base cartridge:

  1. Open your IDE, and then open a file explorer view of your project.
  2. Under the root folder that you downloaded for the Buy with Prime cartridge, in the cartridges folder, open the package.json file.
  3. In the package.json file,git replace the following relative path with the relative path to your app_storefront_base cartridge: 
      "paths": {
    "base": "../storefront-reference-architecture-master/cartridges/app_storefront_base/"
  },

  4. Save the changes to the package.json file.

Build the Buy with Prime cartridge

To build the Buy with Prime cartridge, make sure that you're using version 14.19 or later of Node.js.

  1. At a command prompt, open your buy-with-prime-for-salesforce-commerce-cloud directory.
  2. Change directory to the cartridges directory.
  3. Run npm install.
  4. Run npm run build.

The build outputs the compiled and generated code to a directory named static. For example, in the int_buywithprime directory, in the cartridge subdirectory, you'll see the code in the static subdirectory.

└── <Project name>
    ├── ...
    ├── buy-with-prime-for-salesforce-commerce-cloud/
    |   ├── cartridges/
    |   |   ├── int_buywithprime/
    |   |   |   ├── cartridge/
    |   |   |   |   ├── ...
    |   |   |   |   ├── static/
    |   |   |   |   └── ...
    |   |   |   └── ...
    |   |   └── int_buywithprime_sfra/
    |   └── ...
    └── ...

Update and import the site metadata for the Buy with Prime cartridge

The Buy with Prime cartridge has site-specific configuration and credentials so that you can associate each site with a different Buy with Prime merchant console account, if needed. You can update the metadata for the Buy with Prime cartridge with your site-specific metadata, and then import the metadata into the Business Manager tool for Salesforce Commerce Cloud.

As an alternative to following the procedures for updating and importing the site metadata, you can choose your site in Business Manager before running a job. For details, see Select your site using Business Manager.

Update your site metadata in the Buy With Prime cartridge

In the code for the Buy with Prime cartridge, do the following to replace placeholders with the name of your site.

  1. Open the Business Manager tool for Salesforce Commerce Cloud, and then in the upper left corner, on the menu, verify your name of your site.
  2. Open your IDE, and then open a file explorer view of your project.
  3. In the buy-with-prime-for-salesforce-commerce-cloud folder, open the metadata folder.
  4. In the jobs.xml file, replace each of the occurrences of {your_site_id} with the name of your site.
  5. In the jobs.xml file, replace the occurrence of RefArch with the name of your site.
  6. In the services.xmlfile, replace the occurrence of RefArch with the name of your site.
  7. Save the changes to the jobs.xml and services.xml files.
  8. From the metadata folder, open the sites folder, and then rename the RefArch subdirectory to match the name of your site.
└── <Project name>
    ├── ...
    ├── buy-with-prime-for-salesforce-commerce-cloud/
    |   ├── cartridges/
    |   |   ├── int_buywithprime/
    |   |   └── int_buywithprime_sfra/
    |   ├── metadata/
    |   |   ├── ...
    |   |   ├── sites/
    |   |   |   └── RefArch/
    |   |   ├── jobs.xml
    |   |   └── services.xml
    |   └── ...
    └── ...

Import your site metadata to Salesforce Commerce Cloud

After updating the site metadata, do the following to import the metadata from the Buy with Prime cartridge to Salesforce Commerce Cloud.

  1. Zip the metadata directory and all of its subdirectories into a new .zip file.
  2. Open the Business Manager tool for Salesforce Commerce Cloud.
  3. From the Administration menu, under Site Development, click Site Import & Export.
  4. Under Import, click the Choose File button.
  5. Navigate to the .zip file that you created, and then click Open.
  6. Click Upload.
  7. Click the option button next to instance/metadata.zip, then click Import, and then click OK.

To verify that the metadata imported successfully, do the following to view the log:

  1. From the Administration menu, under Site Development, click Development Setup.
  2. On the Folder Browser tab, click Logs, then jobs, and then sfcc-site-import.
  3. Click the Job-sfcc-site-import-....log with the latest last modified date.

If the import succeeds, the log shows finished with status [OK].

Select your site using Business Manager as an alternative to updating and importing site metadata

As an alternative to editing and importing the site metadata, you can select your site in Business Manager for the job that you want to run.

  1. Open the Business Manager tool for Salesforce Commerce Cloud.
  2. From the Administration menu, under Operations, click Jobs.
  3. Click the job for which you want to specify your site.
  4. Click the Job Steps tab.
  5. Next to Scope, click the value.
  6. Select the check box next to your site, and then click Assign.

Related topics

Configure the Buy With Prime Cartridge

Updated 2 days ago