/
UltraCart REST Checkout API

UltraCart REST Checkout API



This is Version 1 of the UltraCart REST API. It is now legacy. It will remain forever, but no new development will be done.

Please see Version 2 for new development.  Version 2 contains language specific SDKs, more functionality, and reduced API call counts.

Version 2 Main Documentation

Version 2 Supplemental Documentation

 

Additional Note, August 2020:

To prevent anyone from using this code in a new installation, several key samples have been removed.  These samples referred to php scripts that are no longer compatible with the UltraCart engine.    You should not be using this javascript anymore.   This documentation exists only for a reference for old legacy implementations.



Changes

(this list was started Aug 2014)

August 2014

Added localization to support non US currencies.    There are two ways to set the currency of the shopping cart.    

1. Updating the cart with cart.currencyCode will cause the localized fields to display in that currency.

2. Adding an item to the cart which has the item cost in a different currency will set the cart to that currency.   Only the first item added alters the currency of the cart.

You will now see additional fields on the Cart and CartItem ending with "Localized" and "LocalizedFormatted".  The localized fields contain currency amounts in the local currency.    The formatted fields are strings containing currency symbols for easy use in templates and mark up.

Introduction (Things you'll wish you read first)

The UltraCart REST API aims to be a lightweight protocol for tying a checkout page(s) to the UltraCart back end.



Merchant ID Required

Every call needs a merchant id (our merchant id is DEMO). We need to know who you are. There are three ways to provide the merchant id to the server:

  1. Query Parameter: _mid=DEMO

  2. HTTP Header: 'X-UC-Merchant-Id': 'DEMO'

  3. Cookie named UltraCartMerchantID

Most of the examples below use the http header since it's easy to use with jQuery. If you wished to do it for all your ajax calls, you could execute this javascript:

jQuery.ajaxSetup({ cache: false, headers: {'X-UC-Merchant-Id': 'DEMO', "cache-control": "no-cache"});

However, that makes each call less atomic (and jQuery doesn't recommend it). Still, it's an option and may work well with your site.

If you receive an error "Missing Merchant ID", you've forgotten to do one of the above.



Now, in case you're wondering why the three methods use different names...

  1. We made the query parameter as short as possible to keep the urls as short as possible. We used an underscore to denote "meta data" to the call.

  2. We follow common practices for naming custom http headers. While the X- prefix is officially out of vogue, we still think it looks cool.

  3. The cookie 'UltraCartMerchantID' is used in hundred of existing UltraCart checkout pages. So it made sense to stick with that cookie name.



Where are the errors?

When something doesn't work or you get an error, open your browser console and view the headers. Look for the error.

then fix it.

Can't? Then get on github.com. Ask for help here.

Note Regarding Support for API

API troubleshooting

UltraCart's free support does not cover API development questions or troubleshooting of custom checkout pages.

Please post your questions to the "Issues" section of the github.com API reponsitories, which are monitored and responded to by the API developers. Please allow 24-48 hours for a reply.

Additional API support and troubleshooting services can be purchased at $100/hr (1 hour minimum) via UltraCart Professional Services.

(Scheduling of paid for support will be determined by Professional Services personnel.)



/rest/cart/checkout is not the end

/rest/cart/checkout is NOT THE END! It's the beginning of the end. If the response from checkout has no errors, you must redirect the browser to the url found in checkoutResonse.redirectToUrl. That finishes the order. Any errors during that phase (card declined) will send the browser back to checkoutRequest.redirectOnErrorUrl, which is usually set to your checkout page. It's a circle, one that handles shipping companies and payment gateway timeouts without timing out the browser. It also handles any upsell gauntlets. So make sure you follow the redirect!

// incompatible code. this code was removed.





Do this or you'll never complete an order...

By July 15th, 2015, all UltraCart checkouts must use Hosted Fields to collect credit card information.  This replaces the old storeCard function.   This is a requirement for PCI 3.0.  UltraCart staff has already updated many sites and the average time to retrofit an existing site to using Hosted Fields has taken under 20 minutes.   Some of them have been switched over in less than 5 minutes.  While the implementation of Hosted Fields is gory, the installation of them is trivial.   Please see this page for details.

Reference Implementations

All reference implementations will be hosted on github.com under the UltraCart tree ( https://github.com/UltraCart ).  You are invited and encouraged to participate in the development of these interfaces.  We hope you will use, clone, fork, and help improve these interfaces by filing suggestions and bug reports.

Current Implementations

Name

Design Goal

Location

Comments

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

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.

Cart Objects

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.

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.

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

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

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



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.



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

number

string

Gift certificate amount

giftCertificateRemainingBalanceAfterOrder

giftCertificateRemainingBalanceAfterOrderLocalized

giftCertificateRemainingBalanceAfterOrderLocalizedFormatted

number

number

string

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

giftCharge

giftChargeLocalized

giftChargeLocalizedFormatted

number

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

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