# Third-party shopping carts — the Cart Upload command (/archive/paypal-payments-standard/integration-guide/cart-upload)
> **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/).
Third-party shopping carts integrate PayPal Payments Standard on behalf of
PayPal merchants. The Cart Upload command passes the contents of a third-party
shopping cart to PayPal for checkout and payment processing.
> **Note:** **Note:** Merchants can also create their own, PayPal-hosted
> shopping cart. For more information, see
> [Create an Add to Cart button](/archive/paypal-payments-standard/integration-guide/add-to-cart-step-1)
> or the `BMCreateButton`
> [NVP](/api/nvp-soap/create-button-nvp/)
> |
> [SOAP](/api/nvp-soap/create-button-soap/)
> API call.
* [The checkout experience](#the-checkout-experience)
* [Implement the Cart Upload command](#implement-the-cart-upload-command)
* [Implement the Instant Update API with Cart Upload](#implement-the-instant-update-api-with-the-cart-upload-command)
> **Note:** **Important:** This page contains unencrypted button code for
> illustrative purposes only. To prevent malicious tampering of buttons on
> your live website, always encrypt your manually created buttons.
## The checkout experience [#the-checkout-experience]
The PayPal checkout experience with the Cart Upload command begins on a
merchant's shopping cart page, when someone clicks the check-out button.
Alternatively, it begins when someone selects PayPal on the merchant's payment
methods page.
The PayPal checkout experience with the Cart Upload command begins on a
merchant's shopping cart page, when someone clicks the check-out button.
Alternatively, it begins when someone selects PayPal on the merchant's payment
methods page.
* **PayPal Account Optional is turned on**. Buyers can pay without an existing PayPal account and can sign up for one after they complete the payment.
For more information, see [PayPal Account Optional](/archive/paypal-payments-standard/admin/checkout-settings#make-paypal-account-optional-at-checkout).
* **Shipping Calculations have been set up**. PayPal calculate the shipping charges automatically and adds them to the order.
For more information, see [Auto-calculate shipping charges](/archive/paypal-payments-standard/admin/checkout-settings#auto-calculate-shipping-charges).
* **Auto Return is turned off**. Buyers must click a **Return to Merchant** button to redirect their browsers to the merchant website after completing their payments with PayPal.
For more information, see [Auto Return](/archive/paypal-payments-standard/admin/checkout-settings#auto-return-the-buyer-to-your-website).
### What buyers see with third-party shopping carts [#what-buyers-see-with-third-party-shopping-carts]
Steve is shopping for photos on the Designer Fotos website. He selects several
photos for purchase by clicking the **Add to Cart** button
underneath each one.
Steve is shopping for photos on the Designer Fotos website. He selects several
photos for purchase by clicking the button
underneath each one.
**Add to Cart**
*View Cart* link at any time to review the items already in the cart
and to begin the PayPal Payments Standard checkout experience.
In this example integration, the third-party shopping cart is programmed by
the vendor to display the contents of the cart each time Steve clicks an
button. In addition, Steve can click the
**Proceed to Checkout**
After selecting the items he wants to buy and specifying their quantities,
Steve clicks the **Proceed to Checkout** button.
> **Note:** **Note:** If your website gathers information about your buyer,
> you can define HTML code to pre-populate the corresponding billing
> information fields. The buyers see a collapsed version of the billing
> information section. For example, if you pre-filled the billing address, the
> address information displays on the page without the entry fields. Each
> pre-filled section of information is followed by a *change* link to
> let the buyers modify the information, if necessary. For more information,
> see
> [Filling Out FORMs Automatically with HTML Variables](/archive/paypal-payments-standard/integration-guide/formbasics#auto-fill-forms-with-html-variables).
Steve does not have a PayPal account, so he clicks
*Don't have a PayPal account?* to enter his payment and billing
information on the payment login page. He clicks the
**Agree and Continue** button, and a review page displays the
details of his payment.
Steve does not have a PayPal account, so he clicks
Designer Fotos has set up Shipping Calculations in the account profile, so
PayPal calculates shipping costs automatically and adds them to the order.
**Pay Now** button to complete the payment, and
in response, the browser takes Steve to a payment confirmation page.
Steve clicks the
* Click *Print Receipt* to view and print a PayPal payment receipt.
* Click *Go to PayPal account overview* to view his account.
* Click *Link your bank account to your PayPal account now* to add a bank account to his PayPal account.
PayPal sends Steve an email notice of his payment to Designer Fotos.
PayPal sends Steve an email notice of his payment to Designer Fotos.
> **Note:** **Note:** Designer Fotos (the user
> [seller@designerfotos.com](mailto:seller@designerfotos.com)) can
> also see the payment in the PayPal account history.
## Implement the Cart Upload command [#implement-the-cart-upload-command]
Instead of relying on the PayPal Shopping Cart, many merchants use third-party
shopping carts that are already integrated with PayPal. The section describes
how you can use the Cart Upload command to integrate PayPal Payments Standard
with your third-party cart.
### Required third-party shopping cart variables [#required-third-party-shopping-cart-variables]
Your HTML code requires at least the following hidden HTML variables. For a
complete list of variables, see
[HTML Variables for PayPal Payments Standard](/archive/paypal-payments-standard/integration-guide/Appx-websitestandard-htmlvariables).
| Name | Description |
| ------------- | ------------------------------------------------------------------------------------------- |
| `amount_1` | Price of a single item or the total price of all items in the shopping cart |
| `business` | Email address of your PayPal account |
| `item_name_1` | Name of the item or a name for the entire shopping cart |
| `upload` | Indicates the use of third-party shopping cart |
To integrate your third-party shopping cart with PayPal and PayPal Payments
Standard, use one of these methods:
* Pass the details of the individual items.
* Pass the aggregate amount of the total cart payment rather than the individual item details.
### Passing individual item details to PayPal [#passing-individual-item-details-to-paypal]
If you code your third-party shopping cart to pass individual items to PayPal,
information about the items is included in buyers' and merchants' transaction
histories and notifications.
1. Set the `cmd` variable to *cart*.
2. Include the `upload` variable:
```html lineNumbers
```
3. Define item details for each item in the cart.
Specify the required variables and any optional variables listed in
[Technical HTML Variables](/archive/paypal-payments-standard/integration-guide/Appx-websitestandard-htmlvariables#technical-variables).
Specify the required variables and any optional variables listed in
`_x`.
`x` equals the
item number of the item in the cart starting from `1`. Increase
`x` by one for each item that you add to the cart.
Append `_x` to the variable name where `x` equals the
item number of the item in the cart starting from `1`. Increase
`x` by one for each item that you add to the cart.
`x` equal to `3`, and so on.
You must define the first item in the cart with `x` equal to
`1`, the second item with `x` equal to
For example, name the variables for the first item `item_name_1`,
`amount_1`, and `quantity_1`.
Name the variables for the second item `item_name_2`,
`amount_2`, and `quantity_2`.
> **Note:** **Important:** Sequentially increment the
> *`x`* value by 1 to have PayPal recognize each item.
> Skipping one or more numbers in the sequence causes PayPal to ignore items.
> For example, if you skip item 1 to item 3 without defining item 2, PayPal
> ignores the third item.
The following example shows the minimum required HTML for your post to PayPal.
> **Note:** **Important:** The following example button code is unencrypted
> for illustrative purposes only. In production, you must always use encrypted
> or hosted buttons in your web pages to prevent malicious users from
> tampering with the code.
#### HTML for passing individual item detail to PayPal [#html-for-passing-individual-item-detail-to-paypal]
```html lineNumbers
```
#### Setting currency in the cart [#setting-currency-in-the-cart]
PayPal uses the currency value of the `currency_code` variable that
accompanies the payment to interpret all variables that contain monetary
amounts, such as `amount_x`, `shipping_x`,
`shipping2_x`, `handling_x`, `tax_x`, and
`tax_cart`. Because `currency_code` is not
item-specific, do not append `x` to the
`currency_code` variable name. If you do not post a
`currency_code` variable value, all monetary values default to U.S.
dollars.
#### Setting tax on individual items [#setting-tax-on-individual-items]
Use the `tax_x` variable to specify the tax for a particular item
in the cart. For example, the following line specifies that the tax on item 2
in the cart is 15 cents:
```html lineNumbers
```
#### Setting profile-based shipping charges by weight on individual items [#setting-profile-based-shipping-charges-by-weight-on-individual-items]
Use the `weight_x` and `weight_unit` variables to
specify item weights if the merchant uses weight-based shipping rates. For
example, the following lines specify the weight of item 3 in the cart as 1.5
kg:
```html lineNumbers
```
Use the `quantity_x` variable if the merchant uses quantity-based
shipping rates. For example, the following line specifies that the quantity
for item 3 in the cart is 6:
```html lineNumbers
```
For information on how merchants set up weight-based shipping rates, see the
[Auto calculate shipping charges (U.S. Merchants Only)](/archive/paypal-payments-standard/admin/checkout-settings#auto-calculate-shipping-charges).
### Setting the tax for the entire cart [#setting-the-tax-for-the-entire-cart]
Use the `tax_cart` variable to specify a tax amount that applies to
the entire transaction rather than to individual items. The
`tax_cart` variable overrides any per-item tax amount specified
with `tax_x`.
### Setting the weight for the entire cart [#setting-the-weight-for-the-entire-cart]
Use the `weight_cart` and `weight_unit` variables to
specify the total weight of the cart, if the merchant uses weight-based
shipping rates. The `weight_cart` variable overrides any per-item
weights specified with `weight_x`.
### Setting discounts for the cart [#setting-discounts-for-the-cart]
Use the discount variables to specify discount amount or percentages.
* Use `discount_amount_cart` to charge a single discount amount for the entire cart.
* Use `discount_amount_x` to set a discount amount associated with item `x`.
* Use `discount_rate_cart` to charge a single discount percentage for the entire cart.
* Use `discount_rate_x` to set a discount percentage associated with item `x`.
The discount amount displays on all pages, email messages, and reports that
show payment information.
#### Default tax and discount processing [#default-tax-and-discount-processing]
Item-specific discounts apply before tax calculation for items in the
third-party cart. Discounts and tax apply to each item based on the discounts
and tax rate specified. However, your buyer sees only a total discount amount
for the cart and one entry for any applicable sales tax.
#### Setting consolidated discount amounts [#setting-consolidated-discount-amounts]
Consolidated discounts apply to the entire cart. PayPal calculates the tax on
the total of all items after applying the consolidated discount value. Your
buyer sees a total discount amount for the cart and one entry for any
applicable sales tax.
Consolidated discounts apply to the entire cart. PayPal calculates the tax on
the total of all items after applying the consolidated discount value. Your
buyer sees a total discount amount for the cart and one entry for any
applicable sales tax.
`tax_cart`. If you do not specify a tax value and your
profile specifies a tax rate, PayPal applies your profile tax rate after
applying the consolidated discount value.
When you use consolidated discount amounts, you should specify a consolidated
tax value in `tax_cart`. If you do not specify a tax value and your
profile specifies a tax rate, PayPal applies your profile tax rate after
applying the consolidated discount value.
`tax_rate_x`.
### Passing the aggregate shopping cart amount to PayPal [#passing-the-aggregate-shopping-cart-amount-to-paypal]
You can aggregate your entire shopping cart and pass the total amount to
PayPal. You must post a single `item_name_1` for the entire cart
and the total price of the cart contents in `amount_1` as though it
were a purchase of a single item.
> **Note:** **Note:** One drawback to passing aggregate cart information is
> that buyers do not see the individual items in their order on the PayPal
> payment pages.
The following HTML code shown is identical to the
[Passing individual item details to PayPal](#passing-individual-item-details-to-paypal)
example except here the example aggregates the individual item amounts and
item names into a single amount and a single item.
> **Note:** **Important:** The following example button code is unencrypted
> for illustrative purposes only. In reality, you must always use encrypted or
> hosted buttons in your web pages to prevent malicious users from tampering
> with the code.
#### HTML for aggregate cart detail to PayPal [#html-for-aggregate-cart-detail-to-paypal]
```html lineNumbers
```
## Implement the Instant Update API with the Cart Upload command [#implement-the-instant-update-api-with-the-cart-upload-command]
The Instant Update API is a callback API that lets you update PayPal in real
time with shipping, insurance, and tax amounts when buyers change their
shipping address on the PayPal Review Your Payment page.
* [About the Instant Update API and the Cart Upload Command](#about-the-instant-update-api-and-the-cart-upload-command)
* [Best practices for implementing Instant Update](#best-practices-for-implementing-instant-update)
* [Other considerations for implementing Instant Update](#other-considerations-for-implementing-instant-update)
* [Setting up the callback for Instant Update](#setting-up-callback-for-instant-update)
* [Responding to the callback for Instant Update](#responding-to-the-callback-for-instant-update)
### About the Instant Update API and the Cart Upload command [#about-the-instant-update-api-and-the-cart-upload-command]
The Instant Update API is a server call to your callback server that instantly
updates PayPal pages and enhances the Express Checkout experience on the
Review your information page.
The Instant Update API is a server call to your callback server that instantly
updates PayPal pages and enhances the Express Checkout experience on the
Review your information page.
1. When a buyer logs in to PayPal, the PayPal server calls your callback server with the buyer's default shipping address, which is stored in the PayPal system.
2. Your callback server responds with the shipping options available for that address, along with any insurance options and tax adjustments on the order.
3. PayPal displays this information on the Review your information page so buyers can choose from the options.
#### How Instant Update works with the Cart Upload command [#how-instant-update-works-with-the-cart-upload-command]
The following figure shows how the Instant Update callback works in the Cart
Upload checkout experience.
The following figure shows how the Instant Update callback works in the Cart
Upload checkout experience.
1. The checkout experience begins when a buyer clicks the checkout button on the Shopping Cart page of your third-party cart.
In the HTML code of the checkout button, provide the URL where PayPal can call your callback server, as well as fallback tax, shipping and insurance amounts. If you or your carrier base shipping rates on shipment size, include the shipping dimension HTML variables on individual items in the cart.
2. The buyer is redirected to PayPal to enter billing information or to log in to PayPal.
3. Before displaying the PayPal Review page, PayPal sends the buyer' shipping address to your callback server.
Every time the buyer changes the shipping address, PayPal calls your callback server.
4. Your callback server calculates tax, shipping, and insurance, based on the address in the callback request.
Calculate the amounts in your own code, or request the shipping and insurance amounts from your preferred carrier. If the address in the request is outside of the areas where you ship, respond with `NO_SHIPPING_OPTION_DETAILS` set to `1`.
5. PayPal updates the Review Your Payment page to show the options and rate that you sent back in the callback response from your callback server.
6. The buyer makes final selections and clicks the **Pay** button.
7. PayPal displays a confirmation page, from which the buyer can click a link to print a receipt.
#### Implementing Instant Update with the Cart Upload command [#implementing-instant-update-with-the-cart-upload-command]
You need a callback server to respond to Instant Update requests from PayPal.
Also, you need to add Instant Update HTML variables to your Cart Upload
command to set up the checkout for Instant Update.
1. Set up a secure server as your Instant Update callback server to accept Instant Update requests from PayPal.
2. Develop you callback server to process Instant Update requests and respond with tax, shipping, and insurance amounts.
3. Modify the HTML code of your Cart Upload commands by adding Instant Update HTML variables:\* The URL of your callback server and the timeout duration \* Fallback tax, shipping options, and an insurance amount. You must specify at least 1 shipping option \* Dimensions for all individual items, if you base shipping rates on shipping dimension
4. Eliminate your shipping options page.
5. Test your implementation of the callback and your fallback options.
#### The Review Your Payment page after implementing Instant Update [#the-review-your-payment-page-after-implementing-instant-update]
After you integrate the Instant Update API, you can display the shipping
options, related insurance options, and the tax amount. You control what to
display, which is instantly updated on the page.
After you integrate the Instant Update API, you can display the shipping
options, related insurance options, and the tax amount. You control what to
display, which is instantly updated on the page.
The shipping options, related insurance options, and the tax amount appear on
the page, as follows:
### Best practices for implementing Instant Update [#best-practices-for-implementing-instant-update]
PayPal recommends its list of best practices as a checklist for completing
your implementation of the Instant Update API.
* **Meet the pre-requisites** — Provide individual item detail instead of aggregate order amounts to take advantage of the Instant Update API.
* **Streamline the checkout experience** — Eliminate the shipping options page in your standard checkout experience.
* **Use the default callback timeout** — Use the recommended 3-second callback response timeout.
* **Follow PayPal-defined semantics and syntax** — Adhere to well-formed variable names and syntax rules in the callback response to PayPal. If errors occur in the response, PayPal uses the fallback options.
* **Ensure a consistent and good buyer experience —** When fallback shipping options are used, you should honor the rates to ensure a consistent and good buyer experience.
* **Localize shipping options** — Return localized shipping options, based on the buyer's country and locale, which PayPal sends in the callback request.
### Other considerations for implementing Instant Update [#other-considerations-for-implementing-instant-update]
When you implement the callback, you must consider callback response errors,
.timeouts, and shipping options.
#### Callback response errors [#callback-response-errors]
If there are any callback response errors, PayPal responds by displaying the
fallback options on the PayPal Review Your Payment page. To obtain the richer
set of options available through the callback, exercise care in the syntax and
values you specify and test the callback integration.
#### Minimum and maximum shipping options [#minimum-and-maximum-shipping-options]
You can specify up to 10 shipping options for the fallback options in the HTML
code for the Cart Upload command and for the detailed options based on
shipping address in the callback response. You must specify at least 1
shipping option.
#### Callback timeouts [#callback-timeouts]
If the callback does not return within the timeout period, PayPal displays the
fallback shipping options you specified in the HTML code for the Cart Upload
command in the drop-down menu on the PayPal Review Your Payment page.
If the callback does not return within the timeout period, PayPal displays the
fallback shipping options you specified in the HTML code for the Cart Upload
command in the drop-down menu on the PayPal Review Your Payment page.
The PayPal Review your information page in the following figure shows two
shipping options from which the buyer can choose if the callback times out. An
amount of $1.00 is offered for insurance:
#### Shipping to an alternate address [#shipping-to-an-alternate-address]
If you do not ship to the buyer's shipping address that PayPal sends in the
callback request, set `NO_SHIPPING_OPTION_DETAILS` to
`1` in the callback response.
If you do not ship to the buyer's shipping address that PayPal sends in the
callback request, set
```html lineNumbers
METHOD=CallbackResponse
NO_SHIPPING_OPTION_DETAILS =1
CALLBACKVERSION= <61.0 or greater >
```
When your callback server sends the previous response, the Review your
information page has these features:
* A message at the top of the page indicates that your business does not ship to this location.
* The shipping and handling section and the insurance section are dimmed.
* The buyer can change the shipping address.
* A new callback request is sent if the buyer changes the shipping address.
### Setting up callback for Instant Update [#setting-up-callback-for-instant-update]
To set up the callback, establish a connection with PayPal by providing the
location where PayPal calls your callback server, along with your shipping
options.
To set up the callback, establish a connection with PayPal by providing the
location where PayPal calls your callback server, along with your shipping
options.
* Establishing your Instant Update callback server
* Passing Instant Update callback information to PayPal
#### Establishing your instant update callback server [#establishing-your-instant-update-callback-server]
To start, you must build and operate a secure, reliable, and fast callback
server that computes shipping options, corresponding insurance options, and
tax, based on your business rules. To verify that callback requests originate
from PayPal.
To start, you must build and operate a secure, reliable, and fast callback
server that computes shipping options, corresponding insurance options, and
tax, based on your business rules. To verify that callback requests originate
from PayPal.
* The callback URL must start with HTTPS for production integration.
* The callback URL must start with HTTP or HTTPS for PayPal sandbox integration.
#### Passing Instant Update callback information to PayPal [#passing-instant-update-callback-information-to-paypal]
You pass Instant Update callback information in the HTML code of the Cart
Upload command. The Instant Update HTML variables let you specify the URL of
you callback server and the fallback values for shipping, insurance, and tax
amounts.
You pass Instant Update callback information in the HTML code of the Cart
Upload command. The Instant Update HTML variables let you specify the URL of
you callback server and the fallback values for shipping, insurance, and tax
amounts.
* `callback_url`. The URL of your callback server.
* `callback_timeout`. Always use the value `3`, unle instructed otherwise by PayPal.
* `fallback_shipping_option_x`. One or more sets of shipping option variables. You must include one instance of this variable with it `x` index set to `0`. If you include just one instance, you must include `fallback_shipping_option_is_default_x` with it `x` index set to `0` and its value set to `1`.
The following sample code illustrates a basic setup for the Instant Update
callback, which you include in the HTML Form variables for the Cart Upload
command.
```html lineNumbers
...
...
```
### Responding to the callback for Instant Update [#responding-to-the-callback-for-instant-update]
PayPal sends your callback server an Instant Update request whenever buyers
enter billing information or log in to PayPal to make payments. Your callback
server calculates shipping options and rates and sends them back to PayPal, in
Name-Value pair (NVP) format.
PayPal sends your callback server an Instant Update request whenever buyers
enter billing information or log in to PayPal to make payments. Your callback
server calculates shipping options and rates and sends them back to PayPal, in
Name-Value pair (NVP) format.
`callback_url` HTML variable. The fields in the
callback request include:
* Individual item details that you included in the Cart Upload command.
* Shipping address of the buyer.
Using the information in the callback request, calculate the rates and options
yourself or send the information in an API call to your carrier to perform the
calculations for you. Then send the shipping options, insurance amounts, and
taxes to PayPal in the callback response.
#### The callback request for Instant Update with the Cart Upload command [#the-callback-request-for-instant-update-with-the-cart-upload-command]
Callback requests specify the shipping addresses that buyers want to use when
they are about to complete a payment. Also, callback requests include
individual item details for the payments that buyers want to complete.
Callback requests specify the shipping addresses that buyers want to use when
they are about to complete a payment. Also, callback requests include
individual item details for the payments that buyers want to complete.
* 2 individual item details, which can be used to calculate taxes
* Weight information with one line item, which can be used to calculate shipping charge
* A shipping address
`METHOD=CallbackRequest &CALLBACKVERSION=57.0 &CURRENCYCODE=USD &LOCALECODE=en_US &L_NAME0=10% Decaf Kona Blend Coffee&L_NUMBER0=623083 &L_DESC0=Size: 8-oz &L_AMT0=9.95 &L_QTY0=2 &L_NAME1=Coffee Filter bags&L_NUMBER1=6230 &L_DESC1=Size: Two 24-piece boxes &L_AMT1=39.70 &L_QTY1=2 &L_ITEMWEIGHTUNIT1=lbs&L_ITEMWEIGHTVALUE1=0.5&SHIPTOSTREET=1 Main St&SHIPTOCITY=San Jose&SHIPTOSTATE=CA&SHIPTOCOUNTRY=US&SHIPTOZIP=95131&SHIPTOSTREET2`
#### Callback response for Instant Update [#callback-response-for-instant-update]
Callback responses let you specify one or more shipping options, with unique
shipping, insurance, and tax amounts. Your callback server calculates the
amounts based on shipping addresses that buyers provide during the PayPal
checkout experience.
Callback responses let you specify one or more shipping options, with unique
shipping, insurance, and tax amounts. Your callback server calculates the
amounts based on shipping addresses that buyers provide during the PayPal
checkout experience.
* Shipping insurance, with a different amount for each shipping option
* Three shipping methods, with different shipping amounts
* Taxes, with different amounts for each shipping method
* The UPS Expedited shipping method is the default method
`METHOD=CallbackResponse &OFFERINSURANCEOPTION=true&L_SHIPPINGOPTIONNAME0=UPS Air&L_SHIPPINGOPTIONLABEL0=UPS Next Day Air Freight &L_SHIPPINGOPTIONAMOUNT0=20.00 &L_TAXAMT0=2.20 &L_INSURANCEAMOUNT0=1.51 &L_SHIPPINGOPTIONISDEFAULT0=false &L_SHIPPINGOPTIONNAME1=UPS Expedited&L_SHIPPINGOPTIONLABEL1=UPS Express 2 Days &L_SHIPPINGOPTIONAMOUNT1=10.00 &L_TAXAMT1=2.00 &L_INSURANCEAMOUNT1=1.35 &L_SHIPPINGOPTIONISDEFAULT1=true&L_SHIPPINGOPTIONNAME2=UPS Ground&L_SHIPPINGOPTIONLABEL2=UPS Ground 2 to 7 Days &L_SHIPPINGOPTIONAMOUNT2=5.99 &L_TAXAMT2=1.99 &L_INSURANCEAMOUNT2=1.28 &L_SHIPPINGOPTIONISDEFAULT2=false`
button
underneath each one.
**Add to Cart**
*View Cart* link at any time to review the items already in the cart
and to begin the PayPal Payments Standard checkout experience.
In this example integration, the third-party shopping cart is programmed by
the vendor to display the contents of the cart each time Steve clicks an
button. In addition, Steve can click the
**Proceed to Checkout**
After selecting the items he wants to buy and specifying their quantities,
Steve clicks the **Proceed to Checkout** button.
> **Note:** **Note:** If your website gathers information about your buyer,
> you can define HTML code to pre-populate the corresponding billing
> information fields. The buyers see a collapsed version of the billing
> information section. For example, if you pre-filled the billing address, the
> address information displays on the page without the entry fields. Each
> pre-filled section of information is followed by a *change* link to
> let the buyers modify the information, if necessary. For more information,
> see
> [Filling Out FORMs Automatically with HTML Variables](/archive/paypal-payments-standard/integration-guide/formbasics#auto-fill-forms-with-html-variables).
Steve does not have a PayPal account, so he clicks
*Don't have a PayPal account?* to enter his payment and billing
information on the payment login page. He clicks the
**Agree and Continue** button, and a review page displays the
details of his payment.
Steve does not have a PayPal account, so he clicks
Designer Fotos has set up Shipping Calculations in the account profile, so
PayPal calculates shipping costs automatically and adds them to the order.
**Pay Now** button to complete the payment, and
in response, the browser takes Steve to a payment confirmation page.
Steve clicks the
* Click *Print Receipt* to view and print a PayPal payment receipt.
* Click *Go to PayPal account overview* to view his account.
* Click *Link your bank account to your PayPal account now* to add a bank account to his PayPal account.
PayPal sends Steve an email notice of his payment to Designer Fotos.
PayPal sends Steve an email notice of his payment to Designer Fotos.
> **Note:** **Note:** Designer Fotos (the user
> [seller@designerfotos.com](mailto:seller@designerfotos.com)) can
> also see the payment in the PayPal account history.
## Implement the Cart Upload command [#implement-the-cart-upload-command]
Instead of relying on the PayPal Shopping Cart, many merchants use third-party
shopping carts that are already integrated with PayPal. The section describes
how you can use the Cart Upload command to integrate PayPal Payments Standard
with your third-party cart.
### Required third-party shopping cart variables [#required-third-party-shopping-cart-variables]
Your HTML code requires at least the following hidden HTML variables. For a
complete list of variables, see
[HTML Variables for PayPal Payments Standard](/archive/paypal-payments-standard/integration-guide/Appx-websitestandard-htmlvariables).
| Name | Description |
| ------------- | ------------------------------------------------------------------------------------------- |
| `amount_1` | Price of a single item or the total price of all items in the shopping cart |
| `business` | Email address of your PayPal account |
| `item_name_1` | Name of the item or a name for the entire shopping cart |
| `upload` | Indicates the use of third-party shopping cart |
To integrate your third-party shopping cart with PayPal and PayPal Payments
Standard, use one of these methods:
* Pass the details of the individual items.
* Pass the aggregate amount of the total cart payment rather than the individual item details.
### Passing individual item details to PayPal [#passing-individual-item-details-to-paypal]
If you code your third-party shopping cart to pass individual items to PayPal,
information about the items is included in buyers' and merchants' transaction
histories and notifications.
1. Set the `cmd` variable to *cart*.
2. Include the `upload` variable:
```html lineNumbers
```
3. Define item details for each item in the cart.
Specify the required variables and any optional variables listed in
[Technical HTML Variables](/archive/paypal-payments-standard/integration-guide/Appx-websitestandard-htmlvariables#technical-variables).
Specify the required variables and any optional variables listed in
`_x`.
`x` equals the
item number of the item in the cart starting from `1`. Increase
`x` by one for each item that you add to the cart.
Append `_x` to the variable name where `x` equals the
item number of the item in the cart starting from `1`. Increase
`x` by one for each item that you add to the cart.
`x` equal to `3`, and so on.
You must define the first item in the cart with `x` equal to
`1`, the second item with `x` equal to
For example, name the variables for the first item `item_name_1`,
`amount_1`, and `quantity_1`.
Name the variables for the second item `item_name_2`,
`amount_2`, and `quantity_2`.
> **Note:** **Important:** Sequentially increment the
> *`x`* value by 1 to have PayPal recognize each item.
> Skipping one or more numbers in the sequence causes PayPal to ignore items.
> For example, if you skip item 1 to item 3 without defining item 2, PayPal
> ignores the third item.
The following example shows the minimum required HTML for your post to PayPal.
> **Note:** **Important:** The following example button code is unencrypted
> for illustrative purposes only. In production, you must always use encrypted
> or hosted buttons in your web pages to prevent malicious users from
> tampering with the code.
#### HTML for passing individual item detail to PayPal [#html-for-passing-individual-item-detail-to-paypal]
```html lineNumbers
```
#### Setting currency in the cart [#setting-currency-in-the-cart]
PayPal uses the currency value of the `currency_code` variable that
accompanies the payment to interpret all variables that contain monetary
amounts, such as `amount_x`, `shipping_x`,
`shipping2_x`, `handling_x`, `tax_x`, and
`tax_cart`. Because `currency_code` is not
item-specific, do not append `x` to the
`currency_code` variable name. If you do not post a
`currency_code` variable value, all monetary values default to U.S.
dollars.
#### Setting tax on individual items [#setting-tax-on-individual-items]
Use the `tax_x` variable to specify the tax for a particular item
in the cart. For example, the following line specifies that the tax on item 2
in the cart is 15 cents:
```html lineNumbers
```
#### Setting profile-based shipping charges by weight on individual items [#setting-profile-based-shipping-charges-by-weight-on-individual-items]
Use the `weight_x` and `weight_unit` variables to
specify item weights if the merchant uses weight-based shipping rates. For
example, the following lines specify the weight of item 3 in the cart as 1.5
kg:
```html lineNumbers
```
Use the `quantity_x` variable if the merchant uses quantity-based
shipping rates. For example, the following line specifies that the quantity
for item 3 in the cart is 6:
```html lineNumbers
```
For information on how merchants set up weight-based shipping rates, see the
[Auto calculate shipping charges (U.S. Merchants Only)](/archive/paypal-payments-standard/admin/checkout-settings#auto-calculate-shipping-charges).
### Setting the tax for the entire cart [#setting-the-tax-for-the-entire-cart]
Use the `tax_cart` variable to specify a tax amount that applies to
the entire transaction rather than to individual items. The
`tax_cart` variable overrides any per-item tax amount specified
with `tax_x`.
### Setting the weight for the entire cart [#setting-the-weight-for-the-entire-cart]
Use the `weight_cart` and `weight_unit` variables to
specify the total weight of the cart, if the merchant uses weight-based
shipping rates. The `weight_cart` variable overrides any per-item
weights specified with `weight_x`.
### Setting discounts for the cart [#setting-discounts-for-the-cart]
Use the discount variables to specify discount amount or percentages.
* Use `discount_amount_cart` to charge a single discount amount for the entire cart.
* Use `discount_amount_x` to set a discount amount associated with item `x`.
* Use `discount_rate_cart` to charge a single discount percentage for the entire cart.
* Use `discount_rate_x` to set a discount percentage associated with item `x`.
The discount amount displays on all pages, email messages, and reports that
show payment information.
#### Default tax and discount processing [#default-tax-and-discount-processing]
Item-specific discounts apply before tax calculation for items in the
third-party cart. Discounts and tax apply to each item based on the discounts
and tax rate specified. However, your buyer sees only a total discount amount
for the cart and one entry for any applicable sales tax.
#### Setting consolidated discount amounts [#setting-consolidated-discount-amounts]
Consolidated discounts apply to the entire cart. PayPal calculates the tax on
the total of all items after applying the consolidated discount value. Your
buyer sees a total discount amount for the cart and one entry for any
applicable sales tax.
Consolidated discounts apply to the entire cart. PayPal calculates the tax on
the total of all items after applying the consolidated discount value. Your
buyer sees a total discount amount for the cart and one entry for any
applicable sales tax.
`tax_cart`. If you do not specify a tax value and your
profile specifies a tax rate, PayPal applies your profile tax rate after
applying the consolidated discount value.
When you use consolidated discount amounts, you should specify a consolidated
tax value in `tax_cart`. If you do not specify a tax value and your
profile specifies a tax rate, PayPal applies your profile tax rate after
applying the consolidated discount value.
`tax_rate_x`.
### Passing the aggregate shopping cart amount to PayPal [#passing-the-aggregate-shopping-cart-amount-to-paypal]
You can aggregate your entire shopping cart and pass the total amount to
PayPal. You must post a single `item_name_1` for the entire cart
and the total price of the cart contents in `amount_1` as though it
were a purchase of a single item.
> **Note:** **Note:** One drawback to passing aggregate cart information is
> that buyers do not see the individual items in their order on the PayPal
> payment pages.
The following HTML code shown is identical to the
[Passing individual item details to PayPal](#passing-individual-item-details-to-paypal)
example except here the example aggregates the individual item amounts and
item names into a single amount and a single item.
> **Note:** **Important:** The following example button code is unencrypted
> for illustrative purposes only. In reality, you must always use encrypted or
> hosted buttons in your web pages to prevent malicious users from tampering
> with the code.
#### HTML for aggregate cart detail to PayPal [#html-for-aggregate-cart-detail-to-paypal]
```html lineNumbers
```
## Implement the Instant Update API with the Cart Upload command [#implement-the-instant-update-api-with-the-cart-upload-command]
The Instant Update API is a callback API that lets you update PayPal in real
time with shipping, insurance, and tax amounts when buyers change their
shipping address on the PayPal Review Your Payment page.
* [About the Instant Update API and the Cart Upload Command](#about-the-instant-update-api-and-the-cart-upload-command)
* [Best practices for implementing Instant Update](#best-practices-for-implementing-instant-update)
* [Other considerations for implementing Instant Update](#other-considerations-for-implementing-instant-update)
* [Setting up the callback for Instant Update](#setting-up-callback-for-instant-update)
* [Responding to the callback for Instant Update](#responding-to-the-callback-for-instant-update)
### About the Instant Update API and the Cart Upload command [#about-the-instant-update-api-and-the-cart-upload-command]
The Instant Update API is a server call to your callback server that instantly
updates PayPal pages and enhances the Express Checkout experience on the
Review your information page.
The Instant Update API is a server call to your callback server that instantly
updates PayPal pages and enhances the Express Checkout experience on the
Review your information page.
1. When a buyer logs in to PayPal, the PayPal server calls your callback server with the buyer's default shipping address, which is stored in the PayPal system.
2. Your callback server responds with the shipping options available for that address, along with any insurance options and tax adjustments on the order.
3. PayPal displays this information on the Review your information page so buyers can choose from the options.
#### How Instant Update works with the Cart Upload command [#how-instant-update-works-with-the-cart-upload-command]
The following figure shows how the Instant Update callback works in the Cart
Upload checkout experience.
The following figure shows how the Instant Update callback works in the Cart
Upload checkout experience.
1. The checkout experience begins when a buyer clicks the checkout button on the Shopping Cart page of your third-party cart.
In the HTML code of the checkout button, provide the URL where PayPal can call your callback server, as well as fallback tax, shipping and insurance amounts. If you or your carrier base shipping rates on shipment size, include the shipping dimension HTML variables on individual items in the cart.
2. The buyer is redirected to PayPal to enter billing information or to log in to PayPal.
3. Before displaying the PayPal Review page, PayPal sends the buyer' shipping address to your callback server.
Every time the buyer changes the shipping address, PayPal calls your callback server.
4. Your callback server calculates tax, shipping, and insurance, based on the address in the callback request.
Calculate the amounts in your own code, or request the shipping and insurance amounts from your preferred carrier. If the address in the request is outside of the areas where you ship, respond with `NO_SHIPPING_OPTION_DETAILS` set to `1`.
5. PayPal updates the Review Your Payment page to show the options and rate that you sent back in the callback response from your callback server.
6. The buyer makes final selections and clicks the **Pay** button.
7. PayPal displays a confirmation page, from which the buyer can click a link to print a receipt.
#### Implementing Instant Update with the Cart Upload command [#implementing-instant-update-with-the-cart-upload-command]
You need a callback server to respond to Instant Update requests from PayPal.
Also, you need to add Instant Update HTML variables to your Cart Upload
command to set up the checkout for Instant Update.
1. Set up a secure server as your Instant Update callback server to accept Instant Update requests from PayPal.
2. Develop you callback server to process Instant Update requests and respond with tax, shipping, and insurance amounts.
3. Modify the HTML code of your Cart Upload commands by adding Instant Update HTML variables:\* The URL of your callback server and the timeout duration \* Fallback tax, shipping options, and an insurance amount. You must specify at least 1 shipping option \* Dimensions for all individual items, if you base shipping rates on shipping dimension
4. Eliminate your shipping options page.
5. Test your implementation of the callback and your fallback options.
#### The Review Your Payment page after implementing Instant Update [#the-review-your-payment-page-after-implementing-instant-update]
After you integrate the Instant Update API, you can display the shipping
options, related insurance options, and the tax amount. You control what to
display, which is instantly updated on the page.
After you integrate the Instant Update API, you can display the shipping
options, related insurance options, and the tax amount. You control what to
display, which is instantly updated on the page.
The shipping options, related insurance options, and the tax amount appear on
the page, as follows:
### Best practices for implementing Instant Update [#best-practices-for-implementing-instant-update]
PayPal recommends its list of best practices as a checklist for completing
your implementation of the Instant Update API.
* **Meet the pre-requisites** — Provide individual item detail instead of aggregate order amounts to take advantage of the Instant Update API.
* **Streamline the checkout experience** — Eliminate the shipping options page in your standard checkout experience.
* **Use the default callback timeout** — Use the recommended 3-second callback response timeout.
* **Follow PayPal-defined semantics and syntax** — Adhere to well-formed variable names and syntax rules in the callback response to PayPal. If errors occur in the response, PayPal uses the fallback options.
* **Ensure a consistent and good buyer experience —** When fallback shipping options are used, you should honor the rates to ensure a consistent and good buyer experience.
* **Localize shipping options** — Return localized shipping options, based on the buyer's country and locale, which PayPal sends in the callback request.
### Other considerations for implementing Instant Update [#other-considerations-for-implementing-instant-update]
When you implement the callback, you must consider callback response errors,
.timeouts, and shipping options.
#### Callback response errors [#callback-response-errors]
If there are any callback response errors, PayPal responds by displaying the
fallback options on the PayPal Review Your Payment page. To obtain the richer
set of options available through the callback, exercise care in the syntax and
values you specify and test the callback integration.
#### Minimum and maximum shipping options [#minimum-and-maximum-shipping-options]
You can specify up to 10 shipping options for the fallback options in the HTML
code for the Cart Upload command and for the detailed options based on
shipping address in the callback response. You must specify at least 1
shipping option.
#### Callback timeouts [#callback-timeouts]
If the callback does not return within the timeout period, PayPal displays the
fallback shipping options you specified in the HTML code for the Cart Upload
command in the drop-down menu on the PayPal Review Your Payment page.
If the callback does not return within the timeout period, PayPal displays the
fallback shipping options you specified in the HTML code for the Cart Upload
command in the drop-down menu on the PayPal Review Your Payment page.
The PayPal Review your information page in the following figure shows two
shipping options from which the buyer can choose if the callback times out. An
amount of $1.00 is offered for insurance: