# HTML Variables for PayPal Payments Standard (/archive/paypal-payments-standard/integration-guide/Appx-websitestandard-htmlvariables)
> **Warning:** This product is [deprecated](/archive/product-lifecycle) and should not be used for new integrations. Use [Payment Links and Buttons](/payment-links-buttons/overview) instead. For information about migrating, visit the [Upgrade Hub](https://developer.paypal.com/upgrade/wps/guide/).
PayPal Payments Standard payment buttons and the Cart Upload command support the following HTML variables.
> **Note:** **Note:** For deprecated variables, see [deprecated variables](#deprecated-variables).
## Technical variables [#technical-variables]
Technical HTML variables control how PayPal responds technically when people click PayPal payment buttons or when third-party shopping carts or solution providers initiate payment processing with the Cart Upload command. They also control how your buttons interact with special PayPal features.
> **Note:** **Note:** Use the HTML `IMG` tag to display the button on your web page.
> **Note:** **Note:** Use the HTML
>
> * The US, UK, Canada, and Australia can use [PayPal Subscriptions](/subscriptions/about) for recurring payments.
> * The US and UK can use PayPal Credit. Contact PayPal for information on enabling PayPal Credit.
> **Note:**
>
> ```html lineNumbers
> src="https://www.paypalobjects.com/webstatic/en_US/i/btn/png/btn_buynow_107x26.png"
> alt="Buy Now"
> />
> ```
**Valid values for the cmd variable**
| `cmd` value | Description |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `_xclick` | The button that the person clicked was a Buy Now button. |
| `_cart` | For shopping cart purchases. The following variables specify the kind of shopping cart button that the person clicked: `add`. Add to Cart buttons for the PayPal Shopping Cart`display`. View Cart buttons for the PayPal Shopping Cart`upload`. The Cart Upload command for third-party carts |
| `_xclick-subscriptions` | The button that the person clicked was a Subscribe button. |
| `_xclick-auto-billing` | The button that the person clicked was an Automatic Billing button. |
| `_donations` | The button that the person clicked was a Donate button. |
| `_s-xclick` | The button that the person clicked was protected from tampering by using encryption, or the button was saved in the merchant's PayPal account. PayPal determines which kind of button was clicked by decoding the encrypted code or by looking up the saved button in the merchant's account. |
**Valid values for the cmd variable**
| value | Description |
| ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `_xclick`Optional | The URL to which PayPal posts information about the payment, in the form of Instant Payment Notification messages.Character Length: 255 |
| `_cart`Requirement exception Required for buttons that have been saved in PayPal accounts. Otherwise, not allowed. | For shopping cart purchases. The following variables specify the kind of shopping cart button that the person clicked: > **Note:** **Note:** A merchant's PayPal account can have a maximum of 1,000 saved payment buttons. |
| `_xclick-subscriptions`Optional | An identifier of the source that built the code for the button that the buyer clicked, sometimes known as the *build notation*. Specify a value using the following format: `text lineNumbers Company_Service_Product_Country ` Substitute `` with an appropriate value: `BuyNow` > **Note:** **Important:** The `BuyNow` is deprecated. For new integrations, see [Customize the PayPal Checkout Button](/checkout).`AddToCart``Donate``Subscribe``AutomaticBilling``ShoppingCart` Substitute `` with `WPS` always for PayPal Payments Standard payment buttons and for the PayPal Payments Standard Cart Upload command. Substitute `` with an appropriate two-letter country code from codes defined by the [ISO 3166-1](http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements) standard. For example, a Buy Now button on your website that you coded yourself might have the following line of code: `bn="DesignerFotos_BuyNow_WPS_US"` > **Note:** **Note:** HTML button code that you create on the PayPal website includes `bn` variables with valid PayPal-generated values. |
## Individual items variables [#individual-items-variables]
These individual item variables specify information about a product or service for Buy Now and Add to Cart buttons, or they specify information about a contribution for Donate buttons.
| Name | Description |
| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `amount`See description for requirement | The price or amount of the product, service, or contribution, not including shipping, handling, or tax. If you omit this variable from Buy Now or Donate buttons, buyers enter their own amount at the time of payment. Required for Add to Cart buttonsOptional for Buy Now and Donate buttonsNot used with Subscribe buttons. |
| `discount_amount `Optional | Discount amount associated with an item, which must be less than the selling price of the item. If you specify `discount_amount` and `discount_amount2` is not defined, this flat amount is applied regardless of the quantity of items purchased. Valid only for Buy Now and Add to Cart buttons. |
| `discount_amount2`Optional | Discount amount associated with each additional quantity of the item, which must be equal to or less than the selling price of the item. For `discount_amount2` to take effect, you must also specify a `discount_amount`that is greater than or equal to `0`. Valid only for Buy Now and Add to Cart buttons. |
| `discount_rate`Optional | Discount rate, as a percentage, associated with an item. Set to a value less than 100. If you do not set `discount_rate2`, the value in `discount_rate` applies only to the first item regardless of the quantity of items purchased. Valid only for Buy Now and Add to Cart buttons. |
| `discount_rate2`Optional | Discount rate, as a percentage, associated with each additional quantity of the item. Must be equal to or less than `100`. For `discount_rate2` to take effect, you must also specify a `discount_rate` that is greater than or equal to `0`. Valid only for Buy Now and Add to Cart buttons. |
| `discount_num`Optional | Number of additional quantities of the item to which the discount applies. Applicable when you specify `discount_amount2` or `discount_rate2`. Specifies an upper limit on the number of discounted items. Valid only for Buy Now and Add to Cart buttons. |
| `item_name`See description for requirement | Description of item. If you omit this variable, buyers enter their own name during checkout. Optional for Buy Now, Donate, Subscribe, Automatic Billing, and Add to Cart buttons Character length: 127 |
| `item_number`See description for requirement | Pass-through variable for you to track product or service purchased or the contribution made. The value you specify is passed back to you upon payment completion. Required if you want PayPal to track either inventory or profit and loss for the item the button sells.Character length: 127 |
| `quantity`Optional | Number of items. If profile-based shipping rates are configured with a basis of quantity, the sum of `quantity` values is used to calculate the shipping charges for the payment. PayPal appends a sequence number to uniquely identify the item in the PayPal Shopping Cart. For example, `quantity1`, `quantity2`, and so on. > **Note:** **Note:** The value for `quantity` must be a positive integer. Null, zero, or negative numbers are not allowed. |
| `shipping`Optional | The cost of shipping this item. If you specify `shipping` and `shipping2` is not defined, this flat amount is charged regardless of the quantity of items purchased. This `shipping` variable is valid only for Buy Now and Add to Cart buttons. By default, if profile-based shipping rates are configured, buyers are charged an amount according to the shipping methods they choose. |
| `shipping2`Optional | The cost of shipping each additional unit of this item. If you omit this variable and profile-based shipping rates are configured, buyers are charged an amount according to the shipping methods they choose. This `shipping` variable is valid only for Buy Now and Add to Cart buttons. |
| `tax`Optional | Transaction-based tax override variable. Set this variable to a flat tax amount to apply to the payment regardless of the buyer's location. This value overrides any tax settings set in your account profile. Valid only for Buy Now and Add to Cart buttons. By default, profile tax settings, if any, apply. |
| `tax_rate`Optional | Transaction-based tax override variable. Set this variable to a percentage that applies to the `amount` multiplied by the quantity selected during checkout. This value overrides any tax settings set in your account profile. A valid value is from `0.001` to `100`. Valid only for Buy Now and Add to Cart buttons. By default, profile tax settings, if any, apply. Character length: 6 |
| `undefined_quantity`Optional | Enables buyers to specify the quantity. For example, `1`. Optional for Buy Now buttons.Not used with other buttons. Character length: 1 |
| `weight`Optional | Weight of items. If profile-based shipping rates are configured with a basis of weight, the sum of `weight` values is used to calculate the shipping charges for the payment. A valid value is a decimal number with two significant digits to the right of the decimal point. |
| `weight_unit`Optional | The unit of measure if `weight` is specified. Valid value is `lbs` or `kgs`. Default is `lbs`. |
| `on0`Optional | First option field name and label. The `os0` variable contains the corresponding value for this option field. For example, if `on0` is `size`, `os0` could be `large`. Optional for Buy Now, Add to Cart, Subscribe, and Automatic Billing buttons.Not used with Donate buttons. Character length: 64 |
| `on1`Optional | Second option field name and label. The `os1` variable contains the corresponding value for this option field. For example, if `on1` is `color` then `os1` could be `blue`. You can specify a maximum of 7 option field names (6 with Subscribe buttons) by incrementing the option name index (`on0` through `on6`). Optional for Buy Now, Add to Cart, Subscribe, and Automatic Billing buttons.Not used with Donate buttons. Character length: 64 |
| `os0`Optional | Option selection of the buyer for the first option field, `on0`. If the option field is a dropdown menu or a set of radio buttons, each valid value is no more than 64 characters. If buyers enter this value in a text field, the maximum value is 200 characters long. > **Note:** **Note:** The option field `on0` must also be defined. For example, it could be `size`. For priced options, include the price and currency symbol in the text of the option selections: `html lineNumbers ` Add a corresponding `option_select0` and `option_amount0` variable for each priced option. Priced options are supported only for Buy Now and Add to Cart buttons. Only one dropdown menu option selection can have priced options. Optional for Buy Now, Add to Cart, Subscribe, and Automatic Billing buttons.Not used with Donate buttons. Character length: 64 or 200, see above |
| `os1`Optional | Option selection of the buyer for the second option field, on1. If the option field is a dropdown menu or a set of radio buttons, each valid value is no more than 64 characters. If buyers enter this value in a text field, the maximum value is 200 characters long. You can specify a maximum of seven option selections (6 with Subscribe buttons) by incrementing the option selection index (`os0` through `os6`). You can implement up to five option selections as dropdown menus and up to two option selections as test boxes. > **Note:** **Note:** A corresponding option field (`on0` through `on6`) must be defined. Optional for Buy Now, Add to Cart, Subscribe, and Automatic Billing buttons.Not used with Donate buttons. Character length: 64 or 200, see above |
| `option_index`See description for requirements | The cardinal number of the option field, `on0` through `on9`, that has product options with different prices for each option. Include option\_index if the option field with prices is not `on0`. Optional for Buy Now, Add to Cart, Subscribe, and Automatic Billing, buttons.Not used with Donate buttons. Default is `0`. |
| `option_select0`Optional | For priced options, the value of the first option selection of the `on0` dropdown menu. The values must match exactly: `html lineNumbers ... ` Optional for Buy Now, Add to Cart, Subscribe, and Automatic Billing buttons.Not used with Donate buttons. Character length: 64 |
| `option_amount0`Optional | For priced options, the amount that you want to charge for the first option selection of the `on0` dropdown menu. Use only numeric values; the currency is taken from the `currency_code` variable. For example: `html lineNumbers ... ` You can specify a maximum of 10 option selections by incrementing the option selection index (`option_select0` through `option_select9`). > **Note:** **Note:** You must also set a corresponding `os0` option selection. Optional for Buy Now, Add to Cart, Subscribe, and Automatic Billing buttons.Not used with Donate buttons. Character length: 64 |
| `option_amount1`Optional | For priced options, the amount that you want to charge for the second option selection of the `on0` dropdown menu. For example: `html lineNumbers ... ... ` You can specify a maximum of 10 option amounts by incrementing the option amount index (`option_amount0` through `option_amount9`). > **Note:** **Note:** You must also set a corresponding `os0` option selection. Optional for Buy Now, Add to Cart, Subscribe, and Automatic Billing buttons.Not used with Donate buttons. Character length: 64 |
## Payment transaction variables [#payment-transaction-variables]
Payment transaction variables provide information about entire payments, regardless of the individual items involved with the payment. You can use these variables with Add to Cart buttons and the Cart Upload command.
| Name | Description |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `address_override`Optional | `1`. The address specified with automatic fill-in variables overrides the PayPal member's stored address. Buyers see the addresses that you pass in, but they cannot edit them. PayPal does not show addresses if they are invalid or omitted. For more information, see the [Auto-fill PayPal checkout page variables](#auto-fill-paypal-checkout-page-variables). Character Length: 1 |
| `currency_code`Optional | The currency of the payment. Default is `USD`. For valid values, see [Currencies Supported by PayPal](/api/nvp-soap/currency-codes#multi-currency-support-for-paypal-payments). Character Length: 3 |
| `custom`Optional | Pass-through variable for your own tracking purposes, which buyers do not see. By default, no variable is passed back to you. Character Length: 256 |
| `handling`Optional | Handling charges. This variable is not quantity-specific. The same handling cost applies, regardless of the number of items on the order. By default, no handling charges are included. |
| `invoice`Optional | Pass-through variable you can use to identify your invoice number for this purchase. By default, no variable is passed back to you. Character Length: 127 |
| `tax_cart`Optional | Cart-wide tax, overriding any individual item `tax_x` value |
| `weight_cart`Optional | If profile-based shipping rates are configured with a basis of weight, PayPal uses this value to calculate the shipping charges for the payment. This value overrides the `weight` values of individual items. A valid value is a decimal number with two significant digits to the right of the decimal point. |
| `weight_unit`Optional | The unit of measure if `weight_cart` is specified. Valid value is `lbs` or `kgs`. Default is `lbs`. |
## Shopping cart variables [#shopping-cart-variables]
Use these shopping carts variables with Add to Cart buttons, as well as with third-party shopping carts or custom carts that initiate payment processing with the Cart Upload command.
> **Note:** **Note:** PayPal recommends passing no more than 25 items in a single button or Cart Upload command.
| Name | Description |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `add`See description for requirements | Add an item to the PayPal Shopping Cart. Set this variable, as follows: `text lineNumbers add="1" ` Alternatively, use the `display="1"` variable, which displays the contents of the PayPal Shopping Cart to the buyer. If you specify both `add` and `display`, `display` takes precedence. Character Length: 1 |
| `amount_x `Required | The amount associated with item `x`. To pass an aggregate amount for the entire cart, use `amount_1`. Applies only to the Cart Upload command. |
| `business`Required | Your PayPal ID or an email address associated with your PayPal account. Email addresses must be confirmed. |
| `discount_amount_cart`Optional | Single discount amount charged cart-wide. It must be less than the selling price of all items combined in the cart. This variable overrides any individual item `discount_amount_x` values, if present. Applies only to the Cart Upload command. > **Note:** **Note:** Not applicable if using individual tax amounts *`tax_x`*. |
| `discount_amount_x`Optional | The discount amount associated with item `x`. It must be less than the selling price of the associated item. This amount is added to any other item discounts in the cart. Applies only to the Cart Upload command. |
| `discount_rate_cart`Optional | Single Discount rate, as a percentage, to be charged cart-wide. Set to a value less than 100. The variable overrides any individual item `discount_rate_x` values, if present. Applies only to the Cart Upload command. > **Note:** **Note:** Not applicable if using individual tax amounts *`tax_x`*. |
| `discount_rate_x`Optional | The discount rate associated with item `x`. Set to a value less than 100. The variable takes into account all quantities of item `x`. Applies only to the Cart Upload command. |
| `display`See description for requirements | Display the contents of the PayPal Shopping Cart to the buyer. This variable must be set as follows: `text lineNumbers display="1" ` The alternative is the `add="1"` variable, which adds an item to the PayPal Shopping Cart. If both `add` and `display` are specified, `display` takes precedence. Character Length: 1 |
| `handling_cart`Optional | Single handling fee charged cart-wide. If `handling_cart` is used in multiple Add to Cart buttons, the `handling_cart` value of the first item is used. |
| `item_name_x`Required | The name associated with item `x`. To pass an aggregate name for the entire cart, use `item_name_1`. Applies only to the Cart Upload command. |
| `paymentaction`Optional | Indicates whether the payment is a final sale or an authorization for a final sale, to be captured later. Valid value is `sale`, `authorization`, or `order`. Default is `sale`. To place a hold on the PayPal account for the authorized amount, set this value to `authorization`. To authorize the payment without placing a hold on the PayPal account, set this value to `order`. > **Note:** **Important:** If you set `paymentaction` to `order`, use the Authorization & Capture API to authorize and capture payments. The Merchant Services on the PayPal website let you capture payments only for authorizations but not for orders. |
| `quantity_x`Optional | The quantity associated with item `x` that is uploaded from a shopping cart. To pass an aggregate quantity for the entire cart, use `quantity_1`. |
| `shopping_url`Optional | The URL of the page on the merchant website that buyers go to when they click the Continue Shopping button on the PayPal Shopping Cart page. For more information see [Continue shopping on current the merchant web page](/archive/paypal-payments-standard/integration-guide/html-example-cart#continue-shopping-on-the-current-merchant-web-page). |
| `upload`See description for requirements | Upload the contents of a third-party shopping cart or a custom shopping cart. Set this variable as follows: `text lineNumbers upload="1" ` Alternatively, use the `add="1"` variable and the `display="1"` variables with the PayPal Shopping Cart. Character Length: 1 |
## Recurring payment variables [#recurring-payment-variables]
Recurring payments variables set terms for different PayPal automatic payment plans. Recurring payment buttons are:
* Subscribe
* Automatic Billing
**Subscribe variables**
| Name | Description |
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `business`Required | Your PayPal ID or an email address associated with your PayPal account. Email addresses must be confirmed. |
| `item_name`Optional | Description of item being sold. If you are collecting aggregate payments, the value can be a summary of all items purchased, a tracking number, or a generic term such as, `subscription`. If you omit this variable, buyers see a field in which they can enter the item name.Character Length: 127 |
| `currency_code`Optional | The currency of prices for trial periods and the subscription. Default is `USD`. For valid values, see [Currencies Supported by PayPal](/api/nvp-soap/currency-codes#multi-currency-support-for-paypal-payments). Character Length: 3 |
| `a1`Optional | Trial period 1 price. For a free trial period, specify `0`. |
| `p1`See description for requirements | Trial period 1 duration. Required if you specify `a1`. Specify an integer value in the valid range for the units of duration that you specify with `t1`.Character Length: 2 |
| `t1`Required if you specify `a1` | Trial period 1 units of duration. Valid value is: `D`. Days. Valid range for `p1` is `1` to `90`.`W`. Weeks. Valid range for `p1` is `1` to `52`.`M`. Months. Valid range for `p1` is `1` to `24`.`Y`. Years. Valid range for `p1` is `1` to `5`. Character Length: 1 |
| `a2`Optional | Trial period 2 price. Can be specified only if you also specify `a1`. |
| `p2`See description for requirements | Trial period 2 duration. Required if you specify `a2`. Specify an integer value in the valid range for the units of duration that you specify with `t2`.Character Length: 2 |
| `t2`See description for requirements | Trial period 2 units of duration. Valid value is: `D`. Days. Valid range for `p2` is `1` to `90`.`W`. Weeks. Valid range for `p2` is `1` to `52`.`M`. Months. Valid range for `p2` is `1` to `24`.`Y`. Years. Valid range for `p2` is `1` to `5`. Character Length: 1 |
| `a3`Required | Regular subscription price. |
| `p3`Required | Subscription duration. Specify an integer value in the Valid range for the units of duration that you specify with `t3`.Character Length: 2 |
| `t3`Required | Regular subscription units of duration. Valid value is: `D`. Days. Valid range for `p3` is `1` to `90`.`W`. Weeks. Valid range for `p3` is `1` to `52`.`M`. Months. Valid range for `p3` is `1` to `24`.`Y`. Years. Valid range for `p3` is `1` to `5`. Character Length: 1 |
| `src`Optional | Recurring payments. Subscription payments recur unless subscribers cancel their subscriptions before the end of the current billing cycle or you limit the number of times that payments recur with the value that you specify for `srt`. Valid value is: 0. Subscription payments do not recur.1. Subscription payments recur. Default is 0. Character Length: 1 |
| `srt`Optional | Recurring times. Number of times that subscription payments recur. Specify an integer with a minimum value of 2 and a maximum value of 52. Valid only if you specify `src="1"`.Character Length: 1 |
| `sra`Optional | Reattempt on failure. If a recurring payment fails, PayPal attempts to collect the payment two more times before canceling the subscription. Valid value is: 0. Do not reattempt failed recurring payments.1. Reattempt failed recurring payments before canceling. Default is `1`. For more information, see [Reattempting Failed Recurring Payments with Subscribe Buttons](/archive/paypal-payments-standard/integration-guide/html-example-subscribe#reattempted-payments). Character Length: 1 |
| `no_note`Required | Do not prompt buyers to include a note with their payments. Valid value is from Subscribe buttons: 1. Hide the text box and the prompt. For Subscribe buttons, always set `no_note` to `1`. Character Length: 1 |
| `custom`Optional | User-defined field which PayPal passes through the system and returns to you in your merchant payment notification email. Subscribers do not see this field.Character Length: 255 |
| `invoice`Optional | User-defined field which must be unique with each subscription. The invoice number is shown to subscribers with the other details of their paymentsCharacter Length: 127 |
**Subscribe variables**
| Name | Description |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `business`Required | Specify whether to let buyers enter maximum billing limits in a text box or choose from a list of maximum billing limits that you specify. Valid value is: `max_limit_own`. your button displays a text box for buyers to enter their own maximums above a minimum billing limit that you set with the `min_amount` variable.`max_limit_defined`. your button displays a dropdown menu of product options with prices to let buyers choose their maximum billing limits. |
| `item_name`Optional | The minimum monthly billing limit, if you have one. Valid only if `subscription` = `max_limit_own`. |
## PayPal checkout page variables [#paypal-checkout-page-variables]
These variables control how PayPal checkout pages appear and function.
| Name | Description |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `image_url`Optional | The URL of the 150x50-pixel image displayed as your logo in the upper left corner of the PayPal checkout pages. Default is your business name, if you have a PayPal Business account or your email address, if you have PayPal Premier or Personal account. Character Length: 1,024 |
| `lc`Optional | The locale of the checkout login or sign-up page. PayPal provides localized checkout pages for some countries and languages. For more information about locale codes and a list of supported locales, see the [PayPal locale codes](/api/codes/locale) reference page. Character Length: 5 |
| `no_shipping`Optional | Do not prompt buyers for a shipping address. Valid value is: `0`. Prompt for an address, but do not require one.`1`. Do not prompt for an address.`2`. Prompt for an address and require one. Default is `0`. Character Length: 1 |
| `return`Optional | The URL to which PayPal redirects buyers' browser after they complete their payments. For example, specify a URL on your site that displays a thank you for your payment page. By default, PayPal redirects the browser to a PayPal webpage. Character Length: 1,024 |
| `rm`Optional | Return method. The `FORM ``METHOD` used to send data to the URL specified by the `return` variable. Valid value is: `0`. All shopping cart payments use the `GET` method.`1`. The buyer's browser is redirected to the return URL by using the `GET` method, but no payment variables are included.`2`. The buyer's browser is redirected to the return URL by using the `POST` method, and all payment variables are included. Default is `0`. > **Note:** **Note:** The `rm` variable takes effect only if the `return` variable is set and Payment Data Transfer is disabled. Character Length: 1 |
| `cancel_return`Optional | A URL to which PayPal redirects the buyers' browsers if they cancel checkout before completing their payments. For example, specify a URL on your website that displays the Payment Canceled page. By default, PayPal redirects the browser to a PayPal webpage. Character Length: 1,024 |
## Auto-fill PayPal checkout page variables [#auto-fill-paypal-checkout-page-variables]
HTML variables for filling out PayPal checkout pages automatically let you specify information about buyers. PayPal recommends that you include automatic fill-out variables with all of your payment buttons for consistent address handling in the checkout experience of your buyers. To determine how the checkout experience varies if you do not pass in automatic fill-out variables, see [Address Handling (U.S. Merchants Only)](/archive/paypal-payments-standard/integration-guide/Appx-BillingShippingAddress).
> **Note:** **Note:** When you pass in `address_override=1` or tax or shipping variables, PayPal displays the values in the payment widget. Also, PayPal hides the calculation widget, regardless of setting up shipping and tax rates in your Account Profile.
| Name | Description |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `address1`Optional | Street (1 of 2 fields)Character Length: 100 |
| `address2`Optional | Street (2 of 2 fields)Character Length: 100 |
| `city`Optional | CityCharacter Length: 40 |
| `country`Optional | Sets shipping and billing country. For valid values, see [Country and Region Codes](/api/nvp-soap/country-codes/). Character Length: 2 |
| `email`Optional | Email addressCharacter Length: 127 |
| `first_name`Optional | First nameCharacter Length: 32 |
| `last_name`Optional | Last nameCharacter Length: 32 |
| `lc`Optional | Sets the language for the billing information/log-in page only. Default is `US`. For valid values, see [Countries and Regions Supported by PayPal](/api/nvp-soap/country-codes/). Character Length: 2 |
| `charset`Optional | Sets the character set and character encoding for the billing information/log-in page on the PayPal website. In addition, this variable sets the same values for information that you send to PayPal in your HTML button code. Default is based on the language encoding settings in your account profile. For valid values, see [Setting the Character Set — charset](/archive/paypal-payments-standard/integration-guide/formbasics). |
| `night_phone_a`Optional | The area code for U.S. phone numbers, or the country code for phone numbers outside the U.S. PayPal fills in the buyer's home phone number automatically.see above |
| `night_phone_b`Optional | The three-digit prefix for U.S. phone numbers, or the entire phone number for phone numbers outside the U.S., excluding country code. PayPal fills in the buyer's home phone number automatically.see above |
| `night_phone_c`Optional | The four-digit phone number for U.S. phone numbers. PayPal fills in the buyer's home phone number automatically.see above |
| `state`Optional | U.S. state. For valid values, see [PayPal state and province codes](/api/nvp-soap/state-codes/). Character Length: 2 |
| `zip`Optional | Postal code.Character Length: 32 |
## Instant Update API variables [#instant-update-api-variables]
Set up the Cart Upload command for the Instant Update API callback. Establish your own Instant Update callback server before you use these variables. HTML variables for the Instant Update API set up the Cart Upload command for the Instant Update API callback. Establish your own Instant Update callback server before you use these variables.
### Set up a payment for the Instant Update API [#set-up-a-payment-for-the-instant-update-api]
Some Instant Update variables set up the Cart Upload to use your callback server. Include the following required variables in the Cart Upload command to have PayPal send Instant Update requests to your callback server. Include the following optional variables when appropriate.
| Name | Description |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `callback_url`Required | The URL of your Instant Update callback serverCharacter Length: 1024 |
| `callback_timeout`Required | The timeout in seconds for callback responses from your Instant Update callback server. After exceeding the timeout, PayPal uses the fallback values on the Review Your Payment page for tax, shipping, and insurance. Valid value is from `1` through `6`. PayPal recommends the value `3`. > **Note:** **Important:** Use values other than `3` only when instructed to do so by your PayPal representative. Character Length: 1 |
| `callback_version`Required | The version of the Instant Update API that your callback server uses. |
| `fallback_tax_amount`Optional | Tax amount to use as a fallback, if the callback response times out |
| `fallback_shipping_option_name_x`Required | Name and label of shipping option `x` to use as a fallback, if the callback response times out. For example, "Express 2 days". You can include a maximum of 10 shipping options as fallbacks. Substitute `x` with ordinal numbers, starting with `0`. Include one instance of this variable, with its index (`x`) set to `0`. If you include just one instance, include `fallback_shipping_option_is_default_x` parameter with its index, `x`, set to `0` and its value set to `1`. A valid value for `x` is from `0` to `9`. Character Length: 50 |
| `fallback_shipping_option_amount_x`Required | Shipping amount for option `x` to use as a fallback, if the response times out. Valid value for `x` is from `0` to `9`. |
| `fallback_shipping_option_is_default_x`Required | Indicates that shipping option `x` is the default and should be selected in the dropdown menu as a fallback, if the response times out. Only one shipping option can be the default for buyers. Check that you set one instance only of `fallback_shipping_option_is_default_x` to `1`. Valid value is: `1`. Shipping option `x` is the default shipping option.`0`. Shipping option `x` is not the default shipping option. Valid value for `x` is from `0` to `9`. Character Length: 1 |
| `fallback_insurance_option_offered`Optional | Indicates that insurance is offered and consumers can opt in to the insurance during checkout. PayPal ignores this variable if you omit `fallback_insurance_amount` or its value is less than or equal to `0`. Valid value is: `1`. Insurance is offered and consumers can opt in to during checkout.`0`. Insurance is applied along with the transaction, if applicable. The consumer will NOT have a choice to remove the insurance from the transaction amount. Character Length: 1 |
| `fallback_insurance_amount`Optional | Insurance amount to use as a fallback, if the callback response times out. Include the `fallback_insurance_option_offered` HTML variable if you specify an insurance amount. The fallback insurance amount applies to all shipping options that you specify. |
## Instant update variables for dimensions of individual items [#instant-update-variables-for-dimensions-of-individual-items]
Shipping charges are calculated sometimes by using the dimensions of individual items in the shopping cart. Include the following optional dimensional variables below in the Cart Upload command to provide the information to your callback server.
**HTML variables for instant update payment for dimension-based shipping charges**
| Name | Description |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `height_x`Optional | Height of item `x` in the shopping cart. A valid value is a positive integer. |
| `height_unit`Optional | Unit of measure for the values specified by `the height_x` values. A valid value is any value that you choose. PayPal passes the value to your callback server in callback requests. |
| `width_x`Optional | Width of item `x` in the shopping cart. A valid value is a positive integer. |
| `width_unit`Optional | Unit of measure for the value specified by `width_x`. A valid value is any value that you choose. PayPal passes the value to your callback server in callback requests. |
| `length_x`Optional | Length of item `x` in the shopping cart. Valid value is a positive integer. |
| `length_unit `Optional | Unit of measure for the value specified by `length_x`. Valid value is any value that you choose. PayPal passes the value to your callback server in callback requests. |
## Deprecated variables [#deprecated-variables]
The following variables have been deprecated. Deprecated variables are ignored when you pass them to PayPal.
**Deprecated PayPal button HTML variables**
| Name | Description | Deprecation date |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| `cbt`Optional | Sets the text for the Return to Merchant button on the PayPal Payment Complete page. For Business accounts, the return button displays your business name in place of `Merchant`, by default. By default, the text reads`Return to donations coordinator` for Donate buttons. > **Note:** **Note:** The `cbt` variable takes effect only if the `return` variable is set. Character Length: 60 | Dec. 2016 |
| `cn`Optional | Related to the `no_note` variable. When `no_note` is `0`, a text box is displayed at checkout for buyers who would like to include any special instructions. Use the `cn` field to enter a custom note or label for this text box, such as, `Enter any special instructions:`.Character Length: 40 | Sept. 2016 |
| `cpp_cart_border_color`Optional | The HTML hex code for your principal identifying color. PayPal blends your color to white in a gradient fill that borders the cart review area of the PayPal checkout user interface. Valid value is 6 single-byte hexadecimal characters that represent an HTML hex code for a color. Valid only for Buy Now and Add to Cart buttons and the Cart Upload command.Not used with Subscribe or Donate buttons. Character Length: 6 | Sept. 2016 |
| `cpp_header_image`Optional | The image at the top left of the checkout page. The image's maximum size is 750 pixels wide by 90 pixels high. PayPal recommends that you provide an image that is stored only on a secure (https) server. For more information, see [Customize PayPal Checkout Pages](/archive/paypal-payments-standard/admin/checkout-settings) in the Merchant Setup and Administration Guide. Deprecated for Buy Now and Add to Cart buttons and the Cart Upload command. Character Length: No limit | Sept. 2016 |
| `cpp_headerback_color`Optional | The background color for the header of the checkout page. Valid value is case-insensitive six-character, HTML hexadecimal color code in ASCII. Deprecated for Buy Now and Add to Cart buttons and the Cart Upload command. Character Length: 6 | Sept. 2016 |
| `cpp_headerborder_color`Optional | The border color around the header of the checkout page. The border is a 2-pixel perimeter around the header space, which has a maximum size of 750 pixels wide by 90 pixels high. Valid value is case-insensitive six-character, HTML hexadecimal color code in ASCII. Deprecated for Buy Now and Add to Cart buttons and the Cart Upload command. Character Length: 6 | Sept. 2016 |
| `cpp_logo_image`Optional | A URL to your logo image. Use a valid graphics format, such as `.gif`, `.jpg`, or `.png`. Limit the image to 190 pixels wide by 60 pixels high. PayPal crops images that are larger. PayPal places your logo image at the top of the cart review area. > **Note:** **Note:** PayPal recommends that you store the image on a secure (https) server. Otherwise, web browsers display a message that checkout pages contain non-secure items. Valid value is 127 single-byte alphanumeric characters. Valid only for Buy Now and Add to Cart buttons and the Cart Upload command.Not used with Subscribe or Donate buttons. Character Length: 127 | Sept. 2016 |
| `cpp_payflow_color`Optional | The background color for the checkout page below the header. Valid value is case-insensitive six-character, HTML hexadecimal color code in ASCII. > **Note:** **Note:** Background colors that conflict with PayPal's error messages are not allowed; in these cases, the default color is white. Deprecated for Buy Now and Add to Cart buttons and the Cart Upload command. Character Length: 6 | Sept. 2016 |
| `max_text`Optional | A description of the automatic billing plan. The Create a PayPal payment button page uses the same value that you enter in the Description field. Your button passes the description to PayPal to augment the item name in authorization notices and transaction details. If you write the HTML code for your button manually, the value of `max_text` and the text above the button can differ. | Sept. 2016 |
| `modify`Optional | Modification behavior. Valid value is: `0`. Default. Enables subscribers only to sign up for new subscriptions.`1`. Enables subscribers to sign up for new subscriptions and modify their current subscriptions.`2`. Enables subscribers to modify only their current subscriptions. **Deprecation behavior**: The `modify` values `1` and `2` are deprecated. If your customer clicks an existing modify subscription button that uses a `modify` value of `1` or `2`, PayPal returns the following message: `Things don't appear to be working at the moment.` `Please try again later`. Update your code to use `modify=0`, the only valid value, which allows your customers to sign up for new subscriptions only. Character Length: 1 | March 15, 2019 for `modify=1` and `modify=2` |
| `no_note`Optional | Do not prompt buyers to include a note with their payments. Valid value is: 0. Provide a text box and prompt for the note.1. Hide the text box and the prompt. Default is `0`. To add a text label for the text box, such as, `Enter any special instructions:`, use the `cn` variable. Character Length: 1 | Sept. 2016 |
| `page_style`Optional | The custom payment page style for checkout pages. Valid value is: `paypal`. use the PayPal page style`primary`. use the page style that you marked as primary in your account profile`page_style_name`. use the custom payment page style from your account profile that has the specified name Default is `primary` if you added a custom payment page style to your account profile. Otherwise, Default is `paypal`. Character Length: 30 | Sept. 2016 |
| `_oe-gift-certificate`Optional | The button that the person clicked was a Buy Gift Certificate button. | Feb. 1, 2017 |
| `usr_manage`Optional | Set to `1` to have PayPal generate usernames and initial passwords for subscribers. For more information, see [Generate Subscriber User Names and Passwords](/archive/paypal-payments-standard/integration-guide/user-names-passwords). Character Length: 1 | March 15, 2019 |