Shopping/
Integrate

Integrate the PayPal Shopping SDK

DOCS

Last updated: Feb 27th, 8:40am

 

Set up your development environment

Before you can integrate the PayPal Shopping product suite, you must set up your development environment. After you get a token that lets you access protected REST API resources, you create sandbox accounts to test your web and mobile apps. For details, see Get started.

Then, return to this page to integrate the PayPal Shopping product suite.

Register your account

Use this URL to register your account with your client_id:

    1https://www.paypal.com/cartrecovery/signup?clientId= <insert_client_id>

    Install and instantiate

    This script sends an email to remind the user about their cart after information remains in their cart for about five minutes. If the user's browser contains a PayPal cookie, the email sends automatically. If their browser does not contain a PayPal cookie, a dialog box displays and asks the user if they want a copy of their cart sent to their email. The email sends at the top of the hour.

    Install script

    Set up your website to send the customer's shopping events to PayPal. Install and instantiate the SDK by adding the following code to the HEAD section of every page where you want to use it.

    1. Merchant
    2. Partners
    1<script src="https://www.paypal.com/sdk/js?client-id=<insert_production_client_ID>&currency=USD&components=buttons,tracker,messaging"></script>
    VariableDescription
    client-idFor merchants, this is the production client id. For partners, this is the partner client id.
    merchant-idFor partners only.


    Initialize script

    After loading the script into the pages, initialize the script. Depending on how your application manages JavaScript scopes, you may want to initialize the messaging object and the tracker object as shown in this example:

      1var uniqueId = Date.now(); //or your unique session ID
      2paypal.Messaging({
      3  cartRecovery: {
      4    userId: uniqueId
      5  }
      6});
      7var tracker = paypal.Tracker({});
      8tracker.setUser({
      9  user: {
      10    id: uniqueId,
      11    name: "example_name",
      12    email: "example_name@example.com"
      13  }
      14});

      Track information

      Use the tracker object to track information added or removed from the cart. In the script, you must include an id, title, url and imgUrl. You can include other fields from your item's JSON such as weight, tax, or barcodes.

      FieldDescription
      idThe item ID
      titleThe subject line in the email to the customer
      urlThe link to the item in the customer's cart
      imgUrlThe link to the image of the item in the customer's cart

      This script tracks information added to a cart:

        1tracker.addToCart({cartId, items: [{
        2  id: itemId,
        3  title: 'Product Title',
        4  url: 'https://example.com/myitemid',
        5  imgUrl: 'https://example.com/images/items/myitemid.jpg',
        6  price: '1.00'
        7}], total: total.toFixed(2)
        8});

        This script tracks information removed from a cart:

          1tracker.removeFromCart({cartId, items: [{
          2  id: itemId,
          3  title: 'Product Title',
          4  url: 'https://example.com/myitemid',
          5  imgUrl: 'https://example.com/images/items/myitemid.jpg',
          6  price: '1.00'
          7}], total: total.toFixed(2)
          8});

          This script deletes the record when the customer completes checkout:

            1tracker.purchase({
            2  cartId
            3});

            Track shopper activity on your site

            After you install and instantiate the SDK on your pages, you can track shoppers. The PayPal Shopping SDK uses shopping events to identify shoppers and understand their behavior on your site. Using events, PayPal can build a representation of a shopper's cart and keep track of whether the shopper makes a purchase.

            PayPal Tracker is JavaScript code that tracks visitor activity on your website. Use the following JavaScript functions from the PayPal Shopping SDK to implement PayPal Tracker.

            Initialize

            Instantiate the paypal.Tracker global variable before using it to send events.

            paypal.Tracker.(params)

            NameTypeRequiredDescription
            userobjectnoContains the shopper's data.
            user.idstringnoThe id of the shopper in your system. You can use the shopper's email if you don't maintain user ids.
            user.emailstringnoThe shopper's email.
            user.namestringnoThe shopper's name as you want it to appear in your reports and emails.

            paypal.Tracker (params) Example

              1paypal.Tracker({
              2  user: {
              3    id: '3837394700',
              4    email: 'john@doe.com',
              5    firstName: 'John',
              6    lastName: 'Doe'
              7  }
              8})

              Set user

              If you know who the visitor is, use the setUser function. All events emitted on the page are attributed to this visitor.

              Parameters

              NameTypeRequiredDescription
              userobjectnoContains the shopper data.
              user.idstringnoThe id of the shopper in your system. You can use the shopper's email if you don't maintain user ids.
              user.emailstringnoThe shopper's email.
              user.firstNamestringnoThe shopper's first name, as you want it to appear in your reports.
              user.lastNamestringnoThe shopper's last name, as you want it to appear in your reports.

              paypal.Tracker.setUser(params) Example

                1/*
                2 * Example of an event emitted when a known user visits your website.
                3 */
                4paypal.Tracker.setUser({
                5  user: {
                6    id: '3837394700',
                7    email: 'john@doe.com',
                8    firstName: 'John',
                9    lastName: 'Doe'
                10  }
                11})

                paypal.Tracker.view(params)

                Use this function to report on what page is being viewed. This function helps you build an audience in PayPal for targeting your visitors with PayPal's marketing products. PayPal recommends you use relative URIs for this.

                Parameters

                NameTypeRequiredDescription
                pagestringyesThe URI of the page. Can be absolute or relative.
                titlestringnoThe title of the page. Defaults to the site's title if not given.

                paypal.Tracker.view(params) Example

                  1/*
                  2 * Example of an event emitted when a visitor lands on a page
                  3 */
                  4 paypal.Tracker.view({
                  5  xspage:  'carts/1000',
                  6  title: 'Cart Page'
                  7})

                  Carts

                  The following functions help you track cart-related events. To run an effective targeted campaign, cart-related functions are crucial.

                  paypal.Tracker.addToCart(params)

                  Triggers when a user adds items to a cart.

                  NameTypeRequiredDescription
                  cartIdstringnoThe shopping cart's identifier in your system. If you do not supply an ID, PayPal generates a random one.
                  totalstringnoThe total price of the cart. If none is provided, PayPal totals the value of all the items in the cart.
                  currencyCodestringnoUses ISO 4217 Currency Code. Defaults to usd if not present.
                  itemsarrayyesAn array of item objects.
                  items[n].idarrayyesThe ID of the item. Use the SKU if available.
                  items[n].titlearraynoThe name of the item.
                  items[n].urlarraynoThe URL of the item. If you use relative URLs, PayPal infers the absolute URL based on the site's URL.
                  items[n].descriptionnoyesDescription of the item.
                  items[n].imageUrlstringnoThe primary image's absolute URL.
                  items[n].otherImagesstringnoComma-separated urls of other images.
                  items[n].keywordsstringnoComma-separated search keywords.
                  items[n].pricestringnoThe price of the item.
                  items[n].quantitystringnoThe number of units of this item.

                  paypal.Tracker.addToCart(params) Example

                    1/*
                    2 * Example of an event emitted when an item is added to cart
                    3 */
                    4paypal.Tracker.addToCart({
                    5  cartId: '3938349999',
                    6  items: [{
                    7    id: '01120000',
                    8    name: 'Blue Jeans',
                    9    url: '/products/blue-jeans',
                    10    description: 'The original zip fly. First created in 2000, the Regular Fit Jeans',
                    11    imgUrl: 'https://myshop.com/products/blue-jeans.jpg'
                    12    otherImages: 'https://myshop.com/products/blue-jeans-1.jpg,https://myshop.com/products/blue-jeans-2.jpg',
                    13    keywords: 'jeans,blue,relax',
                    14    price: '34.00'
                    15  }],
                    16  total: '34.00',
                    17  currencyCode: 'usd'
                    18})

                    paypal.Tracker.setCart(params)

                    This function sets the cart for the current visitor. It takes the same parameters as addToCart.

                    paypal.Tracker.removeFromCart(params)

                    This function removes items from the current cart. It takes the same parameters as addToCart.

                    paypal.Tracker.purchase(params)

                    This function marks a specific cart as purchased. If you do not provide the cart ID, PayPal uses a last known un-purchased cart ID.

                    NameTypeRequiredDescription
                    cartIdstringnoThe shopping cart's identifier in your system. If you do not supply an ID, PayPal generates a random one.


                      1/*
                      2 * Example of an event emitted when an a cart is purchased
                      3 */
                      4paypal.Tracker.purchase({
                      5  cartId: '3938349999'
                      6})

                      Send shopping cart reminders

                      After you add the Shopping SDK to your site, PayPal can detect when a shopper begins a PayPal transaction but does not complete it. In this instance, PayPal automatically sends a cart reminder email to shoppers who have not completed a purchase. Sellers can track the performance of these emails from the client dashboard provided in the Onboard your seller section.

                      Rebuild abandoned shopping carts

                      When you notice a shopper abandons a cart, you can recover and rebuild it. When a shopper clicks a link in a cart recovery email, PayPal passes the cart ID as a parameter to this link. You can use this cart ID to rebuild the shopper's cart.

                      Onboard your seller

                      In order to capture the seller's information and opt-in to PayPal Shopping, you must create an onboarding flow for your seller.

                      1. Present your seller with a UI element, such as a checkbox, to enable PayPal Shopping in your platform.
                      2. When they have checked the box, present a link for the seller to Manage PayPal Shopping that links to https://www.paypal.com/cartrecovery/signup?partnerUrl=RETURN_URL&clientId=CLIENT_ID. Replace RETURN_URL with the URL you want PayPal to redirect the seller to when they're done setting up PayPal Shopping. Replace CLIENT_ID with the seller's PayPal Client ID. This is the PayPal Shopping dashboard where the seller can manage configuration details.

                      Once the seller has enabled PayPal Shopping, the link goes to their Performance Dashboard, where they can monitor the performance of their Cart Recovery emails.

                      ReferencePayPal.comPrivacyCookiesSupportLegalContact

                      If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more