Callbacks

By hooking into Paddle checkout callbacks, you can take actions based on a buyer’s interaction with your checkout, whether it’s a successful completion, an abandonment or another custom event, such as adding a coupon. Using callbacks can help you to integrate conversion tracking into an external platform, or better customize your buyer’s experience.

Checkout Success & Close Callbacks

Upon your checkout being completed successfully, or being closed/abandoned, you may wish to take additional actions, for example loading a thank you page or showing a message to the user.

The Paddle checkout supports successCallback and closeCallback parameters, which specify functions that are fired upon the checkout completing a transaction or being closed, respectively.

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>

Success and Close Callbacks can also be specified on a Paddle purchase button with the data attributes data-success-callback and data-close-callback. If setting callbacks with data attributes, you must specify an explicit JavaScript function name.

Returned data

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.

Returned data (Close Callback)

{
    "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
    }
}

Returned Data (Success Callback)

{
    "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: The successCallback will override any success redirect set in your Seller Dashboard. If a redirect would have taken place, the redirect_url property in the callback data will contain the URL of the success page set in the dashboard.

Custom Callback Events

In addition to explictly defined Success and Close callbacks you may define a global ‘Event Callback’ to handle a wider range of checkout events.

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

The eventCallback parameter should be set in the Setup() block of Paddle.js by specifying a callback function that handles event data.

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>

Identifying Events

Paddle.js will call your event callback function each time it receives an event from the checkout. The event field contains a string identifying which event it is. A list of different events is shown below:

  • 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 location information.
  • Checkout.PaymentMethodSelected - Fired after the user selects their method of payment.
  • Checkout.Coupon.Applied - Fired if a coupon is added to the checkout.
  • Checkout.Coupon.Remove - Fired if an applied coupon is removed.
  • Checkout.DuplicateWarningShown - Fired if the user is shown a ‘Duplicate Purchase’ warning. (Shown if a user attempts to purchase the same product twice).
  • 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.

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.
  • checkoutData - Information about the checkout object used to build the checkout.
  • campaignData - Data Paddle collects for campaign and referrer tracking.

Useful Attributes

Most checkout events include the following data fields:

  • 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)

Try logging event data to the console to view the full range of values returned with each event.

Event Consistency

Paddle runs A/B tests on our checkout design and 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.

The only events that are guaranteed to be sent in each completed checkout 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 have further questions about how to use callbacks in your checkout, get in touch with our team.

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

Questions about Paddle?

If you need any help regarding your Paddle integration, please get in touch with our Customer Success team using the form below.