Frontend Customisation

Support for Progressive Web Apps/Headless Commerce/Single Page Applications

The module exposes the REST endpoints that needs to set up. You can find them here. The front-end needs to be setup by the merchant/developer.

Notes on the Checkout Session API

The Checkout Session API exposes a number of endpoints to manage active Amazon checkout sessions associated with an active cart in a Magento store. Available endpoints include functionality such as retrieving configuration information used to generate an Amazon Pay button, retrieving shipping addresses associated with an Amazon account, and updating a checkout session by setting payment/shipping/billing information, etc.

The following flowchart illustrates the sequence in which these calls may be made through a normal shopping/checkout flow:


Checkout Session Config

Values returned from this endpoint will be needed to generate the Sign In with Amazon and Amazon Pay buttons. The format of this response will be:

        "merchant_id": string,
        "currency": string,
        "button_color": string,
        "language": string,
        "sandbox": boolean,
        "login_payload": string,
        "login_signature": string,
        "checkout_payload": string,
        "checkout_signature": string,
        "public_key_id": string,
        "pay_only": boolean
        "paynow_payload": string,
        "paynow_signature": string


The value for productType returned in the response will be a boolean value indicating whether the product is PayOnly; true for PayOnly, false for PayAndShip.

For a detailed explanation on how to use these values to generate:

Shipping and Payment Information

The Shipping Address, Payment Descriptor, and Billing Address endpoints are used to retrieve order summary information to display upon checkout review. Shipping and payment method updates can be enabled to allow the user to choose a different shipping address or payment instrument before placing an order.


The value for shippingAddress should be null for PayOnly product types. Similarly, billingAddress should only be populated in EU or for PayOnly product types.

For recommended best practices regarding displaying this information, see Display shipping and payment info (Best Practice).

For a guide on enabling shipping and payment information updates at checkout review, see Enable shipping and payment updates.

Configurable URLs

In order to provide more control over redirects from Amazon during the checkout process, several configuration options are available to define locations for checkout session logic in a headless implementation. See the URL options in Developer Options for a description of the configurable locations.

An example sequence of how these redirects may be used looks like the following:

  • Amazon Pay button is rendered at checkout page
  • User authenticates through Amazon and is redirected to Amazon Checkout Review Return URL with an amazonCheckoutSessionId in the query string
  • Sign user in to Magento store, then redirect to Magento Checkout URL Path with amazonCheckoutSessionId in the query string
  • Use checkout session ID and checkout session API endpoints to set/display shipping information and payment descriptor
  • User places order, call the checkout session API /update endpoint; a processing URL is returned
  • Redirect user to processing URL, and Amazon redirects user to Amazon Checkout Result Return URL
  • Call checkout session API /complete endpoint, and redirect user to Magento Checkout Result URL Path upon success

Swagger Documentation

Detailed documentation on available endpoints, their usage, and request/response bodies can be found here.

Rendering the Amazon Pay Button in a Custom Location

You may wish to display an Amazon Pay button somewhere other than the default options (cart, minicart, checkout, or with payment methods). A recommended solution is loading the amazon-button.js script in a custom block/template similar to how the module renders the minicart button:

  <div id="PayWithAmazon-Cart"
    data-loaded-at="<?= $block->escapeHtml(time()) // added for force re-rendering ?>"
    data-mage-init='{"Amazon_Pay/js/amazon-button": {"hideIfUnavailable": ".amazon-button-container"}}'>

See the minicart button template in the module repository for a full example.