Order Information

Get information about an order once the transaction completes using Paddle.js

Post-Checkout Order Information

In many cases you may wish to display to the user order/license/transaction information, on the ‘Success’ or ‘Thank You’ page after a checkout completes.

Paddle provides an API, and methods within Paddle.js to pull this transaction data from our API upon completed checkout.

An example of the download/license information provided for the Success Page:

{
    "state": "processed",
    "checkout": {
        "checkout_id": "3219233-chre53d41f940e0-58aqh94971",
        "image_url": "https://paddle.s3.amazonaws.com/user/91/XWsPdfmISG6W5fgX5t5C_icon.png",
        "title": "My Product"
    },
    "order": {
        "order_id": 826289,
        "total": "9.99",
        "currency": "GBP",
        "formatted_total": "£9.99",
        "completed": {
            "date": "2016-08-01 21:24:35.000000",
            "timezone_type": 3,
            "timezone": "UTC"
        },
        "receipt_url": "https://my.paddle.com/receipt/826289/3219233-chre53d41f940e0-58aqh94971",
        "has_locker": true,
        "customer": {
            "email": "christian@paddle.com",
            "marketing_consent": true
        },
        "is_subscription": false
    },
    "lockers": [
        {
            "locker_id": 1127139,
            "product_id":514032,
            "product_name":"My Product Name",
            "download": "https://mysite.com/download/my-app",
            "license_code": "ABC-123",
            "instructions": "Simply enter your license code and click 'Activate'."
        }
    ]
}

Polling for Data

As Paddle’s order processing is decentralised, order processing may take a few seconds after the transaction to complete.

This means that, as of the user landing on your Success/Thank You page, the order may not yet be processed.

We recommend polling the order data API. When processing of the order is completed, the state parameter will change to processed.

Required Data

Data can be requested from the Order API in two ways, via an API call, or using Paddle.js. If using Paddle.js the polling and retry logic for orders that are not yet processed is included automatically.

The only required parameter for the Order API is checkout_id which accepts a full checkout hash, for example: 3413183-chre03c47d940e0-58acf92974

For testing purposes, a checkout hash can be found by opening an checkout, and copying the URL.

In production, there are two ways to automatically get this checkout hash:

  1. Listening to checkout event callbacks, the object property eventData.checkout.id will contain the full checkout hash which can be used in calls to this API. (Please see ‘Checkout Events’ documentation for more details…)
  2. Navigating to the Paddle Dashboard, click ‘Edit’ on a product, under the “Set where users should go after checkout” section, you can include the variable {checkout_hash} within your URL for you to pass to the API, eg: http://mysite.com/thanks?checkout={checkout_hash}

Calling the API

Via Paddle.js

Paddle.js will automatically handle polling the API for you, firing your callback function with order information once the order has completed processing:

Paddle.Order.details('3419983-chre50c47d940e0-58acf92974', function(data) {
	// The 'data' variable will contain order information in the format described in section one.
});

Via Paddle.js in Checkout Complete Callback

One of the most common ways to use the Order API is to set a Checkout Complete Callback (See Callbacks).

Listen for a successful checkout with a Checkout Complete Callback, grab the Checkout ID from the Complete Callback and pass it to the Order API to provide an experience where a purchased download/license is immediately available to the customer on the page while they checkout.

Paddle.Checkout.open({
  product: 1234567,
  successCallback: function(data) {
    var checkoutId = data.checkout.id;
    
    Paddle.Order.details(checkoutId, function(data) {
      // Order data, downloads, receipts etc... available within 'data' variable.
      console.log(data);
    });
  }
});

Directly

You can also call the API directly.

  • Endpoint: https://checkout.paddle.com/api/1.0/order
  • Parameters:
    • checkout_id (The full checkout hash value, eg: 3419123-dfet50c47q910d0-58acf92974) - Required.
    • callback (Callback function for JSONP support) – Optional.

Example

curl -X GET https://checkout.paddle.com/api/1.0/order?checkout_id=123456-abc7def-gh89jk

Next Steps

If you haven't already, checkout out 'Callbacks' and how you can combine them with the Order Information API to build an incredible post-checkout UX.
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.

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.