Upsells via API

Here are the steps to offering Upsell via the UltraCart API.

Use the built-in upsell gauntlet.  Don't use the API.  If you're determined to use the API, please read on...

Reasons to use the built-in Upsell

1. It's easy to use and allows for complex upsell paths. 
2. It removes tremendous complexity from the checkout
3. It has a great dashboard and metric tracking.

Objections to using the built-in Upsell

Objection: "We want to keep control of the checkout on our site."  

Response: Why? You can hand off to UltraCart and then immediately redirect on the receipt page if needed.  It's done all the time.

Objection: "We'll have to style up the upsell and receipt pages to match our site"

Response: Yes, but the time spent copying and pasting css code is nothing compared to the time required to implement an api based upsell.

Objection: "I only know PHP.  I don't know Velocity."

Response: You probably won't even use the template language.  Very few implementations have need of Velocity.  But if you do, it's easy to learn and UltraCart Support is there to help you out.

Steps for a manual Upsell

Okay, you have your reasons, so here's the gory details for implementing an Upsell with the UltraCart API.

This example is given using the PHP syntax, but applies to all.

1. Set the cart.upsell_after property with an appropriate object.  $cart→setUpsellAfter().
   1. You must set one of two properties: finalize_after_dts or finalize_after_minutes.  One is an absolute time and the other is a relative.  These times instruct UltraCart when to finalize an order in case the customer closes the browser window.  Sometimes the customer becomes annoyed with annoying upsells, excessive upsells, or upsells with long videos.  They close the browser.  If that happens, when the finalize time is reached, UltraCart will sweep the order into a completed state and charge their card. Setting this property is critical to doing api based upsells.
2. Do not call $checkoutApi.finalizeOrder as normally done. 
3. When the checkout is finished, instead do a full validation using $checkoutApi.validateCart, and if successful redirect your customer to your first upsell page.
4. One each upsell page, retrieve the cart id from wherever you have stored it (cookie, localstorage, server side session variable) and load their cart.  If they choose an upsell, adjust the cart items appropriately and call $checkoutApi→updateCart().
5. Continue showing upsells as desired.
6. When the last upsell is reached, call $checkoutApi.finalizeOrder().

PayPal Upsells

1. For PayPal upsells, you must do a $checkoutApi→handoff().  You cannot finalizeOrder a PayPal order since browser control must be given to PayPal.
2. The CheckoutHandoffRequest must contain several values:
   1. paypal_return_url must be set to the page after PayPal is successful.  This is the page that will receive control after a successful PayPal process.
   2. paypal_maximum_upsell_revenue must be set to the maximum amount you could possibly charge a customer who selected every possible upsell.  Failure to do so will cause your order to fail when upsells are used.  Note: UltraCart calculates this automatically using the built-in Upsells.