Name	Design Goal	Location	Comments
responsive checkout	single page checkout, mobile friendly	https://github.com/UltraCart/responsive_checkout
two page trial	simple, geared toward trial offers		coming soon	wordpress plugin	wordpress	coming soon	drupal plugin	drupal	coming soon	joomla plugin	joomla	coming soon

Object Model

These json objects are used with the Cart REST API. The documentation below is shared with checkout versions 1.0 and 2.0. So you will see references to those libraries as well. Please consult the API section below the REST specific usage.

...

Field Type Comment

cartId string The unique ID for the cart. This needs to be stored as a cookie on the customer's browser so that the cart can be retrieved.

merchantId string The char(5) merchant designation (created during sign up)

errors string[] an array of errors returned from a call. This property should always be consulted after a call returns and messages displayed to the end customer.

advertisingSource string Advertising source the customer selected or entered.

affiliateId string The ID of the affiliate associated with this cart. You can set this field to manually assign an order to a specific affiliate. If no affiliate is associated with the order then this field will be null.

affiliateSubId string The Sub ID of the affiliate associated with this cart. The same comments for affiliateId apply to this field as well.

amazonMerchantId string The merchant's Amazon Seller ID as configured in the UltraCart system.

amazonOrderReferenceId

string

The reference id provided by Amazon once the customer has initiated checkout with them. If this is non-null and cart.paymentMethod is "Amazon", the order will be processed through Amazon.

Tip

This cart example has all of the amazon code plumbed. Take some time to understand it. It is NOT a trivial few lines of code to make it work seamlessly.

https://github.com/UltraCart/rest_api/tree/master/cart_example

amazonWidgetUrl

string

The url for the amazon widget script. This will be production or sandbox depending on your UltraCart configuration.

Note
The example link in the amazonOrderReferenceId does not use these values since the scripts are loaded statically.

amazonButtonUrl string The url for the amazon button script. This will be production or sandbox depending on your UltraCart configuration.

arbitraryShippingHandlingTotal number Override field allowing merchant to override the shipping and handling calculated by the system. To use this field, the Shipping and Handling must be configured to allow overrides.

arbitraryTax number Override field allowing merchants to override calculated tax. To use this field, the Tax must be configured to allow overrides.

arbitraryTaxRate number Override field allowing merchants to override calculated tax rate. To use this field, the Tax must be configured to allow overrides.

arbitraryTaxableSubtotal number Override field allowing merchants to override the taxable subtotal. To use this field, the Tax must be configured to allow overrides.

baseCurrencyCode

string

The default currency code for the merchant. For most merchants, this will be USD, but can be changed in the merchant's configuration.

see also currencyCode

Valid values are:

AUD Australian Dollar
CAD Canadian Dollar
EUR Euro
JPY  Japanese Yen
MXN  Mexican Peso
NOK  Norwegian Krone
NZD  New Zealand Dollar
GBP  Pound Sterling
RUB  Russian Ruble
SGD  Singapore Dollar
SEK  Swedish Krona
CHF  Swiss Franc
TRY  Turkish New Lira
USD  US Dollar
BRL  Brazilian Real

billToAddress1 string Bill to address line 1

billToAddress2 string Bill to address line 2

billToCity string Bill to city

billToCompany string Bill to company

billToCountry string Bill to country. Must be a valid country name from the getAllowedCountries() API call.

billToDayPhone string Bill to day phone

billToEveningPhone string Bill to evening phone

billToFirstName string Bill to first name

billToLastName string Bill to last name

billToPostalCode string Bill to postal code

billToState string Bill to state

billToTitle string Bill to title

buysafeBondAvailable boolean buySAFE bond availability

buysafeBondCost number Cost of the buySAFE bond (for buySAFE merchants only)

buysafeBondFree number True if the buySAFE bond is free to the customer

buysafeBondWanted boolean True if the customer has opted in to a buySAFE bond

buysafeCartDisplayText string The sales text to display by the buySAFE control

buysafeCartDisplayUrl string The URL to link the sales text to so the customer can learn more about buySAFE.

ccEmail string CC Email address

collectCreditCardVerificationNumber boolean True if the CVV2 should be collected for this merchant.

comments

string

customer comments. this is usually collected via a textarea field.

Added 12/2/2013

coupons CartCoupon[ ] Coupons that have been applied to the cart.

creditCardExpirationMonth Integer Credit card expiration month 1 = January 12 = December

creditCardExpirationYear integer Credit card expiration year. Must be a four digit year.

creditCardNumber

string

Credit card number

Warning
As of January 2014, there is a new method for collecting credit card numbers. Please collect card numbers through the card store script. This optional method will become a requirement in the very near future.

creditCardToken string Credit card token (if you are using a tokenizing gateway like Stripe.com)

creditCardType string Type of credit card. See the CREDIT_CARD_TYPE_ constants in the checkoutapi.js file for valid values.

creditCardTypes string[] An array of credit card types (Visa, Mastercard, etc.) that are currently accepted. Used to generate drop down lists.

creditCardVerificationNumber string Credit card verification number 4 digits for American Express and 3 digits for all other types of credit cards.

currencyCode

string

The currency of the cart. The default is the merchant default. Change this value to set the currency of the cart to a different value. If the first item added to the cart has a default currency other than USD, the cart currency will change to match the first item automatically.

(see also baseCurrencyCode)

customerProfileCreditCardId

Integer

The oid (object id) of a stored (on file) credit card to use with the checkout. Supply this to us a credit card on file.

When this is value is passed in to an update call, it will return back a cart with all the card information populated (number masked).

If you wish to remove a stored credit card from an order, set this property to 0 (zero). That will reset it.

The credit card id is found in the cart object of a logged in customer at cart.customerProfile.creditCards[0].id

Warning

UltraCart does not store CVV values. If you chose to allow stored credit cards, you must configure your payment gateway not to require CVV values. If a stored card is used, UltraCart will not validate/require a CVV.

A list of stored credit cards can be obtained from the MyAccount REST API. The customer must be logged in to retrieve a list of credit cards on file.

Note

There are two ways to create a customer account (profile). The /rest/cart methods do not actually create the customer profile until the order completes. At that time, it will store the addresses used and credit cards (if your merchant account is configured to do so).

The MyAcccount REST API does create the customer immediately so it can be used with the MyAccount customer portal. Both APIs use a shopping cart as the underlying cookie/state maintenance. So a customer logged into one is automatically logged into the other.

customField1 string A custom field to store up to 50 characters.

customField2 string A custom field to store up to 50 characters.

customField3 string A custom field to store up to 50 characters.

customField4 string A custom field to store up to 50 characters.

customField5 string A custom field to store up to 50 characters.

customField6 string A custom field to store up to 50 characters.

customField7 string A custom field to store up to 50 characters.

customerProfile CustomerProfile If loggedIn, this variable will contain the CustomerProfile for the current session.

deliveryDate Date Delivery date (optional)

email string Email address

emailConfirm string Second copy of email address used to confirm the customer entered it correctly

exchangeRate number The conversion rate between merchant default and local currencies

giftCertificate string Gift certificate code

giftCertificateAmount

giftCertificateAmountLocalized

giftCertificateAmountLocalizedFormatted

number

string

Gift certificate amount

giftCertificateRemainingBalanceAfterOrder

giftCertificateRemainingBalanceAfterOrderLocalized

giftCertificateRemainingBalanceAfterOrderLocalizedFormatted

number

string

The balance remaining the gift certificate if its initial value was greater than the cart total.

giftCharge

giftChargeLocalized

giftChargeLocalizedFormatted

number

string

Gift charge

giftEmail string Email address of the person receiving this purchase as a gift

giftEmail string Gift Email address

giftMessage string Gift message

giftWrapCost

giftWrapCostLocalized

giftWrapCostLocalizedFormatted

number

string

Gift wrap cost

hasAmazon boolean This will be true if the merchant has "Pay with Amazon" configured properly AND the cart supports it, i.e. the items can be process through Amazon Payments. If the cart is empty, this will be false, since you can't checkout with zero items.

hasPayPal boolean True if the merchant has PayPal enabled.

ipAddress string IP Address of the customer. Used for geo-location of shipping estimates.

items CartItem[ ] All the items in the cart.

liftGate boolean True if this purchase will require delivery by lift gate, false (default) otherwise.

loggedIn boolean true if a customer profile is active, false if otherwise

mailingListOptIn boolean Whether the customers wants to receive news and special offers via email.

needShipping boolean true if the cart needs shipping calculated.

needPayment

boolean

true if the cart should collect payment. This may seem a little useless since it would stand to reason that any time the total is greater than zero payment should be collected. However, there are outside cases where this flag makes the difficult easy. For example, if a customer purchases a free product that is tied to an auto order, then the total of the cart is zero, but payment must be collected for the recurring item to be charged against. This flag makes those scenarios automatic where they would otherwise be impossible to determine without some hardcoded measures.

Note: Added January 2014. Only available with the REST API

password

string

the password is only used during the login (or register) process to log a customer in. It is not populated on any returned objects, so it is lost (purposely) after login.

Constraints: 30 characters max.

payPalButtonAltText string Alt text to use on the PayPal express checkout image

payPalButtonUrl string URL of the PayPal express checkout image

payPalCompatible boolean True if this cart is compatible with PayPal

paymentMethod string Type of payment method. See the PAYMENT_METHOD_ constants in the checkoutapi.js file for valid values.

purchaseOrderNumber string Purchase order number

rtgCode string Specify the Rotating Transaction Gateway for this checkout experience.

screenBrandingThemeCode string The screen branding theme associated with the cart.

shipOnDate Date Ship on date (optional)

shipToAddress1 string Ship to address line 1

shipToAddress2 string Ship to address line 2

shipToCity string Ship to city

shipToCompany string Ship to company

shipToCountry string Ship to country. Must be a valid country name from the getAllowedCountries() API call.

shipToFirstName string Ship to first name

shipToLastName string Ship to last name

shipToPhone string Ship to phone

shipToPostalCode string Ship to postal code

shipToResidential boolean True if the address is residential.

shipToState string Ship to state

shipToTitle string Ship to title

shippingHandling

shippingHandlingLocalized

shippingHandlingLocalizedFormatted

number

string

Shipping and handling cost

Tip

This must be set manually when assigning the shippingMethod! The backend will not calculate this during cart updates. Shipping costs are extremely slow to calculate because numerous third party companies (Fed Ex, UPS, USPS) must be contacted etc. Therefore, when you assign the shipping method, you must also set the price in order the the customer to see it correctly reflected during the ordering process. When the order is submitted, the actual shipping is recalculated and set by the back end. This prevents any clever customers from trying to override the cost by putting zero in the field.

shippingHandlingDiscount

shippingHandlingDiscountLocalized

shippingHandlingDiscountLocalizedFormatted

number

string

Shipping and handling discount (because of coupon)

shippingHandlingWithDiscount

shippingHandlingWithDiscountLocalized

shippingHandlingWithDiscountLocalizedFormatted

number

string

Shipping and handling cost after discount applied.

shippingMethod string Shipping method

specialInstructions string Special instructions for delivery.

storeCreditCard

boolean

If true and the customer has logged in (cart.customerProfile != null and cart.loggedIn == true), then the credit used during the purchase is stored in the customer's profile.

UltraCart considers it good ettiquette to prompt the user to store their credit card. On the normal checkout pages, this is done via a checkbox.

subtotal

subtotalLocalized

subtotalLocalizedFormatted

number

string

Subtotal

subtotalDiscount

subtotalDiscountLocalized

subtotalDiscountLocalizedFormatted

number

string

Subtotal discount (because of coupon)

subtotalWithDiscount

subtotalWithDiscountLocalized

subtotalWithDiscountLocalizedFormatted

number

string

Subtotal after discounts have been applied

surcharge

surchargeLocalized

surchargeLocalizedFormatted

number

string

Credit card surcharge amount

tax

taxLocalized

taxLocalizedFormatted

number

string

Tax

taxCounty string The tax county assigned to this customer. See method getTaxCounties().

taxExempt number True if the customer is tax exempt

taxRate number Tax rate

taxableSubtotal

taxableSubtotalLocalized

taxableSubtotalLocalizedFormatted

number

string

Taxable subtotal

taxableSubtotalDiscount

taxableSubtotalDiscountLocalized

taxableSubtotalDiscountLocalizedFormatted

number

string

Taxable subtotal discount (because of coupons)

taxableSubtotalWithDiscount

taxableSubtotalWithDiscountLocalized

taxableSubtotalWithDiscountLocalizedFormated

number

string

Taxable subtotal after discounts.

total

totalLocalized

totalLocalizedFormatted

number

string

Total

upsellPathCode

string

A string dictating which upsell path code should be followed. By specifying this path, this will override any upsells normally followed based on the cart contents.

Note: Added Dec, 2013, Available only for the Checkout REST API.

...

Versions Compared

Old Version 98

New Version 99

Key

Object Model

Page Comparison

Versions Compared

Old Version 98

New Version 99

Key

Object Model