Checkout v3 Demonstration
There are two main branches for the demonstrations below.
/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.
- /rest/cart
- /rest/site
/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.
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:
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:
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: |
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:
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:
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!
Change the fields and select which validation options to apply. Then validate!
|
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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:
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.
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
After logging in, note the customerProfile object in the cart, as well as cart.loggedIn property
Step 1: Register
Email:
Password:
Password:
Step 2: Logout (Register logs you in)
Step 3: Login Again (Try using incorrect credentials first)
Email:
Password:
Password:
Step 4: Forgot Password
Email:
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:
Admittedly, the terms for the DEMO account appear rather brief with just 'test'...
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:
City State lookup
Pass in a zip code and the city and state are looked up for your. Great for proactive address validation.
Result:
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:
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.
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:
Get State Province Codes
Comments: Much like stateProvinces (above), but returns back codes instead of long names
Country:
Result:
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:
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:
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:
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:
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: itemsPerPage and currentPage are optional and have defaults.
Search Term:
Result:
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.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.
| 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. | |
Single Item
Queries for a single item id and returns a single item. There are two versions of this call.
Item Id: - method=='get': This version returns an item with standard pricing.
- 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.
Result:
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
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:
Password:
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:
Home → Item Management → Items → [edit item] → [click Other tab]
{'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.