Checkout v3 Demonstration

There are two main branches for the demonstrations below.
  1. /rest/cart
  2. /rest/site
/rest/cart contains cart-centric calls. The cart object plays a part in almost everyone call.
/rest/site contains more site-wide calls that return back merchant configured settings. Some of those calls also take an optional cart object, where the presence of a logged in user augments the call.
For example: /rest/site/items has two methods, one of which takes a cart. Making the call without a cart will return back standard pricing. Making the call with the cart will return back adjusted pricing for the current customer. If your company uses pricing tiers, this will be of value.
top

Create/Initialize a shopping cart

Comments: Somewhat unnecessary. This would suffice for an initial cart: {'merchantId':'DEMO'}, however, you can call get cart to receive an empty cart if desired. The real usefulness is maintaining the state of the cart through cookies. When a customer returns to a checkout page, this call will reload their cart, provided you saved the cart id somewhere and pass it back in.
Result:
top

Update a shopping cart

Comments: merchantId and cartId are required. Notice that the cartId property is required even if empty. It must be explicitly stated.
Result:
top

Insert a bare cart, get the cart, then update it using path parameters

Path parameters (passing cart id as part of the path) is common among REST frameworks such as backbone.js.
Result:
top

Add items to a cart

The minimum requirement for adding items are item id and quantity.
Merchant ID
Item #1 Quantity:
Item #2 Quantity:
Item #3 Quantity:
Item #4 Quantity:
Result:
top

Estimate shipping for a cart

If there is no address information, shipping is estimated from the center of the US. We'll add some info though to get some better prices. This is a long running query (several seconds). It takes time to ping FedEx and UPS for rates.
Result:
top

Checkout (End Step)

Note: As of June 2015, this can no longer be done in one or two calls. The credit card number must be supplied to token.ultracart.com through UltraCart Hosted Fields and then the checkout call made.
Result:
top

Validation

Here's an interactive validation procedure. The fields below are filling in (most incorrectly). Not all the validation options are listed below. Some of the validations didn't make for good demonstrations -- too complex. UltraCart has *a lot* of validations available.
Change the fields and select which validation options to apply. Then validate!
Billing Address Fields
First Name:
Last Name:
Company:
Address 1:
Address 2:
City:
State:
Zip:
Country:
Day Phone:
Evening Phone:
Email:
Advertising Source:
Shipping Address Fields
First Name:
Last Name:
Company:
Address 1:
Address 2:
City:
State:
Zip:
Country:
Day Phone:
Evening Phone:
Shipping Method:
Payment Method:
  Validation Description
Billing Address Provided looks for empty fields
Billing State Abbreviation Valid You must supply a country for to validate state. Put 'United States' in the country to test this.
Billing Phone Numbers Provided
Email provided if required
Billing Validate City State Zip makes sure the zip is right for the given city/state
Shipping Method Provided look at the shipping estimates demo above for valid names. "FedEx: 2-Day" should usually work.
Advertising Source Provided
Shipping Address Provided
Shipping Validate City State Zip makes sure the zip is right for the given city/state
Shipping State Abbreviation Valid You must supply a country for to validate state. Put 'United States' in the country to test this.
Payment Method Provided try "Credit Card", or make up an invalid one.
All 'All' includes all validations, not just the ones shown here.
Result:
top

Setting finalizeAfter (and clearing it)

The finalizeAfter marks a cart for completion after a certain amount of time. This feature is used instead of a normal checkout when "upsell after" screens are in play. With upsells, there is always a chance the customer will leave without finishing an upsell gauntlet. To ensure the sale is captures, all information is collected, and setFinalizeAfter is called. Once called, additional upsell screens may be shown and changes to the cart continue (adding product, etc) without fear of losing the sale. clearFinalizeAfter is used to remove the deadline, allowing a cart to expire.

Normally, this is done with a fully comlete cart. For the sake of the demonstration, I'll be using an empty cart. Note however, the cart must exist on the server. You cannot finalize a new cart.
Result:
top

Customer Profiles: Register, Login, Logout, Forgot Password

To run this demonstration, you'll need to create your own customer profile. You may use any email address, real or otherwise. However, you can only see the email from the Forgot Password feature using a valid email address.
After logging in, note the customerProfile object in the cart, as well as cart.loggedIn property
Step 1: Register
Email:
Password:
Step 2: Logout (Register logs you in)
Step 3: Login Again (Try using incorrect credentials first)
Email:
Password:
Step 4: Forgot Password
Email:
Result:
top

Checkout Terms

The checkout terms are not part of the normal cart. Some merchants have *extremely* long checkout terms and we don't want to pass those back and forth 20 times during a cart checkout. However, the terms are based on the items orders, so we still need to pass in a valid cart with some items to get the terms back.
Admittedly, the terms for the DEMO account appear rather brief with just 'test'...
Result:
top

Related Items

Related items are configured by the merchant on the back end. For this call, you pass in the cart, and all the related items are returned. These are usually displayed at the bottom of a view cart page enticing customers to purchase additional products.
Result:
top

City State lookup

Pass in a zip code and the city and state are looked up for your. Great for proactive address validation.
Result:
top

Finalize Order (End Step - SERVER SIDE ONLY. NO BROWSERS. NO JAVASCRIPT)

NEVER, EVER, EVER MAKE THIS CALL USING JAVASCRIPT. THIS IS A SERVER SIDE CALL ONLY.
We're not kidding. This call requires credentials - UltraCart login credentials. If you put those credits on the client side,
you deserve the vicious evil that will be visited upon you when they are discovered. And they will be easily discovered. Stupid should hurt. Making this call from a browser *is* stupid.
NEVER, EVER, EVER MAKE THIS CALL USING JAVASCRIPT. THIS IS A SERVER SIDE CALL ONLY.

Okay, now that we're clear you're only still reading this because you're writing a php server side script...
The request requires three things: 1) cart, 2) credentials (merchantid, username, password), and 3) options.
Options are optional. They wouldn't be options if they weren't right? They discussed in the docs page. Search for FinalizeOrderOptions.
For credentials, please please please create a user that *only* has API Access, then restrict that user to an IP Address (also on Edit User page).
Again, using your main login or owner account to make API calls is beyond ill-advised. It also falls under the stupid category. Don't.

Also, you CANNOT supply a credit card number like this example does. You must use UltraCart Hosted Fields. See http://docs.ultracart.com/display/ucdoc/UltraCart+PCI+Compliance for details.
See https://github.com/UltraCart/rest_api/tree/master/cart_example for an example.

Result:
top

Get State Provinces

Comments: This is a convenience function to retrieve all configured states for a country. It just avoids having to hard code a bunch of states in an application. If you're just shipping to the US, this call doesn't make sense. However, if you ship internationally, this call can be very handy to populate a state/province field with the correct values dynamically whenever the country field changes from (example) United States to Canada.
Country: Result:
top

Get State Province Codes

Comments: Much like stateProvinces (above), but returns back codes instead of long names
Country: Result:
top

Unified Affiliate Cookie Script

If you use affiliates, this call returns back a script that you can attach to your web page and run. It will set the necessary cookies to track your affiliates across multiple domains.
Result:
top

Advertising Sources

Returns back a string array of all the advertising sources configured for a merchant (and theme code). This is almost always used to populate the "Where did you hear from us?" dropdown box on a checkout page.
Result:
top

Return Policy

Fetches a merchant's return policy. Some of you guys have massive return policies, especially anyone selling an digestible product. We don't want to carry that back and forth with every call, so we don't attach it to the cart object. It's separate. You'll probably fetch it once and store it somewhere. localStorage is a great idea...
Result:
top

Allowed Countries

Fetches an array of all the countries a merchant will ship to.
Result:
top

Customer IP Address

Pings back the customer's ip address. Helpful since you can't get this in javascript. Get the ip address and set it on the customer's cart.
Result:
top

Item Search

Searches for items based on the provided search string. This searches item ids, descriptions, and item attributes. The secureServerName variable is only needed for the view links (the link to view each item). You'll want to set this to your web site so any returned urls are ready to go.

itemsPerPage and currentPage are optional and have defaults.
Merchant ID:
Search Term:
Result:
top

Items

Accepts a parameter array of item ids OR a catalog group url, and returns back a list of item objects.
See: http://docs.ultracart.com/display/ucdoc/Groups+-+Catalog
In brief, a catalog group is a url with path (i.e. https://secure.ultracart.com/catalog/DEMO/products/facebook/) that maps to a list of items. It's a
way to group your items for easy retrieval. You can also then update your items without having to change a bunch of web code.
Which should you use? Catalog Groups. Okay, there's a learning curve there. But it's worth it.
If you submit both a list of items and a url, the url wins and those items are returned. The rest call does not combine the two.
Note: The server expects a parameter array of items, not a csv list. The javascript routine splits the string by commas and creates an array.
Merchant ID:
Search Term:
Catalog Group URL:
Hey. You can't just put any url in the field above. It must be a valid catalog group.
Result:
top

Single Item

Queries for a single item id and returns a single item. There are two versions of this call.
  1. method=='get': This version returns an item with standard pricing.
  2. method=='post': This version accepts a cart as the post payload, and if the cart has a logged in customer, it returns an item with that customer's (or pricing tier's) pricing.
Item Id:

Result:
top

Place order using stored credit card.

To run this demonstration, you'll need to create your own customer profile. You may use any email address, real or otherwise.
Notice that this example registers a customer using the MyAccount API instead of the Cart API. This must be done in order to create a credit card. While both APIs accomplish the same thing, the Cart API call doesn't actually create the customer until the order finishes (to reduce spam registrations). The MyAccount creates it immediately. After logging in, note the customerProfile object in the cart, as well as cart.loggedIn property
Email:
Password:
Result:
top

Checkout with Arbitrary Unit Cost

This is the same example as the checkout example, except I've added an arbitraryUnitCost to the Baseball item. Remember that for you to use arbitrayUnitCosts in your checkout, you must configure them in each desired item.
Home → Item Management → Items → [edit item] → [click Other tab]
Result: