Page Comparison

...

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.

...

Field Type Comment

labels hash this hash contains all the labels for the various fields below. This hash is powerful because it contains the mappings you specify in the back end "screen branding' section. See the order labels section for individual listings.

merchantId string your merchant id

customerProfileId int customer's internal identifier

orderId string order id

rejected boolean true if the order was rejected

themeCode string the theme code applied to this order. See screen branding. This code is often used when creating buy links to apply the proper look and feel to an order page. Some merchants only have one theme. Some merchants have 50.

creationDate string ISO-8601 format. When the order was created

creationDateFormatted string DD-MMM-YYYY format. When the order was created

shipOnDate string ISO-8601 format. When the order was requested to ship on.

shipOnDateFormatted string DD-MMM-YYYY format. When the order was requested to ship on.

saturdayDelivery boolean true if the order is set for Saturday delivery

rejectedDate string ISO-8601 format. When the order was rejected (null if it hasn't been)

rejectedDateFormatted string DD-MMM-YYYY format of when the order was rejected, if it was.

quoteExpirationDate string ISO-8601 format. If this order is a quote, when the quote expires.

quoteExpirationDateFormatted string DD-MMM-YYYY format. If this order is a quote, when the quote expires.

status string Completed, Rejected, Quote Sent, Quote Requested, Pre-Order Item, Pending

testOrder boolean true if this order was a test

shippingMethod string a bare bones description of the shipping method

shippingMethodName string a friendly version of the shipping method. This should be preferred for display over shippingMethod

shippingMethodDetailed string an elaborate string contain shippingMethodName and any features such as lift gates and ship to residential,

shippingMethodCompany string UPS, FedEx, etc.

shipping3rdPartyAccountNumber string

email string

ccEmails string[ ] an array of email addresses who were cc'd on the order.

giftEmail string the gift recipient's email address

billToCompany string

billToTitle string

billToFirstName string

billToLastName string

billToAddress1 string

billToAddress2 string

billToCity string

billToState string

billToPostalCode string

billToCountry string

billToDayPhone string

billToEveningPhone string

shipToCompany string

shipToTitle string

shipToFirstName string

shipToLastName string

shipToAddress1 string

shipToAddress2 string

shipToCity string

shipToState string

shipToPostalCode string

shipToCountry string

shipToDayPhone string

shipToEveningPhone string

gift boolean true if the order is a gift

liftGate boolean true if the order requires a lift gate to deliver.

shipToResidential boolean true if the delivery is a residence

hidePaymentInformation boolean whether or not to show payment information. Imagine the scenario where the cost is zero and/or gift certificates were used.

refundPresent boolean duplicate of hasRefund. Use hasRefund, as this field is deprecated and will be removed without warning.

taxShipping boolean is shipping taxed? this affects the display of subtotal information (tax before subtotal or subtotal before tax).

taxCounty string

referralCode string

advertisingSource string

paymentMethod

string

Credit Card, PayPal Order, etc.

Supported payment methods as of 6/2013 (list may change):

Check
Credit Card
Credit Card Fax In
PayPal
eCheck
Purchase Order
Unknown
Money Order
Wire Transfer
COD
CASH
SafetyPay
Amazon SC
SkyMall
Smart Bargains
Quote Request

paymentNote string A friendly working of the paymentMethod. For display purposes, use this value instead of paymentMethod. It will always read the same or better.

cardType string The type of credit card used. VISA, MasterCard, etc.

cardNumber string masked. last four digits.

coupons Coupon The coupon class contains two simple fields: code and description

items Item[ ] The items for this order

giftWrapTitle string the name of the gift wrap

giftWrapCost / giftWrapCostFormatted number / string

hasDiscount boolean true if a discount was made somewhere (often useful for adding an extra table column, etc.)

hasRefund boolean true if a refund was made somewhere (often useful for adding an extra table column, etc.)

subtotalBeforeDiscount / subtotalBeforeDiscountFormatted number / string

discount / discountFormatted number / string

subtotal / subtotalFormatted number / string subtotal with any discounts and refunds already applied

subtotalRefunded / subtotalRefundedFormatted number / string

taxRate / taxRateFormatted number / string

shippingHandlingDiscount / shippingHandlingDiscountFormatted number / string

shippingHandlingTotal / shippingHandlingTotalFormatted number / string total with any discounts and refunds already applied.

shippingHandlingRefunded / shippingHandlingRefundedFormatted number / string

tax / taxFormatted number / string tax with any refund already applied

taxRefunded / taxRefundedFormatted number / string

giftCharge / giftChargeFormatted number / string

surcharge / surchargeFormatted number / string showBuysafe boolean true if this order used buySAFE and the amounts should be shown. buysafeCost / buysafeCostFormatted number / string buysafeRefunded / buysafeRefundedFormatted number / string

~~showInsureShip~~

boolean

true if this order used InsureShip and the amounts should be shown.

Note
InsureShip is no longer available. This would only apply to old legacy orders. It's doubtful you need to consider this field.

~~insureShipCost / insureShipCostFormatted~~ number / string insure ship cost

~~insureShipRefunded / insureShipRefundedFormatted~~ number / string value of any insure ship refunded

total / totalFormatted number / string grand total

totalRefunded / totalRefundedFormatted number / string of the total, this amount was refunded

showCurrencyWarning boolean true if the currency warning (next line) should be shown.

currencyWarning string this is the standard currency warning if the order was placed in a different currnency. It contains a nicely formatted message to show to the customer.

giftCertificateCode string the gift certificate code. If the gift certificate was a credit card type, the code will be masked.

giftCertificateAmount / giftCertificateAmountFormatted number / string the amount used of the gift certificate

giftMessage

string[ ]

array of gift message lines

when this field was entered, newlines were captured to preserve the look. so this field is an array of strings broken by newlines. You may join them or iterate them as desired.

specialInstructions

string[ ]

array of special instructions text

when this field was entered, newlines were captured to preserve the look. so this field is an array of strings broken by newlines. You may join them or iterate them as desired.

comments

string[ ]

array of comments

when this field was entered, newlines were captured to preserve the look. so this field is an array of strings broken by newlines. You may join them or iterate them as desired.

trackingNumbers string[ ] array of tracking numbers

orderCase Case See the case object above. If there is a case (customer feedback) associated with this order, it will be populated in this value.

...

Hash Key	Default
quoteRequestIdField	Quote Request ID
requestDateField	Request Date
expirationDateField	Quote Expiration Date
orderIdField	Order ID
sbtField	SBT
orderDateField	Order Date
billToHeader	Bill To
shipToHeader	Ship To
jobTitleField	Job Title
titleField	Title
nameField	Name
companyField	Company
addressField	Address
cityField	City
stateField	State
zipField	Zip
countryField	Country
emailField	Email
ccEmailField	CC Email
giftEmailField	Gift Email
giftField	Gift
phoneField	Phone
eveningPhoneField	Evening Phone
taxCountyField	Tax County
shippingMethodField	Shipping Method
residential	Residential
liftGate	Lift Gate
shipOnDateField	Ship on Date
deliveryDateField	Delivery Date
shipOnAccountField	Ship on Account
advertisingSourceField	Advertising Source
wrappingPaperField	Wrapping Paper
itemHeader	Item
quantityHeader	Quantity
descriptionHeader	Description
amountHeader	Amount
refundedHeader	Refunded
subtotalBeforeDiscountsField	Subtotal before discounts
discountsField	Discounts
subtotalField	Subtotal
shippingHandlingField	Shipping/Handling
taxRateField	Tax Rate
taxField	Tax
giftChargeField	Gift Charge
surchargeField	Surcharge
giftCertificateField	Gift Certificate
totalField	Total	buySafeFree	Free!
yourActualMessage	Your actual financial statement may vary due to actual currency conversion.

...

Versions Compared

Old Version 104

New Version Current

Key