Parameters that can be passed to UCEditor
- Perry Tew
- Chris Torigian
- Former user (Deleted)
Parameters that can be passed to UCEditor
This document describes the UCEditor URL, the primary entry point for integrating your website with the UltraCart shopping cart system.
UCEditor Overview
The URL http://secure.ultracart.com/cgi-bin/UCEditor is the fundamental link between your website and your UltraCart account. It serves two main purposes: displaying the contents of a customer's shopping cart and adding items to it. You can interact with UCEditor using either HTTP GET or HTTP POST requests.
Why "UCEditor"?
The name UCEditor (UltraCart Editor) reflects its original purpose as a "cart editor" over 15 years ago. Despite significant evolution and hundreds of updates to its functionality, the URL remains unchanged due to hundreds of thousands of existing links across the web.
Common Use Case
In a typical setup, your product display pages will include an "Add to Cart" button. This button is often part of an HTML form that sends data to the UCEditor URL, allowing customers to easily add products to their cart.
URL Parameters
MerchantID (Required)
This parameter identifies your UltraCart account.
Format: 1-5 character merchant ID
Example:
http://secure.ultracart.com/cgi-bin/UCEditor?MerchantID=DEMO
ADD (Optional)
This parameter allows you to add a single item to the cart.
Format: The Item ID of the product you wish to add.
Example:
http://secure.ultracart.com/cgi-bin/UCEditor?MerchantID=DEMO&ADD=MyItemID
Proper URL for Use with Storefronts
When integrating UCEditor with an UltraCart Storefront, you must replace the default secure.ultracart.com hostname with your specific storefront's hostname.
For example, if your storefront's domain is demo.ultracartstore.com, the UCEditor URL would be
http://demo.ultracartstore.com/cgi-bin/UCEditor
Cart Management Parameters
These parameters control how items are added to or cleared from the cart.
ClearCart (Optional)
When present, ClearCart=true will empty the customer's shopping cart of all existing items before processing any new ADD parameters or multiple item additions.
Example:
http://demo.ultracartstore.com/cgi-bin/UCEditor?MerchantID=DEMO&ClearCart=true&ADD=NewItem
NewCart (Optional)
When present, NewCart=true will completely reset the customer's shopping session by removing all items and other existing cart information before processing any new ADD parameters or multiple item additions. This creates a completely fresh cart.
Example:
http://demo.ultracartstore.com/cgi-bin/UCEditor?MerchantID=DEMO&NewCart=true&ADD=FirstItem
Force to Single Page Checkout
SinglePageCheckout (Optional)
Using SinglePageCheckout=true will force the customer's shopping session into the single-page checkout flow, regardless of your store's default checkout configuration.
Example:
http://demo.ultracartstore.com/cgi-bin/UCEditor?MerchantID=DEMO&SinglePageCheckout=true
Note: Once a customer's session is forced into the single-page checkout, it cannot be reverted to the multi-page checkout within the same session. SinglePageCheckout=false is not a valid parameter and will have no effect.
Pre-populating Cart Data From an External Form
You can pre-populate various fields within the UltraCart checkout process by passing specific parameters to the UCEditor URL via either an HTTP GET or POST request.
General Parameters
Parameter | Notes |
|---|---|
| Specifies the advertising source associated with the customer's visit or order. This can be used for tracking marketing campaigns or referrals. |
| Allows you to pre-select a customer-selectable auto-order schedule, enabling recurring shipping options from your site. |
| The quantity of the item to add to the cart. This parameter is typically paired with the |
| Up to 50 characters maximum. |
| Up to 50 characters maximum. |
| Up to 50 characters maximum. |
| Up to 50 characters maximum. |
| Up to 50 characters maximum. |
| Up to 50 characters maximum. |
| Up to 50 characters maximum. |
| Used in pairs with |
| The value corresponding to the |
| Similar to |
| The value corresponding to the |
| When present, UltraCart will automatically select the cheapest available shipping method for the order. |
| Used to force a specific shipping method. The value should be the exact name of the shipping method. For example, to force "INTL FLAT" shipping, use |
| Set to |
| Attempts to immediately finalize the order. Only use this if you are providing all necessary billing, shipping, credit card information, and the cheapest shipping method parameters simultaneously. |
| Attempts to immediately hand off the browser to a third-party payment processor (e.g., http://CCBill.com ). |
| Pass |
| Specifies a particular upsell path that should be displayed to the customer during the checkout process. |
| Adds a specified quantity of an item to the cart. For example, an input field named |
| Removes the specified item ID from the cart if it exists. For example, an input field named |
Billing Information Parameters
Parameter | Description |
|---|---|
| The customer's billing first name. |
| The customer's billing last name. |
| The customer's billing company name. |
| The first line of the customer's billing address. |
| The second line of the customer's billing address. |
| The customer's billing city. |
| The customer's billing state or province. |
| The customer's billing postal code or zip code. |
| The customer's billing country. |
| The customer's billing daytime phone number. |
| The customer's billing evening phone number. |
| The customer's primary email address. |
| An optional secondary email address for sending copies of order notifications. |
Shipping Information Parameters
Parameter | Description |
|---|---|
| The customer's shipping first name. |
| The customer's shipping last name. |
| The customer's shipping company name. |
| The first line of the customer's shipping address. |
| The second line of the customer's shipping address. |
| The customer's shipping city. |
| The customer's shipping state or province. |
| The customer's shipping postal code or zip code. |
| The customer's shipping country. |
| The customer's shipping daytime phone number. |
| Accepts |
Address Copying Logic Parameters
These parameters control how billing and shipping addresses can be copied from one to the other.
Parameter | Notes |
|---|---|
| Copies the shipping address details to the billing address fields, overwriting any existing billing information. This parameter does not consider other billing-related parameters. |
| Copies the shipping address details to the billing address fields, overwriting existing billing information, unless |
| Copies the billing address details to the shipping address fields, overwriting existing shipping information, unless |
| This parameter acts as a cancel action for |
| This parameter acts as a cancel action for |
Credit Card Information Parameters
Warning: Directly passing raw credit card numbers and CVV2 codes is not recommended due to PCI compliance requirements. UltraCart strongly recommends using Hosted Fields for secure collection of sensitive payment information.
Parameter | Notes |
|---|---|
| The type of credit card (e.g., "Visa", "Mastercard", "American Express", "Discover"). |
| Replaces |
| The two-digit expiration month of the credit card (e.g., "01" for January, "12" for December). |
| The four-digit expiration year of the credit card (e.g., "2025"). |
| Replaces |
| Accepts |
Additional Parameters
Parameter | Notes |
|---|---|
arbitraryunitcost | allows you to set a cost for the item within a range of valid prices |
ReferralCode | Must match an actual referral program unless UltraCart support has turned on a flag to allow any arbitrary code to be passed |
OVERRIDECATALOGURL | URL That the customer is sent to after they have completed the order. This overrides the default behavior of sending them back to whatever the referrer header of the original request indicated. |
OVERRIDECONTINUESHOPPINGURL | URL that the customer is sent to after they click continue shopping. This overrides the default behavior of sending them back to whatever the referrer header of the original request indicated. |
ThemeCode | Sets the theme code of the branding to be used during the checkout. This should be used by merchants that have multiple branding themes. |
RtgCode | Sets the specific rotating transaction gateway that should be used to process this order. |
CurrencyCode | If you have multi-currency enabled, this parameter sets the specific currency code for the checkout. |
COUPON | Code of a coupon to add to the cart |
ClearCoupon | If this parameter is "true" then all coupons on the cart are removed. |
GiftCertificate | Gift certificate code to apply to the cart. |
AFFID | Appends Affiliate ID to a buy link. (Note you can also add the also append the Sub-ID) |
SUBID | Appends a sub-ID to the affiliate which allows for tracking where the link is used (more details here regarding using Sub-ID's with affiliate links) |
PREFERREDDCCODE | CODE (Where CODE= the Distribution Center Code - This parameter is used with accounts that have multiple distribution centers in order to force an order to use a specific distribution center to the order. |
SendToUrl | Immediately send the browser to another url after adding the information to the cart. This URL must be one of the permitted ones based upon your UltraCart account merchant profile, catalogs, StoreFronts or SSL certificates. SendToUrl - whitelist requirementYou must contact support to have them whitelist the host address to which the customer will be sent. Each domain that is used as the target must be white listed by our support staff in order to prevent abuse as an open relay. |
ImmediateContinueShopping | Immediately send the browser back to the page that clicked the add to cart button. |
ImmediateCheckout | If specified the customer is forced in to an immediate checkout. |
LanguageIsoCode | If you are using a multi-lingual StoreFront, you can pass the three letter ISO language code to trigger a specific language. By default StoreFronts will look at the browsers Accept-Language header to determine which language the customer desires so we recommend only passing this if you dealing with a checkout only scenario and and a external single language website. |
passThru | Any parameter that starts with passThru will be carried through to the next page. passThru Size LimitThe limit is 10kb of passThru parameters. Examples:
|
prop_<name>=<value> props_json=<json string> | Cart Properties are new features of UltraCart shopping carts and orders. They supplement custom fields by allowing for a nearly unlimited number of custom properties for a cart. They are designed for and accessible only through the UltraCart Rest API. There are two methods for setting cart properties: simple and json. Simple add query parameters using the format prop_<name>=value. Examples: ?merchantId=DEMO&prop_color=red&prop_vip=true&prop_bilbo=baggins JSON For a json parameter, create an array of CartProperty objects ('name' and 'value'), then url encode it and pass it as the Example: Cart properties of A=Anteater, B=Boar, and C=Cat. JSON (notice this is an array): Url encode the above json like this: %5B%7Bname%3A%22A%22%2C+value%3A%22Anteater%22%7D%2C%7Bname%3A%22B%22%2C+value%3A%22Boar%22%7D%2C%7Bname%3A%22C%22%2C+value%3A%22Cat%22%7D%5D The actual parameter should be thus:
Once added, these parameters may be accessed easily through the UltraCart provided SDKs. Here is one such example from our PHP library: https://github.com/UltraCart/rest_api_v2_sdk_php/blob/master/lib/models/CartProperty.php and more importantly, once the cart becomes an order, as an order property https://github.com/UltraCart/rest_api_v2_sdk_php/blob/master/lib/models/OrderProperty.php |
Passing multiple items at once
In certain cases you may wish to create a buy link or buy form that add multiple items, which can be accomplished with adding multiple "add" parameters:
http://secure.ultracart.com/cgi-bin/UCEditor?MerchantID=DEMO&ADD=BONE&ADD=DOG-COLLAR
What if you need to be able to include the qty of each item, in the situation above there are only two options, leave the qty out and let the customer adjust the quantity after adding the items to the shopping cart, or including a quantity parameter which would have to be the same for both.
http://secure.ultracart.com/cgi-bin/UCEditor?MerchantID=DEMO&ADD=BONE&ADD=DOG-COLLAR&QUANTITY=3
In many situation you may wish to add multiple items to the cart at once but also have the ability to define a separate quantity for each item, To do so, you will use a modify version of the buy link parameters, that uses a underscore to tie together the ADD statement with it's own quantity (this applies to other parameter, such as the OptionName1 and OptionValue1, etc.
The following variation of the previous code example uses this variation, passing three of the item "Bone" (box of bones) and 1 of the color, passing the size and color options:
http://secure.ultracart.com/cgi-bin/UCEditor?MerchantID=DEMO&ADD_BONE=3&ADD_DOG-COLLAR=1&ADD_DOG-COLLAR_OptionName1=SIZE&ADD_DOG-COLLAR_OptionValue1=X-Large&ADD_DOG-COLLAR_OptionName2=COLOR&ADD_DOG-COLLAR_OptionValue2=BLACK
Using Parameters
There are two main styles of links that merchant's use:
1) View Cart
2) Buy Link (Item)
View Cart - specify MerchantID only
Buy Link - specify MerchantID and ADD parameters.
All the other parameters can be used creatively to produce the checkout experience desired. If you have any questions, please contact UltraCart Support.
In order to make the single page checkout automatically display the calculated shipping options, add this script to the footer edit field:
<script>
shippingDestinationChanged();
</script>
-------
Sample uceditor form code skeleton
<form method="POST" action="http://secure.ultracart.com/cgi-bin/UCEditor">
<input type="hidden" name="merchantId" value="DEMO"></input>
<input type="hidden" name="add" value="Bone"></input>
<table>
<tr>
<td>Qty</td>
<td>
<input type="text" name="quantity" value="1"></input>
</td>
</tr>
<tr>
<td></td>
<td>
<input type="submit" name="submit" value="add to cart"></input>
</td>
</tr>
</table>
</form>-------
Sample uceditor form for adding multiple items at one time. The merchant id is SRVCO and the items are T200SAVINGSKIT and T300SAVINGSKIT :
<!--
notice! the *name* of the input is ADD_ + item id. the *value* is the quantity for that item.
-->
<form action='http://secure.ultracart.com/cgi-bin/UCEditor' method='POST'>
<input type='hidden' name='merchantId' value='SRVCO'/>
Please enter your desired quantities below:<br />
$200 Saving Kit <input type='text' name='ADD_T200SAVINGSKIT' size='10' maxlength='10'/><br />
$300 Saving Kit <input type='text' name='ADD_T300SAVINGSKIT' size='10' maxlength='10'/><br />
<input type='submit' value='Add to Cart'/>
</form>