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

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
AdvertisingSource	Specifies the advertising source associated with the customer's visit or order. This can be used for tracking marketing campaigns or referrals.
AutoOrderSchedule	Allows you to pre-select a customer-selectable auto-order schedule, enabling recurring shipping options from your site.
Quantity	The quantity of the item to add to the cart. This parameter is typically paired with the ADD parameter (e.g., ADD=ItemID&Quantity=5).
CustomField1	Up to 50 characters maximum.
CustomField2	Up to 50 characters maximum.
CustomField3	Up to 50 characters maximum.
CustomField4	Up to 50 characters maximum.
CustomField5	Up to 50 characters maximum.
CustomField6	Up to 50 characters maximum.
CustomField7	Up to 50 characters maximum.
OptionName#	Used in pairs with OptionValue# to pass item options. For example, to pass two options, you would use OptionName1, OptionValue1, OptionName2, and OptionValue2.
OptionValue#	The value corresponding to the OptionName#.
VariationName#	Similar to OptionName# and OptionValue#, these parameters are used in pairs with VariationValue# to pass item variation values.
VariationValue#	The value corresponding to the VariationName#.
ShippingCheapestMethod	When present, UltraCart will automatically select the cheapest available shipping method for the order.
ShippingMethod	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 &ShippingMethod=INTL%20FLAT.
SinglePageCheckout	Set to true to force the cart into single-page checkout. (Note: This cannot be reverted to multi-page checkout within the same session by setting it to false.)
ImmediateFinalize	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.
ImmediateThirdPartyHandoff	Attempts to immediately hand off the browser to a third-party payment processor (e.g., http://CCBill.com ).
PayPalExpressCheckout	Pass true to initiate a PayPal Express Checkout session.
UpsellPathCode	Specifies a particular upsell path that should be displayed to the customer during the checkout process.
ADD_<item id>	Adds a specified quantity of an item to the cart. For example, an input field named ADD_BONES with a value of 10 would add 10 units of the item with ID "BONES" to the cart.
REMOVE_<item id>	Removes the specified item ID from the cart if it exists. For example, an input field named REMOVE_SHIRT would remove the item with ID "SHIRT".

Billing Information Parameters

Parameter	Description
BillingFirstName	The customer's billing first name.
BillingLastName	The customer's billing last name.
BillingCompany	The customer's billing company name.
BillingAddress1	The first line of the customer's billing address.
BillingAddress2	The second line of the customer's billing address.
BillingCity	The customer's billing city.
BillingState	The customer's billing state or province.
BillingPostalCode	The customer's billing postal code or zip code.
BillingCountry	The customer's billing country.
BillingDayPhone	The customer's billing daytime phone number.
BillingEveningPhone	The customer's billing evening phone number.
Email	The customer's primary email address.
CCEmail	An optional secondary email address for sending copies of order notifications.

Shipping Information Parameters

Parameter	Description
ShippingFirstName	The customer's shipping first name.
ShippingLastName	The customer's shipping last name.
ShippingCompany	The customer's shipping company name.
ShippingAddress1	The first line of the customer's shipping address.
ShippingAddress2	The second line of the customer's shipping address.
ShippingCity	The customer's shipping city.
ShippingState	The customer's shipping state or province.
ShippingPostalCode	The customer's shipping postal code or zip code.
ShippingCountry	The customer's shipping country.
ShippingDayPhone	The customer's shipping daytime phone number.
ShippingResidentialAddress	Accepts Yes or No to indicate if the shipping address is residential.

Address Copying Logic Parameters

These parameters control how billing and shipping addresses can be copied from one to the other.

Parameter	Notes
BillingSameAsShipping	Copies the shipping address details to the billing address fields, overwriting any existing billing information. This parameter does not consider other billing-related parameters.
DefaultBillingSameAsShipping	Copies the shipping address details to the billing address fields, overwriting existing billing information, unless BillingDifferent=true is also present.
DefaultShippingSameAsBilling	Copies the billing address details to the shipping address fields, overwriting existing shipping information, unless ShippingDifferent=true is also present.
BillingDifferent	This parameter acts as a cancel action for DefaultBillingSameAsShipping. If true, it prevents DefaultBillingSameAsShipping from copying the shipping address to billing. It has no effect on its own.
ShippingDifferent	This parameter acts as a cancel action for DefaultShippingSameAsBilling. If true, it prevents DefaultShippingSameAsBilling from copying the billing address to shipping. It has no effect on its own.

Credit Card Information Parameters

note

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
CreditCardType	The type of credit card (e.g., "Visa", "Mastercard", "American Express", "Discover").
CreditCardNumberToken	Replaces CreditCardNumber. Use this parameter when integrating with UltraCart's Hosted Fields solution for secure card number tokenization. See the Hosted Fields documentation for details.
CreditCardExpMonth	The two-digit expiration month of the credit card (e.g., "01" for January, "12" for December).
CreditCardExpYear	The four-digit expiration year of the credit card (e.g., "2025").
CreditCardCVV2Token	Replaces CreditCardNumberCvv2. Use this parameter when integrating with UltraCart's Hosted Fields solution for secure CVV2 tokenization. See the Hosted Fields documentation for details.
PaymentType	Accepts "Credit Card", "Check", or "eCheck".

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. Not Applicable for newer merchants on StoreFronts.
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. :::info ### SendToUrl - whitelist requirement You 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. :::info ### passThru Size Limit The limit is 10kb of passThru parameters. ::: Examples: - &passThruGreen=Red - &passThru_showWarning=true - &passThruVip=1 :::info The token for retrieving the passThru value is [passthru] :::
prop_= props_json=	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_=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 props_json parameter. Example: Cart properties of A=Anteater, B=Boar, and C=Cat. JSON (notice this is an array): [{name:"A", value:"Anteater"},{name:"B", value:"Boar"},{name:"C", value:"Cat"}] 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: /cgi-bin/UCEditor?merchantId=DEMO&props_json=%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 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>

Related Documentation

Advanced Links - JavaScript