UltraCart REST Site API
This is Version 1 of the UltraCart REST API. It is now legacy. It will remain forever, but no new development will be done.
Please see Version 2 for new development.
Version 2 Supplemental Documentaion
- 1 Introduction (Things you'll wish you read first)
- 2 Object Model
- 3 Site REST API
- 3.1 /rest/site/stateProvinces
- 3.2 /rest/site/stateProvinceCodes
- 3.3 /rest/site/storeFront/searchAutoSuggest
- 3.4 /rest/site/unifiedAffiliateCookieScript
- 3.5 /rest/site/advertisingSources
- 3.6 /rest/site/returnPolicy
- 3.7 /rest/site/allowedCountries
- 3.8 rest/site/customerIpAddress
- 3.9 /rest/site/items/search
- 3.10 /rest/site/items
- 3.11 /rest/site/items/{item id}
- 3.12 /rest/site/items/{item id}/relatedItems
- 4 Server Side Logging
Introduction (Things you'll wish you read first)
The UltraCart REST API aims to be a lightweight protocol for tying a checkout page(s) to the UltraCart back end.
// this code was removed due to incompatibility with the current UltraCart engine.
Every call needs a merchant id (our merchant id is DEMO). We need to know who you are. There are four ways to provide the merchant id to the server:
Use your StoreFront url instead of secure.ultracart.com within your proxy script.
Query Parameter:
_mid=DEMOHTTP Header:
'X-UC-Merchant-Id': 'DEMO'Cookie named
UltraCartMerchantId
The very best way is to use your StoreFront url. Every merchant has free StoreFronts with their account. Make sure you have one configured with a valid theme, and then change your proxy script to point to your StoreFront url. For example, change the destination from secure.ultracart.com to <MerchantID>.ultracartstore.com. Any requests directed to a StoreFront will automatically resolve the merchant id automatically.
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 make 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.
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.
Object Model
Any json objects referenced below may be found on the Checkout REST API screen. These two APIs have lots of overlap.
Site REST API
The site rest api deals with calls that are more merchant-centric rather than cart-centric. They usually return information that is the same regardless of the cart, such as a merchant's return policy or allowed countries.
When a site rest call does take a cart, it's to augment the call with customer specific information.
For example, if a merchant has pricing tiers configured, then the prices for items will be different if a customer is logged in or not. Those calls that take cart objects will consider the logged in user when returning back pricing, etc.
You'll see this behavior on some of the item calls.
When a call takes an optional cart object, the method type will usually change from a 'get' to a 'post', and the post payload will be the cart's json. Don't forget to set the right type if you're passing in the cart.
/rest/site/stateProvinces
Method | GET | Comments |
|---|---|---|
Description | returns back all states for the country provided | This is a convenience function to retrieve all configured states for a country. |
Cookies | none | |
Path Parameters | none | |
Query Parameters | country | 'United States', 'Canada', etc. |
Headers | none | |
Receives Json | none | |
Returns Json | String Array | Example:
Example for include codes:
|
function stateProvinces() {
var country = jQuery('#stateProvincesCountry').val() || 'United States';
jQuery.ajax({
url: '/rest/site/stateProvinces',
data: {country: country},
type: 'get',
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 (states) {
jQuery('#stateProvincesResult').html('<pre>' + JSON.stringify(states, null, ' ') + '</pre>');
});
}
jQuery(document).ready(function () {
jQuery('#stateProvincesButton').on('click', stateProvinces);
});
<div class='demo'><a class='demo-link' name="demo14"></a>
<h4 class='title'>Get State Provinces</h4>
<div class='details'>
Country: <input type="text" id="stateProvincesCountry" value="United States"/>
<input type="button" class='demo-button' value="Get States/Provinces" id="stateProvincesButton"/>
<script type="syntaxhighlighter" class="brush: javascript" id="demo-code-display14"></script>
Result:
<div class="results" id="stateProvincesResult"></div>
</div>
</div>/rest/site/stateProvinceCodes
Method | GET | Comments |
|---|---|---|
Description | returns back all state codes for the country provided | This is just like /rest/site/stateProvinces, but it returns back codes instead of long names. |
Cookies | none | |
Path Parameters | none | |
Query Parameters | country | 'United States', 'Canada', etc. |
Headers | none | |
Receives Json | none | |
Returns Json | String Array | Example:
|
function stateProvinceCodes() {
var country = jQuery('#stateProvinceCodesCountry').val() || 'United States';
jQuery.ajax({
url: '/rest/site/stateProvinceCodes',
data: {country: country},
type: 'get',
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 (statesCodes) {
jQuery('#stateProvinceCodesResult').html('<pre>' + JSON.stringify(statesCodes, null, ' ') + '</pre>');
});
}
jQuery(document).ready(function () {
jQuery('#stateProvinceCodesButton').on('click', stateProvinceCodes);
});
<div class='demo'><a class='demo-link' name="demo15"></a>
<h4 class='title'>Get State Province Codes</h4>
<div class='details'>
Country: <input type="text" id="stateProvinceCodesCountry" value="United States"/>
<input type="button" class='demo-button' value="Get States/Provinces" id="stateProvinceCodesButton"/>
<script type="syntaxhighlighter" class="brush: javascript" id="demo-code-display15"></script>
Result:
<div class="results" id="stateProvinceCodesResult"></div>
</div>
</div>/rest/site/storeFront/searchAutoSuggest
Method | GET | Comments |
|---|---|---|
Description | returns back suggestions and result items based upon current search | This is just like /rest/site/stateProvinces, but it returns back codes instead of long names. |
Cookies | none | |
Path Parameters | none | |
Query Parameters | search thumbnailHeight thumbnailWidth | Users search string. Don't submit until 3 characters long. thumbnailHeight/thumbnailWidth take precedence over thumbnailSize. Valid values are:
|
Headers | none | |
Receives Json | none | |
Returns Json | A complex object containing suggestions and results. | Example: { |
/rest/site/unifiedAffiliateCookieScript
Method | GET | Comments |
|---|---|---|
Description | returns back a url that can be used to construct a script element. When run, that script will set cookies to track affiliates across domains. | There's lot of ways to run the script. jQuery makes it easy. |
Cookies | none | |
Path Parameters | none | |
Query Parameters | secureHostName - the domain you wish to track affiliates on _mid - your Merchant ID (could also use header or cookie - see example) | www.mystorenamehere.com |
Headers | none | |
Receives Json | none | |
Returns Json | This returns a text string, not Json! | Example:
|
function unifiedAffiliateScript() {
var merchantId = 'DEMO';
var secureHostName = "www.mystorenamehere.com";
jQuery.ajax({
url: '/rest/site/unifiedAffiliateCookieScript',
data:{secureHostName: secureHostName},
type: 'get',
headers: {'X-UC-Merchant-Id': merchantId, // this is one way to pass MID
"cache-control": "no-cache"}, // could also pass merchant id as query parameter named '_mid' or cookie named 'UltraCartMerchantId'
dataType: 'text' // NOTE: This returns back plain text!
}).done(function (script) {
jQuery('#unifiedAffiliateCookieScriptResult').html('<pre>' + script + '</pre>');
});
}
jQuery(document).ready(function () {
jQuery('#unifiedAffiliateCookieScriptButton').on('click', unifiedAffiliateScript);
});
<div class='demo'><a class='demo-link' name="demo16"></a>
<h4 class='title'>Unified Affiliate Cookie Script</h4>
<div class='details'>
<input type="button" class='demo-button' value="Get Script" id="unifiedAffiliateCookieScriptButton"/>
<script type="syntaxhighlighter" class="brush: javascript" id="demo-code-display16"></script>
Result:
<div class="results" id="unifiedAffiliateCookieScriptResult"></div>
</div>
</div>/rest/site/advertisingSources
Method | GET | Comments |
|---|---|---|
Description | returns back a string array of all advertising sources for a merchant and (optionally) a specific theme code. | |
Cookies | none | |
Path Parameters | none | |
Query Parameters | screenBrandingThemeCode | Theme code is optional. If not provided, the default is used (DFLT). To manage your theme codes, login to the back end (secure.ultracart.com) and navigate to Home → Configuration → Look and Feel Section → Screen Branding Themes |
Headers | none | |
Receives Json | none | |
Returns Json | A string array of advertising sources | Example:
|
function advertisingSources() {
var themeCode = "DFLT";
jQuery.ajax({
url: '/rest/site/advertisingSources',
data:{screenBrandingThemeCode: themeCode},
type: 'get',
headers: {'X-UC-Merchant-Id': 'SANTI', // this is one way to pass MID
"cache-control": "no-cache"}, // could also pass merchant id as query parameter named '_mid' or cookie named 'UltraCartMerchantId'
dataType: 'json'
}).done(function (sources) {
jQuery('#advertisingResult').html('<pre>' + JSON.stringify(sources, null, ' ') + '</pre>');
});
}
jQuery(document).ready(function () {
jQuery('#advertisingButton').on('click', advertisingSources);
});
<div class='demo'><a class='demo-link' name="demo17"></a>
<h4 class='title'>Advertising Sources</h4>
<div class='details'>
<input type="button" class='demo-button' value="Get Advertising Sources" id="advertisingButton"/>
<script type="syntaxhighlighter" class="brush: javascript" id="demo-code-display17"></script>
Result:
<div class="results" id="advertisingResult"></div>
</div>
</div>/rest/site/returnPolicy
Method | GET | Comments |
|---|---|---|
Description | returns back a plain text string of the merchant's return policy | returns back the policy for the default theme (DFLT) unless the theme is specified Fetches a merchant's return policy. Some of you guys have massive return policies, especially |
Cookies | none | |
Path Parameters | none | |
Query Parameters | screenBrandingThemeCode | Theme code is optional. If not provided, the default is used (DFLT). To manage your theme codes, login to the back end (secure.ultracart.com) and navigate to Home → Configuration → Look and Feel Section → Screen Branding Themes |
Headers | none | |
Receives Json | none | |
Returns Json | This returns a text string, not Json! | Example:
|
function returnPolicy() {
var themeCode = "DFLT";
jQuery.ajax({
url: '/rest/site/returnPolicy',
data:{screenBrandingThemeCode: themeCode},
type: 'get',
headers: {'X-UC-Merchant-Id': 'DEMO', // this is one way to pass MID
"cache-control": "no-cache"}, // could also pass merchant id as query parameter named '_mid' or cookie named 'UltraCartMerchantId'
dataType: 'text' // NOTICE the data type. This returns plain text.
}).done(function (returnPolicy) {
jQuery('#returnPolicyResult').html('<pre>' + returnPolicy + '</pre>');
});
}
jQuery(document).ready(function () {
jQuery('#returnPolicyButton').on('click', returnPolicy);
});
<div class='demo'><a class='demo-link' name="demo18"></a>
<h4 class='title'>Return Policy</h4>
<div class='details'>
<input type="button" class='demo-button' value="Get Return Policy" id="returnPolicyButton"/>
<script type="syntaxhighlighter" class="brush: javascript" id="demo-code-display18"></script>
Result:
<div class="results" id="returnPolicyResult"></div>
</div>
</div>/rest/site/allowedCountries
Method | GET | Comments |
|---|---|---|
Description | returns back a string array of all countries a merchant ships to | |
Cookies | none | |
Path Parameters | none | |
Query Parameters | none | |
Headers | none | |
Receives Json | none | |
Returns Json | A string array of countries | Example:
... and many more ... |
function allowedCountries() {
jQuery.ajax({
url: '/rest/site/allowedCountries',
type: 'get',
headers: {'X-UC-Merchant-Id': 'DEMO', // this is one way to pass MID
"cache-control": "no-cache"}, // could also pass merchant id as query parameter named '_mid' or cookie named 'UltraCartMerchantId'
dataType: 'json'
}).done(function (countries) {
jQuery('#allowedCountriesResult').html('<pre>' + JSON.stringify(countries, null, ' ') + '</pre>');
});
}
jQuery(document).ready(function () {
jQuery('#allowedCountriesButton').on('click', allowedCountries);
});
<div class='demo'><a class='demo-link' name="demo19"></a>
<h4 class='title'>Allowed Countries</h4>
<div class='details'>
<input type="button" class='demo-button' value="Get Allowed Countries" id="allowedCountriesButton"/>
<script type="syntaxhighlighter" class="brush: javascript" id="demo-code-display19"></script>
Result:
<div class="results" id="allowedCountriesResult"></div>
</div>
</div>rest/site/customerIpAddress
Method | GET | Comments |
|---|---|---|
Description | returns back the customer's ip address | |
Cookies | none | |
Path Parameters | none | |
Query Parameters | none | |
Headers | none | |
Receives Json | none | |
Returns Json | Plain Text! IP Address | Example:
|
function customerIpAddress() {
jQuery.ajax({
url: '/rest/site/customerIpAddress',
type: 'get',
headers: {'X-UC-Merchant-Id': 'DEMO', // this is one way to pass MID
"cache-control": "no-cache"}, // could also pass merchant id as query parameter named '_mid' or cookie named 'UltraCartMerchantId'
dataType: 'text' // Note! Plain text string
}).done(function (ipAddress) {
jQuery('#customerIpAddressResult').html('<pre>' + ipAddress + '</pre>');
});
}
jQuery(document).ready(function () {
jQuery('#customerIpAddressButton').on('click', customerIpAddress);
});
<div class='demo'><a class='demo-link' name="demo20"></a>
<h4 class='title'>Customer IP Address</h4>
<div class='details'>
<input type="button" class='demo-button' value="Get Allowed Countries" id="customerIpAddressButton"/>
<script type="syntaxhighlighter" class="brush: javascript" id="demo-code-display20"></script>
Result:
<div class="results" id="customerIpAddressResult"></div>
</div>
</div>/rest/site/items/search
Method | GET | Comments |
|---|---|---|
Description | search for items, and returns back a paginated result search. | |
Cookies | none |