Page Comparison

UltraCart Legacy API

Table of Contents

maxLevels	2

...

Calls to the API happen through one of the user accounts configured for a merchant. We recommend that a separate API user be configured for the merchant account with only the API permission set. This will minimize the chance that someone changes the password for the user and breaks the program using the API. Configuration of users and permissions occurs under:

Panel
Configuration Menu → Users

Make sure to define the IP addresses that you will be making API calls from otherwise you will have to worry about activating the IPs with a web browser. Below is a screen shot of where you define the IPs.

...

The result code is a numeric return code for the function call. Programmers should always look at this return code before manipulating the result data to see if the call was successful. A value of zero indicates success. All other values indicate some sort of failure. The ResultMessage field will contain additional details about the result code if available. The following table below shows the meaning of each numeric result code that can be returned by the API.

ResultCode	ResultMessage
0	Success
1	Unknown Error
2	Missing Parameter
3	Invalid Login
4	Inadequate Permissions
5	Invalid Parameter Value
6	Internal Error
7	HTTPS Required

The ResultData is always a CDATA object of the function result. The contents of this can vary from function call to function call. For instance some functions may return a simple string, XML document, BASE64 encoded image, etc.
All API calls are made to the same URL end-point with different parameters. These calls must be secured over HTTPS (SSL) in order to insure that the data provided is secured at all times. The URL to make HTTPS GET requests of is: https://secure.ultracart.com/cgi-bin/UCApi
Attempts to make these calls over regular HTTP will result in an error code being returned.

...

This function call will create a new catalog group.
Additional Required Parameters

Parameter	Description
code	Each catalog group has a code associated with it. The code is appended to the path of the parent to create the new path for this group. You should not use spaces or other characters that make difficult urls in your code values.
description	The description of the group. This is commonly displayed as a paragraph of text on the catalog.
groupTemplateOID	the OID of the template to use when a group page is rendered. This should be obtained from a call to QueryCatalogTemplateList.
hostOID	the OID of the host that you are creating the catalog group in. This should be obtained from a call to QueryCatalogHostList.
imageURL	(deprecated) the URL to an image that should be associated with the catalog group. This should not be used. Instead merchants should use the integrated multimedia functionality available within the catalog group management.
itemTemplateOID	the OID of the template to use when an individual item page is rendered within this group. This should be obtained from a call to QueryCatalogTemplateList.
parentOID	The OID of the parent group.
title	the title of the group. This is typically the use one or more words like "Products" or "Off-road Cars". The code for the group is typically the title with punctuation removed and spaces replaced with underscores.

Result Data Format
The ResultData will contain the OID of the new catalog group that has been created if the function is successful.

...

Assigns item(s) to a specified catalog group.
Additional Required Parameters

Parameter	Description
assign	An XML document that contains all the assignment information. There are two methods of identifying the items to assign (OID or item Id). An OID is just an internal number that identifies the item within UltraCart. It is very common to see OIDs in the result sets from API calls.

The format of the XML document is

Code Block

language

language	xml
theme	DJango
xml	linenumbers	true

<assign>
   <catalogGroup>catalog_group_oid_here</catalogGroup>
   <items>
      <item>item_oid_here</item>
      <item>item_oid_here</item>
      <itemId>item_id_here</itemId>
      <itemId>item_id_here</itemId>
   </items>
</assign>

...

Updates all the attributes associated
Additional Required Parameters

Parameter	Description
CatalogGroup	XML document with the OID of the catalog group and all the attribute pairs. The attributes in the XML document will replace all existing attributes on the group. Below is an example of the XML document.

Code Block

language

language	xml
theme	DJango
xml	linenumbers	true

<catalog_group>
   <oid>catalog_group_oid_here</oid>
   <attributes>
      <attribute>
         <name>author</name>
         <value>HTML Coder</value>
      </attribute>
      <attribute>
         <name>version</name>
         <value>2.0</value>
      </attribute>
   </attributes>
</catalog_group>

...

This function deletes a catalog group and any descendants of the group.
Additional Required Parameters

Parameter	Description
oid	The identifier of the catalog group to delete. This should be obtained from a call to QueryCatalogGroups.

Result Data Format
No result data is returned. A successful call will have a resultCode of zero.

...

Edits the configuration associated with an individual catalog group.
Additional Required Parameters

Parameter	Description
code	each catalog group has a code associated with it. The code is appended to the path of the parent to create the new path for this group. You should not use spaces or other characters that make difficult urls in your code values.
description	The description of the group. This is commonly displayed as a paragraph of text on the catalog.
groupTemplateOID	the OID of the template to use when a group page is rendered. This should be obtained from a call to QueryCatalogTemplateList.
imageURL	(deprecated) the URL to an image that should be associated with the catalog group. This should not be used. Instead merchants should use the integrated multimedia functionality available within the catalog group management.
itemTemplateOID	the OID of the template to use when an individual item page is rendered within this group. This should be obtained from a call to QueryCatalogTemplateList.
oid	the OID of the catalog group to obtain. This is typically obtained from a call to QueryCatalogGroups.
parentOID	The OID of the parent group.
title	the title of the group. This is typically the use one or more words like "Products" or "Off-road Cars". The code for the group is typically the title with punctuation removed and spaces replaced with underscores.

Result Data Format
No result data is returned. A successful call will have a resultCode of zero.

...

hostOID – The OID of the catalog to query. This should be obtained from a call to QueryCatalogHostList.
Result Data Format
The ResultData is a Base-64 encoded XML document. An example is shown below:

Code Block

language	xml
theme	DJango	language	xml
linenumbers	true

<groups>
   <group>
      <oid></oid>
      <parentOid></parentOid>
      <title></title>
      <description></description>
      <root></root>
      <imageURL></imageURL>
      <itemTemplateOid></itemTemplateOid>
      <groupTemplateOid></groupTemplateOid>
      <code></code>
   </group>
</groups>

The group element will repeat for as many groups as there are in the catalog. The single root element of the catalog is identified with a root = Y in the XML document.

QueryCatalogHostList

Queries a list of all the catalog hosts configured on the account.
Additional Required Parameters

<none>

Result Data Format
The ResultData is a base-64 encoded XML document. An example is shown below:

Code Block

language

language	xml
theme	DJango
xml	linenumbers	true

<hosts>
   <host>
      <oid></oid>
      <name></name>
   </host>
   <host>
      <oid></oid>
      <name></name>
   </host>
</hosts>

...

Queries all the templates associated with a given catalog host.
Additional Required Parameters

Parameter	Description
hostOID	the OID of the catalog host to retrieve templates for.

Result Data Format
The ResultData is a base-64 encoded XML document. An example of the document is shown below:

Code Block

language	xml
theme	DJango	language	xml
linenumbers	true

<templates>
   <template>
      <oid></oid>
      <name></name>
   </template>
</templates>

...

Queries all the items assigned to a single catalog group.
Additional Required Parameters

Parameter	Description
parentCatalogGroupOid	the OID of the catalog group to query the items on. This should be retrieved from a call to QueryCatalogGroups.

Result Data Format
The result is a base-64 encoded XML document. An example is provided below:

Code Block

language	xml
theme	DJango
language	xml
linenumbers	true

<items>
   <item>
      <oid></oid>
      <itemId></itemId>
      <description></description>
      <manufacturerName></manufacturerName>
      <manufacturerSku></manufacturerSku>
   </item>
</items>

...

This function removes one or more items from a catalog group.
Additional Required Parameters

Parameter	Description
remove

An XML document that describes the catalog group to remove items from and which items to remove. All the data within the document references OIDs of catalog groups and items. Below is an example document for removes item Oids 101, 102, and 103 from catalog group 10. The actual oids to make a call to this function will be retrieved from calls to QueryCatalogGroups and QueryItemsInCatalogGroup.

Code Block

language	xml
theme	DJango
language	xml
linenumbers	true

<remove>
   <catalogGroup>10</catalogGroup>
   <items>
      <item>101</item>
      <item>102</item>
      <item>103</item>
   </items>
</remove>

...

This function creates a new item, or updates an existing item, within the item management section using the details provided in an XML document.
Additional Required Parameters

Parameter	Description
Item	XML document based upon the Schema file located at https://secure.ultracart.com/xml/apiCreateItem.xsd The easiest way to understand the XML is to query an item using the QueryItem function.

Result Data Format
No result data is returned. A successful call will have a resultCode of zero.

...

This function deletes one item from the account.
Additional Required Parameters

Parameter	Description
ItemId	The item ID of the item to delete from the account. This function uses the item ID and not the OID.

Result Data Format
No result data is returned. A successful call will have a resultCode of zero.

...

This function allows the programmatic upload of files to an item's multimedia section. This function is not suitable for large files over 10MB. For files that large merchants should use the virtual FTP server.
Additional Required Parameters

Parameter	Description
data	base 64 encoded file data.
filename	the name of the file that is being uploaded.
ItemId	the item to associate this multimedia file with.

Result Data Format
No result data is returned. A successful call will have a resultCode of zero.

...

This function queries a single item from the account.
Additional Required Parameters

Parameter	Description
ItemId	item id of the item to query.

Result Data Format
If the ResultCode is zero then the function call was successful and the ResultData will contain a base-64 encoded XML document of the item's details. The XML will conform to:
https://secure.ultracart.com/xml/apiCreateItem.xsd
The returned XML can be modified and then used in an additional call to CreateItem in order

...

This function queries the item folder structure within the UltraCart account under Item Management -> Items. This folder structure can be used to place items in particular folders in calls to CreateItem or useful in displaying the hierarchy in a catalog item assignment tool.
Additional Required Parameters

Parameter	Description
hostOid	the hostOid is the oid of a catalog host. The folders will be returned with a count of the number of unassigned items there are in the folder.

Result Data Format
The ResultData of the function call is a base-64 encoded XML document of the folder structure. Below is an example of the XML document format.

Code Block

language	xml
theme	DJango	language	xml
linenumbers	true

<folders>
   <folder>
      <oid></oid>
      <parentOid></parentOid>
      <description></description>
      <unassignedItems></unassignedItems>
   </folder>
</folders>

...

This function queries the available inventory for a given item.
Additional Required Parameters

Parameter	Description
ItemId	the item id to query inventory on.

Result Data Format
If the function is successful then the ResultCode will be zero and the ResultData will contain a base-64 encoded XML document. An example of the XML document is displayed below:

Code Block

language	xml
theme	DJango
language	xml
linenumbers	true

<inventory>
   <merchant_item_id></merchant_item_id>
   <is_inventory_tracked></is_inventory_tracked>
   <quantity></quantity>
   <allocated_to_placed_orders></allocated_to_placed_orders>
   <allocated_to_shopping_carts></allocated_to_shopping_carts>
   <available_to_allocate></available_to_allocate>
</inventory>

...

No additional parameters are required on this call.
Result Data Format
If the function is successful then the ResultCode will be zero and the ResultData will contain a base-64 encoded XML document. Below is an example of the XML:

Code Block

language	xml
theme	DJango
language	xml
linenumbers	true

<inventories>
   <inventory>
      <merchant_item_id></merchant_item_id>
      <quantity></quantity>
      <allocated_to_placed_orders></allocated_to_placed_orders>
      <allocated_to_shopping_carts></allocated_to_shopping_carts>
      <available_to_allocate></available_to_allocate>
   </inventory>
   <inventory>
      <merchant_item_id></merchant_item_id>
      <quantity></quantity>
      <allocated_to_placed_orders></allocated_to_placed_orders>
      <allocated_to_shopping_carts></allocated_to_shopping_carts>
      <available_to_allocate></available_to_allocate>
   </inventory>
</inventories>

...

No additional parameters are required on this function.
Result Data Format
If the function is successful then the ResultCode will contain a zero and the ResultData will contain a base-64 encoded XML document. Below is an example of the XML document:

Code Block

language	xml
theme	DJango
language	xml
linenumbers	true

<merchant_item_ids>
   <merchant_item_id></merchant_item_id>
   <merchant_item_id></merchant_item_id>
   <merchant_item_id></merchant_item_id>
   <merchant_item_id></merchant_item_id>
</merchant_item_ids>

...

This function queries all the items that are configured within a particular folder in the item management hierarchy.
Additional Required Parameters

Parameter	Description
parentFolderOid	the Oid of the folder to query. This can be obtained with a call to QueryItemFolders.

Result Data Format
If the function is successful then the ResultCode will contain a zero and the ResultData will contain a base-64 encoded XML document. Below is an example of the XML document:

Code Block

language	xml
theme	DJango
language	xml
linenumbers	true

<items>
   <item>
      <oid></oid>
      <itemId></itemId>
      <description></description>
      <manufacturerName></manufacturerName>
      <manufacturerSku></manufacturerSku>
      <unassignedItem></unassignedItem>
      <inactive></inactive>
 </item>
</items>

...

This function updates the inventory associated with multiple items. The inventory is specified at the individual distribution center level.
Additional Required Parameters

Parameter	Description
Inventory	An XML document that contains the item ids, distribution center identifier, and inventory levels to update.

An example of the XML document is below:

Code Block

language

language	xml
theme	DJango
xml	linenumbers	true

<update_inventory>
   <distribution_center_code></distribution_center_code>
   <items>
      <item>
         <item_id></item_id>
         <quantity></quantity>
      </item>
      <item>
         <item_id></item_id>
         <quantity></quantity>
      </item>
      <item>
         <item_id></item_id>
         <quantity></quantity>
      </item>
   </items>
</update_inventory>

...

This function will check whether a given set of order Ids exists on an account.
Additional Required Parameters

Parameter	Description
orders	XML document containing all the order Ids to check.

Below is an example:

Code Block

language	xml
theme	DJango	language	xml
linenumbers	true

<orders>
   <order>
      <order_id></order_id>
   </order>
   <order>
      <order_id></order_id>
   </order>
   <order>
      <order_id></order_id>
   </order>
</orders>

The order element can be repeated for as many order Ids as you want to check.
Result Data Format
If the function call is successful then the resultCode will be zero and the resultData will contain a base-64 encoded XML document. An example of the XML document is provided below:

Code Block

language

language	xml
theme	DJango
xml	linenumbers	true

<orders>
   <order>
      <order_id></order_id>
      <exists></exists>
   </order>
   <order>
      <order_id></order_id>
      <exists></exists>
   </order>
   <order>
      <order_id></order_id>
      <exists></exists>
   </order>
</orders>

...

This method allows programs to retrieve information associated with orders in XML format. This includes all the address, item, shipping, etc. information. The information is useful for integration with marketing, accounting, and fulfillment systems. Merchants that are using QuickBooks and want to do integration should simply use the UltraBooks software instead of attempting to write their own.
Additional Required Parameters

Parameter	Description
StartDTS	specify the time range to look for orders between. The format for each parameter is YYYY/MM/DD HH:MM:SS. All times should be specified in EST.
StopDTS	specify the time range to look for orders between. The format for each parameter is YYYY/MM/DD HH:MM:SS. All times should be specified in EST.
DateType	specifies which date to consider in the search. The three options for this parameter are: Creation, Payment, and Shipment.
CurrentStage	specifies which stage the order must be in to match the search. The valid options are: AR, SD, CO, and REJ. These abbreviations stand for: PO – Pre-Orders PC – Pending Clearance AR – Accounts Receivable SD – Shipping Department CO – Completed Orders REJ – Rejected Orders

Result Data Format
The result data is a base 64 encoded XML document similar to the way order information can be exported from the web interface. The schema definition for the XML document is located at: http://secure.ultracart.com/xml/ultracart.xsd

...

This function exports up to 100 pending orders in the specified format. The orders included in this result will be the first 100 orders that have the exported to QuickBooks flag set to false on them. This function is useful for building custom exports to an accounting package.
Additional Required Parameters

Parameter	Description
format	valid values are "XML", "CSV", or "BizTracker". Typically the XML format is utilizes as it is the easiest format to represent the entire order data.

Result Data Format
If the function is successful the resultCode will be zero and the resultData will contain a base 64 encoded XML document. An example document is shown below:

Code Block

language	xml
theme	DJango
language	xml
linenumbers	true

<export>
   <orderIds>
      <orderId></orderId>
      <orderId></orderId>
      <orderId></orderId>
      <orderId></orderId>
   </orderIds>
   <document>base 64 encoded document</document>
</export>

...

This function marks one or more orders as exported to accounting.
Additional Required Parameters

Parameter	Description
orderIds	XML document of all the orderIds to mark as exported to accounting.

An example is shown below:

Code Block

language	xml
theme	DJango	language	xml
linenumbers	true

<orderIds>
   <orderId></orderId>
   <orderId></orderId>
   <orderId></orderId>
   <orderId></orderId>
   <orderId></orderId>
</orderIds>

...

This function marks an order as shipped for the default distribution center.
Additional Required Parameters

Parameter

Description

orderId

the order id to mark as shipped.

skipCustomerNotification

prevents a shipment email from being sent to the customer

trackingNumber

the package tracking number. This parameter must be specified on the function call even if no tracking number is provided. Just provide an empty string if that is the case.

distributionCenterCode

The distribution center code that shipped out this order.

Note
If not specified then it assumes the default distribution center. If the order did not go out the default distribution center then it will not be marked shipped. We recommend you always provide this parameter if you have more than one distribution center.

Result Data Format
If the function is successful the resultCode is zero. There is no resultData associated with this function.

...

This function marks an order is having a successful payment processed on it. This function does not cause a card to be charged. It is only to facility offline payment processing and reporting back to UltraCart. The order will move from the Accounts Receivable to the Shipping Department or Completed Orders depending upon whether shipping is required.
Additional Required Parameters

Parameter	Description
orderId	the order id to mark the payment as processed on.

Result Data Format
If the function is successful the resultCode is zero. There is no resultData associated with this function.

...

This function will purge credit card information from an order. This will clear out the card number and set the expiration to January, 1990.
Additional Required Parameters

Parameter	Description
orderId	the order id to purge credit card information on.

Result Data Format
If the function is successful the resultCode is zero. There is no resultData associated with this function.

...

This function will export a single order in XML Schema format for the given order Id.
Additional Required Parameters

Parameter	Description
orderId	the order Id to export.

Result Data Format
If the function is successful the resultCode will be zero and the resultData will contain a base 64 encoded XML document for the order. The XML document will conform to the following Schema definition:
https://secure.ultracart.com/xml/ultracart.xsd

...

This function searches the order database and returns the matching orders in an XML Schema export format. The result can contain up to 100 matching order records.
Additional Required Parameters

Parameter	Description
firstName	first name to search on
lastName	last name to search on
email	email to search on
base64	True if XML export should be based 64. We recommend specifying this because some orders now contain XML characters that can not be nested inside of the legacy API response message. Defaults to false.

At least one of the three parameters is required. A % can be used as a wildcard in the search fields. All the parameters must be specified, but two of the three can be left blank.
Result Data Format
If the function is successful then the resultCode will be zero and the resultData will contain a base 64 encoded XML document. The XML document will conform to the following Schema definition:
https://secure.ultracart.com/xml/ultracart.xsd

Versions Compared

Old Version 16

New Version 17

Key

QueryCatalogHostList