...
The UltraCart REST API aims to be a lightweight protocol for tying a checkout page(s) to the UltraCart back end.
Here are the demos
...
There are simple examples of all the major REST calls found here:
https://secure.ultracart.com/merchant/integrationcenter/checkoutapi_v3/demo1.html
Please notice that the script is running on secure.ultracart.com, so it doesn't suffer any cross-domain restrictions. As such, the urls are all relative (/rest/cart).
If you attempt to run a demo on your own machine, you'll need to install a proxy script, found here: https://github.com/UltraCart/responsive_checkout/blob/master/rest_proxy.php
After installing it, you need to adjust your url. Notice the difference below between line 3 and 4.
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
function createCart() {
jQuery.ajax({
// url: '/rest/cart', // same domain
url: '/rest_proxy.php?_url=/rest/cart', // cross-domain
headers: {'X-UC-Merchant-Id': 'DEMO',
"cache-control": "no-cache"}, // could also pass merchant id as query parameter named '_mid' or cookie named 'UltraCartMerchantID'
dataType: 'json'
}).done(function (cart) {
jQuery('#createCartResults').html('<pre>' + JSON.stringify(cart, null, ' ') + '</pre>');
});
}
jQuery(document).ready(function () {
jQuery('#createCartButton').on('click', createCart);
});
|
Merchant ID Required
...
Every call needs a merchant id (our merchant id is DEMO). We need to know who you are. There are three ways to provide the merchant id to the server:
- Query Parameter:
_mid=DEMO - HTTP Header:
'X-UC-Merchant-Id': 'DEMO' - Cookie named
UltraCartMerchantID
Most of the examples below use the http header since it's easy to use with jQuery. If you wished to do it for all your ajax calls, you could execute this javascript:
jQuery.ajaxSetup({ cache: false, headers: {'X-UC-Merchant-Id': 'DEMO', "cache-control": "no-cache"});
However, that makes each call less atomic (and jQuery doesn't recommend it). Still, it's an option and may work well with your site.
If you receive an error "Missing Merchant ID", you've forgotten to do one of the above.
Now, in case you're wondering why the three methods use different names...
- We made the query parameter as short as possible to keep the urls as short as possible. We used an underscore to denote "meta data" to the call.
- We follow common practices for naming custom http headers. While the X- prefix is officially out of vogue, we still think it looks cool.
- The cookie 'UltraCartMerchantID' is used in hundred of existing UltraCart checkout pages. So it made sense to stick with that cookie name.
Where are the errors?
| Warning |
|---|
When something doesn't work or you get an error, open your browser console and view the headers. Look for the error.
then fix it. Can't? Then get on github.com. Ask for help here. |
Note Regarding Support for API
...
| title | API troubleshooting |
|---|
...
Merchant ID Required
| Info |
|---|
Every call needs a merchant id (our merchant id is
Most of the examples below use the http header since it's easy to use with jQuery. If you wished to do it for all your ajax calls, you could execute this javascript:
However, that makes each call less atomic (and jQuery doesn't recommend it). Still, it's an option and may work well with your site. If you receive an error "Missing Merchant ID", you've forgotten to do one of the above. Now, in case you're wondering why the three methods use different names...
|
Where are the errors?
| Warning |
|---|
When something doesn't work or you get an error, open your browser console and view the headers. Look for the error.
then fix it. Can't? Then get on github.com. Ask for help here. |
Note Regarding Support for API
| Info | ||
|---|---|---|
| ||
UltraCart's free support does not cover API development questions or troubleshooting of custom checkout pages. Additional API support and troubleshooting services can be purchased at $100/hr (1 hour minimum) via UltraCart Professional Services. (Scheduling of paid for support will be determined by Professional Services personnel.) |
...
| Note | |||
|---|---|---|---|
/rest/cart/checkout is NOT THE END! It's the beginning of the end. If the response from checkout has no errors, you must redirect the browser to the url found in checkoutResonse.redirectToUrl. That finishes the order. Any errors during that phase (card declined) will send the browser back to checkoutRequest.redirectOnErrorUrl, which is usually set to your checkout page. It's a circle, one that handles shipping companies and payment gateway timeouts without timing out the browser. It also handles any upsell gauntlets. So make sure you follow the redirect! Code Block | finishes the order. Any errors during that phase (card declined) will send the browser back to checkoutRequest.redirectOnErrorUrl, which is usually set to your checkout page. It's a circle, one that handles shipping companies and payment gateway timeouts without timing out the browser. It also handles any upsell gauntlets. So make sure you follow the redirect!
|
Do this or you'll never complete an order...
...