Buy with Prime | Developer Documentation
Documentation

Buy with Prime UI Library Reference

📘

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

Buy with Prime offers a UI library that includes ready-to-use custom web components that you can use to incorporate Buy with Prime into your website. The library contains two main modules: the delivery card and the Prime benefit card. This topic describes the fields of the delivery-card and prime-benefit-card components.

Incorporate the library into your web application and populate the components with information that you get by using Buy with Prime interfaces. To provide a consistent display of Buy with Prime features, you must use the Buy with Prime UI library instead of creating your own UI elements.

To use the Buy with Prime UI library, you must first integrate Login with Amazon (LWA) with your site.

delivery-card

You use the delivery-card component to render a delivery card on your site. Delivery cards display shopper-level information such as the shopper’s name, a delivery estimate, the number of items that are eligible for Buy with Prime, and a sign-in link to let the shopper sign in using their Amazon account credentials through Login with Amazon (LWA).

You can use this delivery cards in cart pages and checkout pages.

For delivery card code examples, see Delivery Card Examples.

Fields

FieldTypeRequiredDescription
lwaConfigLwAConfigNoThe LWA configuration for integrating LWA into your site. You must provide an lwaConfig to the delivery-card both before and after a shopper signs in. For details about how to integrate Login with Amazon into your site, see Integrate Login with Amazon with Your Site.
shopperInfoShopperInfoNoThe shopper's Amazon customer profile data. You must have this information if you want to personalize the delivery card for the shopper after they sign in. Examples of this information are their name and whether they are a Prime member. For details about how to get shopper information from LWA, see Customer Profile.
deliveryOffersDeliveryOfferNoThe delivery offers for the items in the cart or order, which you use to show the delivery estimate information in the delivery card. If multiple deliveryOffers are present in deliveryGroups, the delivery card doesn’t render the delivery estimate message.
numberOfPrimeItemsIntNoThe number of items in the cart or order that are eligible for Buy with Prime.
loadingBooleanNoA flag that indicates whether the delivery card shows a loading widget to shopper. The default value is false.
showAuthenticatedCardBooleanNoA flag that indicates whether to display the delivery card on the site after the shopper signs in. If true, the delivery card is displayed. The default value is true.
clickStreamTenantIdStringNoAn ID, if you want to track metrics.

prime-benefit-card

The Prime benefit card displays item-level information such as returnability, a delivery estimate, and whether the item is eligible for Buy with Prime. You can use this component to render the Prime benefit card in cart or checkout pages on your site.

For Prime benefit card code examples, see the following topics:

Fields

FieldTypeRequiredDescription
isShopperPrimeBooleanNo

A flag that indicates whether the shopper is a Prime member. This field can have the following values:

  • true: The authenticated shopper is a Prime member. The prime-benefit-card renders a Prime badge.
  • false: The authenticated shopper isn't a Prime member. The Prime badge isn't rendered.
  • undefined: (Default) The shopper isn't authenticated (hasn't signed in).

The shopper is considered to be a Prime member if the bwpEligibilityStatus in ShopperBwPEligibility is PRIME.

isItemBuyableBooleanNo

A flag that indicates if the item or group of items is eligible for Buy with Prime. This field can have the following values:

  • true: The item is eligible for Buy with Prime. If the shopper is authenticated, the Prime benefit card shows the free delivery benefit, such as "Free delivery." Otherwise, the prime-benefit-card shows the Prime badge and "eligible."
  • false: The item isn't eligible for Buy with Prime. The Prime badge isn't rendered.
  • undefined: (Default) There is no information about whether the item is eligible for Buy with Prime. The Prime badge isn't rendered.

To determine whether an item is eligible for Buy with Prime, you use the Buy with Prime Catalog interface. For an example, see Get the buyability status of a product. An item is considered eligible for Buy with Prime if the buyability status is BUYABLE.

isItemReturnableBooleanNo

A flag that indicates if the Buy with Prime item or group of items is returnable.

  • true: The item is returnable. The Prime benefit card shows the free return benefit, such as "Free return."
  • false: The item isn't returnable. The Prime benefit card shows "Not returnable."
  • undefined: (Default) There is no information about the item's returnability. The Prime benefit card doesn't show the free return benefit.

To determine whether an item is returnable, you use the Buy with Prime Return interface. For examples, see Get Reversal Offers. An item is considered returnable if the title in ReversalOfferGroupSummary is Eligible for Return.

deliveryOfferDeliveryOfferNoThe delivery offer for the item or items in the same group. If a delivery estimate message is present, the Prime benefit card displays the message.
loadingBooleanNo

A flag that indicates whether the Prime benefit card shows a loading widget to the shopper. This field can have the following values:

  • true: The content to be rendered is loading. A spinner icon is rendered.
  • false: (Default) The content is ready to be rendered. The Prime benefit card is shown.
clickStreamTenantIdStringNoAn ID, if you want to track metrics.

Types

The following section describes types that the delivery-card component or prime-benefit-card component use.

LwAConfig

This type contains the LWA configuration for integrating LWA into your site. You must provide an lwaConfig to the delivery-card both before and after a shopper signs in. For details about how to integrate Login with Amazon into your site, see Integrate Login with Amazon with Your Site.

FieldTypeRequiredDescription
clientIdStringYesThe merchant's LWA client ID. You can find this in the merchant's LWA security profile.
redirectUrlStringYes

The URL where shoppers are redirected after they successfully sign in.

Note that LWA only allows redirection to fully qualified URLs that you add as Allowed Return URLs to your LWA security profile. If you attempt to use a non-allowlisted redirectUrl in a delivery card, you get an error. In addition, the redirectUrl that you specify in a delivery card must exactly match an Allowed Return URL (including URL parameters, and so on) that you specified in your LWA security profile. For details about how to integrate with LWA, see Integrate Login with Amazon with Your Site.

signOutCallbackCallback functionYesA callback function that is run when the shopper signs out. You can use this function to handle sign-out logic, such as clearing any shopper state stored on the merchant's side.
stateStringNoAn opaque value used by the client to maintain the state between this request and the response. The authorization service includes this value when redirecting the user back to the client. It is also used to prevent cross-site request forgery (CSRF).
showSignInWindowAsPopupBooleanNo

A flag that indicates whether the LWA sign-in window uses a popup or redirects the shopper to a new page (the redirectUrl) to sign in. If false, LWA redirects the shopper to a new page (the redirectUrl) to sign in. The default value is false.

If you choose to enable popups, be aware that not all browsers support popups. We therefore recommend that you use a redirect mechanism. For details, see Handle redirects.

Be sure to set the domain of the site where the pop-up window is shown as an Allowed Origin in your security profile.

codeChallengeStringNoA parameter that you can use to secure authorization code grants through Proof Key for Code Exchange (PKCE).
codeChallengeMethodStringNoA parameter that you can use to specify what method you used to encode the code_verifier, which is passed through the codeChallenge. Don't provide this value if you didn't provide a codeChallenge.

ShopperInfo

This type represents the shopper’s Amazon customer profile data, including the shopper's name, email, and Prime membership status. This information personalizes the delivery card for the shopper, such as displaying their name after they sign in.

For details on how to get this shopper information, see Customer Profile.

FieldTypeRequiredDescription
nameStringYesThe shopper's name.
emailStringYesThe shopper's email address. This email address is displayed in a sign-out modal.
isPrimeBooleanYesA flag that indicates whether the shopper is a Prime member.

The following image shows some examples of how shopper information is displayed.


DeliveryOffer

This type represents a delivery offer that includes a delivery estimate message or an error code from the deliveryPreview query. For an example, see Sign-in link, number of items offered through Buy with Prime, and a delivery estimate.

FieldTypeRequiredDescription
messageStringNoThe delivery estimate message for the item.
errorCodeStringNoThe error code, such as InvalidDestination and InvalidAddress, returned from the deliveryPreview query. You can use this code to identify specific errors related to the delivery estimate, which enables you to render the appropriate error message.

The following example shows an error response from the deliveryPreview query, which shows the code you should use.

{
  "type": "ValidationError",
  "code": "InvalidDestination",
  "details": {
     "field": null,
     "violations": []
  },
  "errorType": "ValidationException",
  "errorCode": 400
}

The following image shows some examples of delivery offers.

Related topics

Updated 10 days ago