Buy with Prime | Developer Documentation
Documentation

Display Delivery Cards

📘

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

This topic provides examples of how to render delivery cards by using the Buy with Prime UI library.

To learn how to use the UI library to incorporate Buy with Prime into your checkout flow, see Steps to Use the UI Library.

For the Buy with Prime UI Library Reference, see Buy with Prime UI Library Reference.

Sample data

Some examples in this topic use the following sample data.

Sample LWA configuration 
// Sample data
const LWAConfigurations = {
    LWAClientId: "amzn1.application-oa2-client.your-unique-client-id",
    redirectUrl: "https://mystore.com/bwp-signin-redirect",
    state: "example-state" // This is optional for static redirection
};
Sample shopper profile 
// Example LWA ShopperProfile response
const ShopperProfile = {
    user_id: "amznl.account.example-user-id",
    email:"[email protected]",
    name :"Jane",
    postal_code: "98052"
};
Successful delivery preview response 
// Example deliveryPreview response
const deliveryPreview = { 
    id: "example-delivery-preview-id", 
    deliveryGroups: [
        {id: "example-delivery-group-id",
         deliveryOffers: [
            {  id: "example-delivery-offer-id",
               date: {  
                    earliest: "2023-12-08T04:00:00Z",  
                    latest:"2023-12-08T04:00:00Z"
               },  
               policy:{  
                    messaging: {  
                        messageText: "Get it as soon as Tomorrow Apr 6",  
                        locale: "en-US",  
                        badge: "PRIME" 
                    }  
               },  
               "expiresAt":null 
            }]  
        }
    ]
}
Error delivery preview response 
// Example deliveryPreview error response
const deliveryPreviewErrorResponse = { 
    "status": "error",
    "message": "\"Can't ship to this address\"",
    "data": {
        "type": "ValidationError",
        "code": "InvalidDestination",
        "details": {
            "field": null,
            "violations": []
        },
        "errorType": "ValidationException",
        "errorCode": 400
    }
}

Sign-in link

To enable the shopper to sign in, you provide information to the delivery card, and the delivery card takes care of initiating the sign-in process through LWA.

After the shopper signs in, they are redirected to the page that you specified as the redirectUrl in your LWA integration. The redirection includes an LWA authorization code. You must exchange the authorization code for an access token and refresh token. You can then use the LWA access token to retrieve the shopper's Amazon customer profile data. For details, see Use Login with Amazon for Shopper Identity.

The following delivery card has a sign-in link that the shopper clicks to sign in.






Example Code 
// Import the pni-web-components.js in your HTML file
<script type="module" src="/vendor/pni-web-components.js"></script>

// ...other HTML

<script>
   
    document.addEventListener('DOMContentLoaded', function() {
       const deliveryCard = document.createElement('delivery-card');

        deliveryCard.lwaConfig = {
            clientId: LWAConfigurations.LWAClientId,
            redirectUrl: LWAConfigurations.redirectUrl,
            signOutCallback: function() {
                // Placeholder for implementing the sign-out logic, such as clearing the shopper's state for the current session           }, 
            },
            state: LWAConfigurations.state
        };

       // Display the card where you want to place it on the page.
       document.body.appendChild(deliveryCard);
    });
</script>

// ...other HTML

Sign-in link, number of items offered through Buy with Prime, and a delivery estimate

To get a delivery estimate, call the deliveryPreview query. You can get a delivery estimate for unauthenticated shoppers (postal code, IP address, and so on) and for authenticated shoppers by using the LWA access token. For examples, see Create a Delivery Preview for a Product Detail Page.

From the deliveryPreview response, get the deliveryMessage for the item. In the delivery-card, you can structure the DeliveryOffer by using the messageText from the deliveryMessage. The following cases, however, don't display a delivery estimate:

The following example code renders a delivery card with a delivery estimate, the number of items offered through Buy with Prime, and a sign-in link.






Example code 
// Import the pni-web-components.js in your HTML file
<script type="module" src="/path/to/pni-web-components.js"></script>

//...Other HTML

<script>
   
    document.addEventListener('DOMContentLoaded', function() {
       const deliveryCard = document.createElement('delivery-card');

        deliveryCard.lwaConfig = {
            clientId: "amzn1.application-oa2-client.your-unique-client-id",
            redirectUrl: "https://mystore.com/bwp-signin-redirect",
            signOutCallback: function() {
                // Placeholder for implementing the sign-out logic, such as clearing the shopper's state for the current session           }, 
           }
        };

        deliveryCard.deliveryOffers = [
            { message: "Get is as soon as Tomorrow Apr 6", errorCode: null },
        ];

        deliveryCard.numberOfPrimeItems = 2;

       document.body.appendChild(deliveryCard);
    });
</script>

//...Other HTML

// YourReactComponent.jsx

import { DeliveryCardReact } from "/path/to/pni-react-components.js";

function YourReactComponent() {

  // Define the properties for lwaConfig, deliveryOffers, and numberOfPrimeItems
  const lwaConfig = {
    clientId: "amzn1.application-oa2-client.your-unique-client-id",
    redirectUrl: "https://mystore.com/bwp-signin-redirect",
    signOutCallback: function() {
      // Placeholder for implementing the sign-out logic, such as clearing the shopper's state for the current session           }, 
    }
  };

  const deliveryOffers = [
    { message: "Get is as soon as Tomorrow Apr 6", errorCode: null },
  ];

  const numberOfPrimeItems = 2;

  return (
    <div>
      {/* Place the DeliveryCardReact component where desired, passing the props */}
      <DeliveryCardReact 
        lwaConfig={lwaConfig} 
        deliveryOffers={deliveryOffers} 
        numberOfPrimeItems={numberOfPrimeItems}
      />
    </div>
  );
}

export default YourReactComponent;

Signed-in shopper is a Prime member

You can use the shopper profile to create a more personalized experience after the shopper signs in. To determine whether the shopper is a Prime member, call the shopperBwPEligibility query.

If bwpEligibilityStatus in shopperBwPEligibility is PRIME, set isPrime to true in the shopperInfo that you provide to the delivery card. If you set isPrime to true, the delivery card looks like the following example.




Example Code 
// Import the pni-web-components.js in your HTML file
<script type="module" src="/path/to/pni-web-components.js"></script>

//...Other HTML

<script>
   
    document.addEventListener('DOMContentLoaded', function() {
       const deliveryCard = document.createElement('delivery-card');

       deliveryCard.lwaConfig = {
            clientId: LWAConfigurations.LWAClientId,
            redirectUrl: LWAConfigurations.redirectUrl,
            signOutCallback: function() {
                // Placeholder for implementing the sign-out logic, such as clearing the shopper's state for the current session           }, 
            },
            state: LWAConfigurations.state
        };
       
       deliveryCard.shopperInfo = {
           name = ShopperProfile.name,
           email = ShopperProfile.email,
           isPrime = true 
       };
        
       document.body.appendChild(deliveryCard);
    });
</script>

//...Other HTML


// YourReactComponent.jsx

import { DeliveryCardReact } from "/path/to/pni-react-components.js";

function YourReactComponent() {

  const lwaConfig = {
    clientId: "amzn1.application-oa2-client.your-unique-client-id",
    redirectUrl: "https://mystore.com/bwp-signin-redirect",
    signOutCallback: function() {
      // Placeholder for implementing the sign-out logic, such as clearing the shopper's state for the current session           }, 
    }
  };
  
  const shopperInfo = {
    name: "Jane",
    isPrime: true,
    email: "[email protected]"
  }
  
  return (
    <div>
      {/* Place the DeliveryCardReact component where desired, passing the props */}
      <DeliveryCardReact
        lwaConfig={lwaConfig}
        shopperInfo={shopperInfo}
      />
    </div>
  );
}

export default YourReactComponent;

If the shopper clicks their name in the delivery card, the following modal appears. The shopper can either click Cancel or the X icon at the top right corner to dismiss the dialog, or click Sign out.







Signed-in shopper isn't a Prime member

As the previous example mentions, to determine whether the shopper is a Prime member, call the shopperBwPEligibility query.

In the following example, bwpEligibilityStatus in shopperBwPEligibility isn't PRIME, so you set isPrime to false in the shopperInfo that you provide to the delivery card.




Example Code 
// Import the pni-web-components.js in your HTML file
<script type="module" src="/path/to/pni-web-components.js"></script>

//...Other HTML

<script>
   
    document.addEventListener('DOMContentLoaded', function() {
       const deliveryCard = document.createElement('delivery-card');
       
       deliveryCard.lwaConfig = {
           clientId: "amzn1.application-oa2-client.your-unique-client-id",
           redirectUrl: "https://mystore.com/bwp-signin-redirect",
           signOutCallback: function() {
                // Placeholder for implementing the sign-out logic, such as clearing the shopper's state for the current session           }, 
           }
       };
       
       deliveryCard.shopperInfo = {
            name: "Jane",
            email: "[email protected]",
            isPrime: false
       }

       document.body.appendChild(deliveryCard);
    });
</script>

// ...Other HTML

// YourReactComponent.jsx

import { DeliveryCardReact } from "/path/to/pni-react-components.js";

function YourReactComponent() {
  const lwaConfig = {
    clientId: "amzn1.application-oa2-client.your-unique-client-id",
    redirectUrl: "https://mystore.com/bwp-signin-redirect",
    signOutCallback: function() {
      // Placeholder for implementing the sign-out logic, such as clearing the shopper's state for the current session           }, 
    }
  };
  
  const shopperInfo = {
    name: "Jane",
    isPrime: false,
    email: "[email protected]"
  }
  
  return (
    <div>
      {/* Place the DeliveryCardReact component where desired, passing the props */}
      <DeliveryCardReact 
        lwaConfig ={lwaConfig}
        shopperInfo={shopperInfo}
      />
    </div>
  );
}

export default YourReactComponent;

If the shopper isn't a Prime member, the delivery card automatically displays the following modal.












The modal indicates that the shopper isn't a Prime member, describes Prime benefits, and says that the shopper can still choose to continue with other shipping options. The shopper can either click Close or the X icon at the top right corner to dismiss the dialog, or click Sign out.

Number of Buy with Prime items in the cart

Delivery cards can indicate how many items in the shopper's cart are eligible for Buy with Prime.

To get the number of items that are eligible for Buy with Prime, you fetch each item's buyability by using the product query. For an example, see Get the buyability status of a product.

If the status in the buyability object of the response is BUYABLE, add the product to your total of Buy with Prime items.

The following example shows a delivery card when a shopper has one Buy with Prime item in their cart (numberOfPrimeItems = 1).






Example Code 
// Import the pni-web-components.js in your HTML file
<script type="module" src="/path/to/pni-web-components.js"></script>

//...Other HTML

<script>
   
    document.addEventListener('DOMContentLoaded', function() {
       const deliveryCard = document.createElement('delivery-card');

        deliveryCard.lwaConfig = {
            clientId: LWAConfigurations.LWAClientId,
            redirectUrl: LWAConfigurations.redirectUrl,
            signOutCallback: function() {
                // Placeholder for implementing the sign-out logic, such as clearing the shopper's state for the current session           }, 
           }
        };

        deliveryeCard.numberOfPrimeItems = numberOfPrimeItems;
        
       document.body.appendChild(deliveryCard);
    });
</script>

//...Other HTML

Multiple delivery offers

If there are multiple deliveryOffers in deliveryGroups, such as in Get a delivery preview for multiple items, the delivery card doesn’t render a delivery estimate. For an example, see Delivery card: Multiple delivery offers.

This example code renders the following image.






Example Code 
// Import the pni-web-components.js in your HTML file
<script type="module" src="/path/to/pni-web-components.js"></script>

//...Other HTML

<script>
   
    document.addEventListener('DOMContentLoaded', function() {
       const deliveryCard = document.createElement('delivery-card');

       deliveryCard.lwaConfig = {
            clientId: "amzn1.application-oa2-client.your-unique-client-id",
            redirectUrl: "https://mystore.com/bwp-signin-redirect",
            signOutCallback: function() {
              // Placeholder for implementing the sign-out logic, such as clearing the shopper's state for the current session           }, 
           }
        };

       
       deliveryCard.deliveryOffers = [
           { message: "Get is as soon as Tomorrow Apr 6", errorCode: null },
           { message: "Get is as soon as Tomorrow Apr 7", errorCode: null }
       ];        
        

       document.body.appendChild(deliveryCard);
    });
</script>

//...Other HTML

// YourReactComponent.jsx

import { DeliveryCardReact } from "/path/to/pni-react-components.js";

function YourReactComponent() {

  // Define the properties for lwaConfig, deliveryOffers, and numberOfPrimeItems
  const lwaConfig = {
    clientId: "amzn1.application-oa2-client.your-unique-client-id",
    redirectUrl: "https://mystore.com/bwp-signin-redirect",
    signOutCallback: function() {
        // Placeholder for implementing the sign-out logic, such as clearing the shopper's state for the current session           }, 
    }
  };

  const deliveryOffers = [
    { message: "Get is as soon as Tomorrow Apr 6", errorCode: null },
    { message: "Get is as soon as Tomorrow Apr 7", errorCode: null }
  ];
  
  return (
    <div>
      {/* Place the DeliveryCardReact component where desired, passing the props */}
      <DeliveryCardReact 
        lwaConfig={lwaConfig}
        deliveryOffers = {deliveryOffers}
      />
    </div>
  );
}

export default YourReactComponent;

Delivery offer isn't available

This example code renders the following image.





Example Code 
// Import the pni-web-components.js in your HTML file
<script type="module" src="/path/to/pni-web-components.js"></script>

//...Other HTML

<script>
   
    document.addEventListener('DOMContentLoaded', function() {
       const deliveryCard = document.createElement('delivery-card');

        deliveryCard.lwaConfig = {
            clientId: "amzn1.application-oa2-client.your-unique-client-id",
            redirectUrl: "https://mystore.com/bwp-signin-redirect",
            signOutCallback: function() {
                // Placeholder for implementing the sign-out logic, such as clearing the shopper's state for the current session           }, 
           }
        };

        deliveryCard.numberOfPrimeItems = 1;

       document.body.appendChild(deliveryCard);
    });
</script>

//...Other HTML

// YourReactComponent.jsx

import { DeliveryCardReact } from "/path/to/pni-react-components.js";

function YourReactComponent() {

  // Define the properties for LWAConfig, deliveryOffers, and numberOfPrimeItems
  const lwaConfig = {
    clientId: "amzn1.application-oa2-client.your-unique-client-id",
    redirectUrl: "https://mystore.com/bwp-signin-redirect",
    signOutCallback: function() {
      // Placeholder for implementing the sign-out logic, such as clearing the shopper's state for the current session           }, 
    }
  };

  const numberOfPrimeItems = 1;

  return (
    <div>
      {/* Place the DeliveryCardReact component where desired, passing the props */}
      <DeliveryCardReact 
        lwaConfig={lwaConfig}
        numberOfPrimeItems={numberOfPrimeItems}
      />
    </div>
  );
}

export default YourReactComponent;

Invalid destination or invalid address error in the delivery offer

If you encounter an error, such as InvalidDestination or InvalidAddress, when you attempt to fetch a delivery preview for an authenticated shopper, you can pass the error code to the delivery offer. When you do so, the delivery card displays an informational message to the shopper about the error.

This example code renders the following image when the delivery preview returns the error delivery preview response shown in the Sample Data.






Example Code 
// Import the pni-web-components.js in your HTML file
<script type="module" src="/path/to/pni-web-components.js"></script>

//...Other HTML

<script>
   
    document.addEventListener('DOMContentLoaded', function() {
       const deliveryCard = document.createElement('delivery-card');
       
       deliveryCard.lwaConfig = {
            clientId: "amzn1.application-oa2-client.your-unique-client-id",
            redirectUrl: "https://mystore.com/bwp-signin-redirect",
            signOutCallback: function() {
                // Placeholder for implementing the sign-out logic, such as clearing the shopper's state for the current session           }, 
           }
        };
       
       deliveryCard.shopperInfo = {
            name: "Jane",
            email: "[email protected]",
            isPrime: true
       }
       
        deliveryCard.deliveryOffer = [{
            message: null, 
            errorCode: deliveryPreviewErrorResponse.data.code;
        }];            

       document.body.appendChild(deliveryCard);
    });
</script>

//...Other HTML

// YourReactComponent.jsx

import { DeliveryCardReact } from "/path/to/pni-react-components.js";

function YourReactComponent() {
   
  const lwaConfig = {
    clientId: "amzn1.application-oa2-client.your-unique-client-id",
    redirectUrl: "https://mystore.com/bwp-signin-redirect",
    signOutCallback: function() {
      // Placeholder for implementing the sign-out logic, such as clearing the shopper's state for the current session           }, 
    }
  };
  
  const shopperInfo = {
    name: "Jane",
    isPrime: true,
    email: "[email protected]"
  }
  
  const deliveryOffers = [
    { message: null, errorCode:"InvalidDestination" },
  ];
  
  return (
    <div>
      {/* Place the DeliveryCardReact component where desired, passing the props */}
      <DeliveryCardReact
        lwaConfig = {lwaConfig}
        shopperInfo = {shopperInfo}
        deliveryOffers = {deliveryOffers}
      />
    </div>
  );
}

export default YourReactComponent;

Delivery card hidden for a signed-in shopper

This example shows how to hide the delivery card after the shopper signs in, but still shows the modal about not having Prime if the authenticated shopper isn't a Prime member.

Example Code 
// Import the pni-web-components.js in your HTML file
<script type="module" src="/path/to/pni-web-components.js"></script>

//...Other HTML

<script>
   
    document.addEventListener('DOMContentLoaded', function() {
       const deliveryCard = document.createElement('delivery-card');

       deliveryCard.lwaConfig = {
            clientId: "amzn1.application-oa2-client.your-unique-client-id",
            redirectUrl: "https://mystore.com/bwp-signin-redirect",
            signOutCallback: function() {
                // Placeholder for implementing the sign-out logic, such as clearing the shopper's state for the current session           }, 
           }
        };
       
       deliveryCard.shopperInfo = {
            name: "Jane",
            email: "[email protected]",
            isPrime: true
       };       
        
       deliveryCard.showAuthenticatedCard = false; 

       document.body.appendChild(deliveryCard);
    });
</script>

//...Other HTML

// YourReactComponent.jsx

import { DeliveryCardReact } from "/path/to/pni-react-components.js";

function YourReactComponent() {

  // Define the properties for lwaConfig, deliveryOffers, and numberOfPrimeItems
  const lwaConfig = {
    clientId: "amzn1.application-oa2-client.your-unique-client-id",
    redirectUrl: "https://mystore.com/bwp-signin-redirect",
    signOutCallback: function() {
      // Placeholder for implementing the sign-out logic, such as clearing the shopper's state for the current session           }, 
    }
  };
  
  const shopperInfo = {
    name: "Jane",
    isPrime: false,
    email: "[email protected]"
  };
  
  return (
    <div>
      {/* Place the DeliveryCardReact component where desired, passing the props */}
      <DeliveryCardReact 
        lwaConfig={lwaConfig}
        shopperInfo = {shopperInfo}
        showAuthenticatedCard = false
      />
    </div>
  );
}

export default YourReactComponent;

Content is loading

If you want to load the content of a delivery card in an asynchronous fashion (after the rest of the page is loaded), you can use the loading flag, as in the following example.





Example Code 
// Import the pni-web-components.js in your HTML file
<script type="module" src="/path/to/pni-web-components.js"></script>

//...Other HTML

<script>
   
    document.addEventListener('DOMContentLoaded', function() {
       const deliveryCard = document.createElement('delivery-card');

       deliveryCard.loading = true;

       document.body.appendChild(deliveryCard);
    });
</script>

// ...Other HTML

// YourReactComponent.jsx

import { DeliveryCardReact } from "/path/to/pni-react-components.js";

function YourReactComponent() {
  
  return (
    <div>
      {/* Place the DeliveryCardReact component where desired, passing the props */}
      <DeliveryCardReact
        loading = true
      />
    </div>
  );
}

export default YourReactComponent;

Related topics

Updated 5 days ago