Callbacks

Listen to callbacks from Paddle Checkout fired upon various user actions occurring.

Make sure you've completed Paddle.js Setup before continuing to this step!

Checkout Complete & Close Callbacks

Upon our checkout being completed successfully, or being closed/abandoned, we may wish to take some additional action, for example show a message to the user.

In the example below we set successCallback and closeCallback function callbacks, which are fired upon one of those actions happening.

Complete and Close Callbacks can also be specified within Checkout Buttons as data-success-callback and data-close-callback. When specifying callbacks within buttons, you must specify the name of a function declared elsewhere within your application.

Example

<script type="text/javascript">
  Paddle.Checkout.open({
    product: 12345,
    email: "jane@paddle.com",
    passthrough: 1939284,
    successCallback: function(data) {
      console.log(data);
      alert('Thanks for your purchase.');
    },
    closeCallback: function(data) {
      console.log(data);
      alert('Your purchase has been cancelled, we hope to see you again soon!');
    }
  });
</script>

<button class="js-buy">Upgrade to Pro</button>

Additionally to the ability to specify a closure/anonymous function, you can also pass in the name of a explicitly defined function, for example:

<script type="text/javascript">
	function checkoutClosed(data) {
		console.log(data);
		alert('Your purchase has been cancelled, we hope to see you again soon!');
	}
	
	function checkoutComplete(data) {
		console.log(data);
		alert('Thanks for your purchase.');
	}

  Paddle.Checkout.open({
    product: 12345,
    email: "jane@paddle.com",
    passthrough: 1939284,
    successCallback: "checkoutComplete",
    closeCallback: "checkoutClosed"
  });
</script>

<button class="js-buy">Upgrade to Pro</button>

Paddle will send an object containing information about the checkout to your callback functions, the data sent to successCallback and closeCallback differ slightly, a list of the information included with each is below.

Close Callback Example:

{
    "checkout": {
        "completed": false,
        "id": "4459220-chra432325e67421-fe2f8d232a",
        "coupon": null,
        "prices": {
            "customer": {
                "currency": "GBP",
                "unit": "34.95",
                "total": "34.95"
            },
            "vendor": {
                "currency": "USD",
                "unit": "43.82",
                "total": "43.82"
            }
        },
        "passthrough": null,
        "redirect_url": null
    },
    "product": {
        "quantity": 1,
        "id": "1234567",
        "name": "My Product"
    },
    "user": {
        "country": "GB",
        "email": "christian@paddle.com",
        "id": 29777
    }
}

Complete Callback Example:

{
    "checkout": {
        "completed": true,
        "id": "4451433-chrd10623c1cbd5-c8d37ad479",
        "coupon": null,
        "prices": {
            "customer": {
                "currency": "USD",
                "unit": "9.99",
                "total": "9.99"
            },
            "vendor": {
                "currency": "USD",
                "unit": "9.99",
                "total": "9.99"
            }
        },
        "passthrough": null,
        "redirect_url": null
    },
    "product": {
        "quantity": 1,
        "id": "1234567",
        "name": "My Product"
    },
    "user": {
        "country": "GB",
        "email": "christian@paddle.com",
        "id": "29777"
    }
}

Note: You may have set a success redirect within your Paddle account, specifying a successCallback will override this redirect, and cause it not to happen. If a redirect would have taken place, we pass the property redirect with a value of true to the data object passed to your callback along with the property redirectUrl which contains the URL of the page the user would have been redirected to.

Other Callback Events

In addition to (or instead of) the explictly defined Complete and Close callbacks, within your Paddle.Setup() call when setting up the library, you can specify a global ‘Event Callback’.

This callback is fired, with an object of data for various events on the checkout, for example entering an email address, supplying country data, or selecting a payment method. A full list of events Paddle.js will fire during the checkout is listed at the bottom of this document.

Unlike the Success and Close callbacks, Event Callbacks are non-blocking and will fire in the background allowing Paddle.js and the checkout to continue with its typical functionality.

Subscribing to Events

Checkout events can be subscribed to within the Setup() method of Paddle.js by specifying a callback function that event data should be sent to.

Specify the function that should be fired when an event is triggered with the eventCallback parameter within the object passed to the Setup() method.

Example

<script src="https://cdn.paddle.com/paddle/paddle.js"></script>
<script type="text/javascript">
	Paddle.Setup({
		vendor: 1234567,
		eventCallback: function(eventData) {
			// Your code...
		}
	});
</script>

To the function will be passed an object containing event data (more on this below).

Identifying Events

Paddle.js will call your event callback function each time it receives an event from the checkout. An event is fired at virtually every user interaction on the checkout, in addition to being fired for errors and other background actions.

Within the object passed to your event callback, will be the parameter event which identifies which event this is. A list of different events can be found toward the bottom of this document.

Example

{
	event: "Checkout.Loaded",
	eventData: { ... },
	checkoutData: { ... },
	campaignData: { ... }
}

Event Data Object

Each event sent will contain an object of event data. This object contains various pieces of information split into various sections:

  • event - The name of the event being fired.
  • eventData - Information passed through from the Paddle checkout.
    • checkout - Attributes about the checkout.
    • product - Attributes about the product being purchased.
    • user - Attributes about the user of the checkout.
  • checkoutData - Information about the checkout object used to build the checkout.
  • campaignData - Data Paddle collects for campaign and referrer tracking.

The format of this object is consistent between events, however additional properties may be added to the eventData.checkout object.

Example Object

{
    "event": "Checkout.Loaded",
    "eventData": {
        "checkout": {
            "completed": false,
            "id": "4450323-chre3ce4cf1138d-ec7774534f",
            "created_at": "2016-11-11 02:39:25",
            "coupon": null,
            "prices": {
                "customer": {
                    "currency": "USD",
                    "unit": "9.99",
                    "total": "9.99"
                },
                "vendor": {
                    "currency": "USD",
                    "unit": "9.99",
                    "total": "9.99"
                }
            },
            "passthrough": null,
            "redirect_url": null
        },
        "product": {
            "quantity": 1,
            "id": "1234567",
            "name": "My Product"
        },
        "user": {
            "country": "GB",
            "email": "christian@paddle.com",
            "id": "29777"
        }
    },
    "checkoutData": {
        "product": "508649",
        "successCallback": "successCallback",
        "closeCallback": "closeCallback",
        "quantity_variable": "1",
        "method": "overlay",
        "referring_domain": "facebook.com",
        "popup": "true",
        "paddle_js": "true",
        "parentURL": "http://mysite.com/testing/basic.html"
    },
    "campaignData": {
        "_Library": {
            "Version": "1.5.1",
            "LoadMethod": "Direct"
        },
        "_Request": {
            "Secure": false,
            "Domain": "mysite.com",
            "Page": "http://mysite.com/testing/basic.html",
            "Mobile": false,
            "Browser": "Chrome",
            "Platform": "Web"
        },
        "_Affiliate": {
            "IsAffiliate": false,
            "AffiliateToken": null
        },
        "_Discovery": {
            "IsDiscovery": false
        },
        "_Campaign": {
            "Referrer": {
                "Name": "Facebook",
                "Type": "Social"
            },
            "Paddle": null,
            "Name": null,
            "Source": null,
            "Medium": null,
            "Term": null,
            "CampaignSummaryString": "mysite.com / Facebook (Chrome)"
        },
        "_SDK": {},
        "_Vendor": 91
    }
}

Common Attributes

  • Email Address: eventData.checkout.user.email
  • Product Name: eventData.checkout.product.name
  • Product ID: eventData.checkout.product.id
  • Checkout Price in Vendor Currency: eventData.checkout.prices.vendor.total (Vendor currency will be consistent, regardless of user location)
  • Passthrough: eventData.checkout.passthrough
  • Checkout Hash/ID: eventData.checkout.id (This can be passed to the Order API to retrieve order information after purchase)

List of Events

The following events will be sent upon adding an event callback.

  • Checkout.Loaded - Indicates the checkout has completed loading and has been shown to the user.
  • Checkout.Error - Fired after any checkout error (including declines, incorrect coupons etc…)
  • Checkout.Login - Fired after the user enters their email address.
  • Checkout.CountryInformationEntered - Fired after a user submits their country information.
  • Checkout.PaymentMethodSelected - Fired after the user selects their method of payment.
  • Checkout.DuplicateWarningShown - Fired if the user is shown a ‘Duplicate Purchase’ warning. (Shown if a transaction for the same product, by that user was attempted in the last 60 seconds).
  • Checkout.PaymentComplete - Fired once the payment was successfully charged. (This should be used to mark a ‘conversion’).
  • Checkout.Complete - Fired once the success message is shown.
  • Checkout.Close - Fired upon the checkout closing.

Event Consistency

Paddle frequently, and silently in the background will run A/B tests on the checkout process, sometimes these tests, experiments and optimizations alter the checkout flow. This can mean that for certain checkouts, a user may be taken through an alternate checkout flow where some events are no longer applicable.

An example of this might be a test where we experiment with collecting the users Email Address and Country Information within the same checkout step. In this instance, it’s possible that the Checkout.Login and Checkout.CountryInformationEntered events might not be fired, or would be potentially combined. Additionally we may periodically add new events as we iterate on the checkout.

The only events that are garaunteed to be sent are:

  • Checkout.Open
  • Checkout.PaymentComplete

These two events are sufficent for most conversion tracking and analysis models. Other events should be used for information purposes only.

If you’d like to discuss the integrity of Checkout Events, or opt-out of A/B tests and optimizations to ensure consistency of events, please contact your Paddle account manager.

Next Steps
Now you've added Checkout Complete & Close callbacks, try some of the additional functionality available within Paddle.js to help grow your business:
Order Information
Get information about an order once the transaction completes using Paddle.js
Affiliate Tracking
Automatically track affiliate campaigns and split funds with promotional partners.
Audience
Collect user email addresses and build a customer marketing base using Paddle.js
Download Prompts & Buttons
Track downloads with Paddle.js
Was this page helpful?