Button widgets

Amazon maintains galleries of multiple versions and sizes of buttons that are available for your use. Button sizes depend on the category of button that you choose for your application.

For Login with Amazon buttons, see the Login with Amazon Button Guidelines, and for Amazon Pay buttons, see the Merchant Tools page on the Amazon Pay website.

The following chart explains more about each button widget option. Note that while the button text is not technically tied to the functionality that you assign to it, you should use the button labels according to the use cases below to avoid customer confusion.

Button Use case
Login with Amazon
Use this button to let a buyer sign in to your site using their Amazon account information. Buyers can sign in before or during the checkout process. After your buyers click one of the Login with Amazon buttons you can do this:
  • Access buyer profile information - Depending on how you set the scope parameter in the button widget, you can access information from the buyer's Amazon profile, including their name, email address, and a unique userID. You can use the profile information to customize the customer's shopping experience and track their browsing history. The userID can be used to identify returning buyers.
  • Create a local account for your buyers - With the information obtained from the Amazon user profile, you create a local account in your shop. This account is equal to your normal shop accounts and offers the same benefits to you and to the customer. The only difference is that the accounts created with the Amazon Login don't have a password created by the customer.
Amazon Pay
Use this button to let a buyer initiate an order transaction from your cart page or any product detail page and access their shipping and payment information using their Amazon account. When a buyer clicks the Amazon Pay button, they sign in using their Amazon user name and password before accessing their shipping and payment information. You can provide the following functionality with this button type:
  • Checkout with Login - As with the Login with Amazon button, you can request that the buyer share their profile information with you when they first sign in to your site.
  • Guest checkout - The Amazon Pay button can be used to let a buyer complete a purchase without sharing any personally identifiable information with you before completing a transaction. When a buyer signs in to access their shipping and payment information, you receive only the buyer's city, country, and postal code for calculating tax and shipping. The buyer doesn't see a consent screen when they sign in using Amazon Pay as a guest. After the buyer completes the checkout process, you receive only their name, email address, and shipping address.

Button widget parameters

The Login with Amazon and Amazon Pay button widget is rendered on your webpage using JavaScript code within the body of your HTML code. The JavaScript code contains parameters that affect the button type, color, size, and so on.

The JavaScript code sample for the button is shown below. For more information, see Step 3: Add a button widget.

 
<script>
  window.onAmazonLoginReady = function() { 
    amazon.Login.setClientId('YOUR-MERCHANT-ID'); 
  };
  
  
window.onAmazonPaymentsReady = function(){
    // render the button here
    var authRequest; 

    OffAmazonPayments.Button('LoginWithAmazon',
      '<YOUR-SELLER-ID>', {
      type:  "TYPE_PARAMETER", 
      color: "COLOR_PARAMETER", 
      size:  "SIZE_PARAMETER", 
      language: "LANGUAGE_PARAMETER",

      authorization: function() { 
        loginOptions = {scope: "SCOPE_PARAMETERS", popup: "POPUP_PARAMETER"};

        authRequest = amazon.Login.authorize (loginOptions,
          "REDIRECT_URL"); 
      } 
    }
}
</script>

The following sections describe the parameters and their values contained in the JavaScript button widget code:

Related code topics:

Your Merchant ID

Replace YOUR_MERCHANT_ID with your own Merchant ID, which you received during registration. If you aren't sure what your Merchant ID is, check your Merchant ID by signing in to Seller Central and going to Integration > MWS Access Key.

Type parameter

The type parameter is an optional parameter for indicating the type of button image that you want to choose for your webpage. Note that if you decide not to specify a value for type, the LwA (Login with Amazon) button is set as the default value.

The following table shows the valid type parameter values, button descriptions, and sample button images.

Type codes Button description Button example
LwA Specifies the Login with Amazon button. This is the default button if type is not specified.
PwA Specifies the Amazon Pay button.

Color parameter

The color parameter is an optional parameter for choosing a button color. The following table shows the valid color code values, color descriptions, and color samples.

Color codes Color description Color example
Gold Gold (default)
LightGray Light gray
DarkGray Dark gray

Size parameter

The size parameter is an optional parameter for choosing a button size. For more information about button size options, see the Zahlungshinweise und Buttons.

Regular Retina
  • small
  • medium (default)
  • large
  • x-large

The actual size rendered depends on the type of button selected:

Parameter Type Size
LwA - Specifies the Login with Amazon button.
  • small (156px x 32px)
  • medium (174px x 46px)
  • large (312px x 64px)
  • x-large (390px x 92px)
PwA - Specifies the Amazon Pay button.
  • small (148px x 30px)
  • medium (200px x 45px)
  • large (296px x 60px)
  • x-large (400px x 90px)

Language

The language parameter is an optional parameter for associating a language with a Login with Amazon or an Amazon Pay button. This is useful for offering multi-language support for an Amazon Pay and Login with Amazon experience for buyers on your website.

For example, a French-speaking buyer wants to make a purchase from a German website. The buyer, either by changing the language preference settings in their browser or by making a selection from a language switcher on your website, can view Amazon Pay components in French.

The following table shows the valid language parameter values.

Language values Language description Buttons
de-DE Germany's German
en-GB UK English
es-ES Spain's Spanish
fr-FR France's French
it-IT Italy's Italian

If you pass a language other than those listed above, the language defaults to the buyer's browser language. If the buyer's browser language preference setting isn't one of the languages listed above, the language defaults to English.

For more information, see Amazon Pay and multi-language integration.

Scope parameters

The value of the parameter scope that you choose influences both the content returned in the response of the call and the type of consent screen that Amazon Pay shows to the buyer to secure their permission for sharing their information.

You can use a combination of the following scope parameters:

Scope parameter Description Requirements
profile Gives access to the full user profile (username, email address, and userID) after login. --
profile:user_id Gives access only to the user-id from the user profile after login. --
payments:widget Required to show the Amazon Pay widgets (address and wallet widget) on your page. If used without the two parameters below, it gives access to the full shipping address after ConfirmOrderReference call and to the full billing address after successful authorization.  
payments:shipping_address Gives access to the full shipping address via the GetOrderReferenceDetails API call as soon as an address has been chosen in the address widget.
  • Requires scope parameter payments:widget
  • AccessToken set in GetOrderReferenceDetails call.
payments:billing_address Gives access to the full billing address via the GetOrderReferenceDetails API-Call as soon as a payment method has been chosen in the wallet widget.
  • Requires scope parameter payments:widget
  • AccessToken set in GetOrderReferenceDetails call.

Example: scope: profile payments:widget payments:shipping_address payments:billing_address

The payments:shipping_address provides access to the buyer's shipping address. To retrieve the full shipping address, you need to call the getOrderReferenceDetails API. For more information, see "Getting the Shipping Address from Amazon" in Step 4: Add the AddressBook and Wallet Widgets, or GetOrderReferenceDetails in the Amazon Pay API reference guide.

The popup parameter determines whether the buyer is presented with a pop-up window to authenticate or if the buyer is instead redirected to an Amazon Pay page to authenticate. If you're hosting the button widget on a non-secure page or for a smartphone-optimized experience, we recommend using the redirect experience.

Use one of the following popup parameters:

  • true - Presents an Amazon Pay authentication screen in a pop-up dialog. Recommended for desktops where the button widget is presented on a secure page. Be aware that this option requires the button to reside on an https page with a valid SSL certificate.
  • false - Redirects the buyer to an Amazon Pay page within the same browser window. Recommended for mobile devices or if you're rendering the button widget on a non-secure page. Be aware that the redirect URL must use the https protocol and have a valid SSL certificate.

Default: popup: true

When the buyer clicks the Amazon Pay and/or Login with Amazon button, the Amazon Pay authentication window launches, and the buyer is asked for their Amazon account email address and password. When the pop-up parameter is set to false (popup: false), clicking the button redirects the buyer to the Amazon Pay authentication page within the same browser window.

After you embed the button and add the JavaScript code with pop-up parameter = popup: true, a window shows where buyers can authenticate without ever leaving your website:

As you can see in the previous screenshot, you can add your company logo to the authentication window. You can do this on Seller Central by clicking the Integration Settings link under Settings.

Redirect URL

The redirect URL is a parameter that determines which page the buyer is redirected to after successfully authenticating. For example, after a successful authentication, you might want to take the buyer to the next page in your checkout pipeline to collect their shipping address and/or payment method details. Be aware that if you use popup:false in your button code – which means that you use the redirect login experience – you have to add all the redirect URLs to an access list in Seller Central. Instructions for adding the redirect URLs to the access list can be found here: Adding allowed JavaScript origins or allowed return URLs

Error handling code

We also recommend that you implement an onError handler in your code. The onError code is optional, but it can save you considerable effort with troubleshooting integration issues. For more information, see Testing your integration in the Sandbox environment.

Adding a logout option

For users who have signed in, you must offer a logout option (often a hyperlink) on your website. The logout option should delete any cached tokens and remove the user's profile information (like their name) from your website. Then your website can present the login button again.

If you are using the Login with Amazon SDK for JavaScript, you can call the amazon.Login.logout method to delete any cached tokens. For example:

 
<script type="text/javascript">
  document.getElementById('Logout').onclick = function() {
    amazon.Login.logout();
  };
</script>
    

Subsequent calls to amazon.Login.authorize present the login screen by default.