Checkout parameters
Passing additional parameters allows you to modify the behavior of the Paddle checkout, such as pre-filling a buyer’s email address or setting a custom message. Either JavaScript parameters or HTML attributes can be used, depending on your integration.
How to pass in parameters
Section titled “How to pass in parameters”The method of specifying checkout parameters depends on whether you have implemented your checkout using the paddle_button class or are invoking the checkout yourself by calling the Paddle.Checkout.open() method.
If you are using the paddle_button class, checkout properties must be set using data attributes on the button itself (see the HTML Attributes tab in the table below). If you are calling Paddle.Checkout.open(), the properties should be set by specifying parameters in the method call (see JavaScript Attribute column below).
See below for a simple example showing how to pass in a user email to the checkout.
Paddle.Checkout.open({ product: 12345, email: "name@example.com",});<a href="#!" class="paddle_button" data-product="12345" data-email="name@email.com" >Buy now</a>Checkout Properties
Section titled “Checkout Properties”A full list of checkout properties is shown below for use either on checkout buttons, or with the Checkout.open() method.
$ref: "../../../models/checkout-js-params.yaml"{ "type": "object", "properties": { "data-product": { "type": "string", "description": "The ID of the Paddle Product, Subscription or Bundle this checkout is for.<br/><br/> Note: this field is required if `data-passthrough` is not set.", "pattern": "\\d+" }, "data-title": { "type": "string", "description": "Override the product’s name on the checkout page.", "maxLength": 200 }, "data-message": { "type": "string", "description": "Override the message/string of text displayed under the product name on the checkout.", "maxLength": 255 }, "data-coupon": { "type": "string", "description": "Pre-fill a coupon code on the checkout.", "minLength": 5, "maxLength": 300 }, "data-email": { "type": "string", "description": "Pre-fill the customer email field on the checkout.", "format": "email" }, "data-marketing-consent": { "type": "string", "description": "Pass on consent to send marketing emails to users.<br/><br/> Note: `data-email` is also required for marketing consent to be pre-filled.", "enum": [0, 1] }, "data-country": { "type": "string", "description": "Pre-fill the customer country field on the checkout. [See supported countries](/reference/platform-parameters/supported-countries).<br/><br/> Note: `data-email` is also required for the customer country to be pre-filled.", "pattern": "[A-Z]{2}", "example": "US" }, "data-postcode": { "type": "string", "description": "Pre-fills the customer 'ZIP/Postcode' field on the checkout. [See countries requiring postcode](/reference/platform-parameters/supported-countries#countries-requiring-postcode).<br/><br/> Note: `data-country` is also required for postcode to be pre-filled." }, "data-allow-quantity": { "type": "string", "description": "Enable the quantity selector on the checkout page.", "enum": [true, false], "default": "true" }, "data-quantity": { "type": "string", "description": "Pre-fill the quantity selector on the checkout. Please note that free products/subscription plans are fixed to a quantity of 1.\n\nNote: a quantity limit of `100` applies to one-time products. Subscription plans have a quantity limit of `10000`. One-time products that use [a single webhook request for fulfilment](/webhooks/product-fulfillment/#setting-up-a-fulfillment-webhook) (with a quantity field) have a quantity limit of `1000`." }, "data-disable-logout": { "type": "string", "description": "Disable the ability for a user to logout/change email once on the checkout.", "enum": [true, false], "default": "false" }, "data-hide-tax-link": { "type": "string", "description": "Whether the user can see the option to add a tax or VAT number.", "enum": [true, false], "default": "false" }, "data-locale": { "type": "string", "description": "Force the checkout to use a specific locale/language. [See Supported Locales](/reference/platform-parameters/supported-locales).\n\nNote: by default, the checkout will automatically detect the buyer's locale/language based on their browser/computer setting." }, "data-passthrough": { "type": ["string", "object"], "description": "A string of metadata you wish to store with the checkout. Will be sent alongside all [webhooks](/webhooks/) associated with the order. See the [Pass Parameters](/guides/checkout/pass-parameters#sending-additional-user-data) documentation for more information.", "maxLength": 1000 }, "data-referrer": { "type": "string", "description": "Add a custom referrer/campaign string to be stored with the checkout." }, "data-success": { "type": "string", "description": "A URL to redirect to upon checkout completion.", "format": "uri" }, "data-success-callback": { "type": "string", "description": "The name of a Javascript function to call upon checkout completion.\n\nNote: using this callback will prevent the success checkout message from appearing. If you would like this to persist on-screen, please use the non-blocking `eventCallback` documented [here](/reference/paddle-js/checkout-events#paddlejs-event-callback) with the `Checkout.Complete` event type instead." }, "data-close-callback": { "type": "string", "description": "The name of a Javascript function to call on checkout close." }, "data-load-callback": { "type": "string", "description": "The name of a Javascript function to call upon checkout load." }, "data-upsell": { "type": "string", "description": "The ID of the Paddle Product, Subscription or Bundle you wish to prompt the user to purchase instead.<br><br>Note: this feature is not available for mobile devices.", "pattern": "\\d+" }, "data-upsell-title": { "type": "string", "description": "Customize the title of the upsell dialog. You can pass html tags and it will be rendered in the screen" }, "data-upsell-text": { "type": "string", "description": "Customize the upsell message displayed to the user. You can pass html tags and it will be rendered in the screen" }, "data-upsell-action": { "type": "string", "description": "Customize the upsell button text. You can pass html tags and it will be rendered in the screen" }, "data-upsell-coupon": { "type": "string", "description": "Pre-fill a coupon code for the upsell product.", "minLength": 5, "maxLength": 300 }, "data-upsell-passthrough": { "type": "string", "description": "A string of metadata you wish to store with the upsell product's checkout. Will be sent alongside all [webhooks](/webhooks/) associated with the order. See the [Pass Parameters](/guides/checkout/pass-parameters#sending-additional-user-data) documentation for more information.", "maxLength": 1000 }, "data-override": { "type": "string", "description": "Open the checkout with a [custom pay link](/api-reference/reference/product-api/#tag/pay-links/POST/2.0/product/generate_pay_link), [cancel URL](/guides/subscriptions/cancel-and-pause#opening-cancel-pages-as-an-overlay) or [payment method update URL](/guides/subscriptions/update-payment-details#opening-update-page-as-an-overlay).", "format": "uri" }, "data-method": { "type": "string", "enum": ["overlay", "sdk"], "description": "Specifies what display mode checkout should use to render the user interface.", "default": "overlay" } }}