UltraCart REST MyAccount API


Introduction

The MyAccount API is the backbone of the UltraCart customer portal.  It is an mini-app and part of your UltraCart web site allowing customers to view order history, edit their personal information, and correspond with you, the Merchant.  There are two forms of the customer portal.  The first is hosted by UltraCart.  The second may be hosted anywhere on your own personal web sites.  The UltraCart hosted portal is stylized using the Screen Branding themes.  Any externally hosted portal is left to individual styling via the normal means.

You may view your UltraCart hosted customer portal using this url and substituting your Merchant ID:

https://secure.ultracart.com/cgi-bin/UCMyAccount?merchantId=DEMO

(also, if you're using a custom SSL certificate, replace secure.ultracart.com with your server name...)

A reference implementation for externally hosted portals is sourced on github:  https://github.com/UltraCart/my_account

It recommended that you start with that implementation since the API was custom built for it.


Examples and Demo (Every call is used by the example script and the demo. Just search for the call.)

Examples: https://github.com/UltraCart/my_account/blob/master/js/myaccount_rest_1.3.js

Demo: https://secure.ultracart.com/merchant/integrationcenter/my_account_demo/

Note: The myaccount_rest link above will go stale as the version is incremented. If that's the case, just go here and look for the latest version: https://github.com/UltraCart/my_account/tree/master/js

Every call in the MyAccount REST API uses two cookies for authentication:

UltraCartMerchantId - Merchant ID

UltraCartShoppingCartId - Cart ID

This is to remain consistent with the UltraCart shopping cart engine. Using the same two cookies avoids multiple login prompts to the customer.

These cookies are automatically set by the login methods, so after login, security is transparent.

Most pages may use a simple model to handle expired sessions or invalid logins:

var redirectToLogin = function () {
  var location_href = "index.html";
  if (location.hash && location.hash.length > 0) {
    location_href += "?hash=" + location.hash.substring(1);
  }
  location.href = location_href;
};
jQuery(document).ajaxError(function (event, xhr) {
  if (xhr.status == 401)
    redirectToLogin();
});

Be aware that the valid presence of these two cookies is not enough to constitute a "logged in" status. The customer must have submitted their profile username and password as some point and the server must have a flag set on its internal record denoting the customer as logged. So do not assume that just because you're seeing these two cookies accompany REST calls that the customer is logged in.



Object Model

These json objects are used with the REST MyAccount API.   

  • id fields are only required for existing objects. When creating/adding new objects, the id field is always blank and provided by the UltraCart servers.
  • Any string fields larger than their maximum size are silently truncated. The field sizes are large enough to handle most data, and the truncation is rarely a problem. The biggest issue with with email addresses. But, an email over 100 characters is also a rarity (pity the soul that has that address).



Address


FieldTypeRequiredComment
idintYes*

Object Identifier. This will always be returned from the server.

Do not create one on your own (won't be accepted).

A common problem that causes our json deserializer to vomit is submitting a new Address with an empty string.

Null is okay. A string that is a parsable integer is okay. But a zero length string has no integer equivalent. Be careful not to do this!

companystring(50)No
firstNamestring(30)Yes
lastNamestring(30)Yes
address1string(32)Yes
address2string(32)No
citystring(32)Yes
statestring(32)Yes
postalCodestring(20)YesIn the US, this is known as 'zip code'
countrystring(32)Yes
titlestring(50)No
dayPhonestring(25)No
eveningPhonestring(25)No


Case

The case is the parent object for a series of emails that can be exchanges between a customer and a merchant when there is a problem.  The case is created when the customer clicks the "Feedback" button for an order.

They can then send a message to a merchant.

FieldTypeRequiredEdit/UpdateComment
caseOidstringYes*No

Object Identifier. This will always be returned from the server.

Do not create one on your own (won't be accepted).

merchantIdstring(5)YesNonot required during insert. it's collected from cookies
orderIdstring(30)YesNo
emailstring(100)YesYesorder email is used if missing
customerProfileIdstringYesNo

this is an integer (it's type is a string to avoid server parser errors)

this is the customer identifier. It is created when a customer creates a new profile during ordering.

This value can be found from the MyAccount object returned from the login methods.

creationDatestringNoNo

ISO-8601 format. very handy when used with something like moment.js

Assigned during case creation. Immutable afterwards.

creationDateFormattedstringNoNo

A formatted version of creationDate.

Format is: dd MMM yyyy HH:mm:ss

Sometimes it's not practical to format the ISO-8601 string, for example, within a Handlebars template.

subjectstring(200)YesYesThis is whatever the customer chooses to name their correspondence with you. This isn't a prominent feature (it's not used as extensively as it could be).
statusstring(50)YesYes

Valid Values: New, Open, Reply Received, Awaiting Feedback, Closed

New

Open

Reply Received - the last activity on this case was the customer sending you, the merchant, an email

Awaiting Feedback - the last activity on this case was you, the merchant, sending the customer an email.

Closed

As a merchant, you'll want to monitor New and Reply Received very closely. They require immediate response.

lastUpdateDatestringNoNo

ISO-8601 format. very handy when used with something like moment.js 

Updated whenever activity occurs. The system updates this. It will ignore any changes you make to this field.

lastUpdateDateFormattedstringNoNo

A formatted version of lastUpdateDate.

Format is: dd MMM yyyy HH:mm:ss

Sometimes it's not practical to format the ISO-8601 string, for example, within a Handlebars template.

messagesCaseMessage[ ]NoInsertan array of messages (emails). Contains both customer and merchant emails.



Case Message

 This is a wrapper object for a message, either from a customer to merchant, or merchant to customer.

Messages cannot be updated once inserted since the emails go out immediately.  It would be pointless to edit a message record.

FieldTypeRequiredEdit/UpdateComment
caseMessageOidStringYes*NoObject Identifier. This will always be returned from the server.
caseOidstringYes*No

Object Identifier. This will always be returned from the server.

Do not create one on your own (won't be accepted).

The caseOid is usually not required when a message is being created because it is extracted from the REST url.

If this message is the first of a new case, the oid won't even exist yet. Don't worry about it. It will be created and populatd in the reture value from any insert calls.

messagestring(2000)YesNothe main body of the email
messageSenderstring(20)NoNo

 The messageSender is determined by the API call. Any message created from the MyAccount REST API will be from a customer. Any message created with the OrderEditor API (currently private) will be from the merchant.

Values: Customer or Customer Service

messageDatestringNoNo

ISO-8601 format. very handy when used with something like moment.js

Assigned during message creation. Immutable afterwards.

messageDateFormattedstringNoNo

A formatted version of messageDate.

Format is: dd MMM yyyy HH:mm:ss







ChangePasswordRequest

This is the wrapper object for the old and new passwords needed to change a customer's password.  The email address is not needed because the customer must be logged in to change their password and the email address is collected from their login record.

FieldTypeRequiredEdit/UpdateComment
oldPasswordstring(30)Yes*Noold password
newPasswordstring(30)Yes*No

new password


CreditCard

A credit card object used on the payment pages.

The credit card has several int fields. Be careful that you do not submit a json object with an empty string "" in any of these fields. That will cause a parse exception and your record rejected. For number fields, must provide either a number, or null/empty. Zero length strings are not the same thing.

FieldTypeRequiredEdit/UpdateComment
merchantIdstring(30)Yes*Noold password
customerProfileIdstring(30)Yes*No

new password

ididYes*Noan internal identifer to the record. Used during updates/deletes. Do not create your own. The server will assign an id when the object is created and it will be returned from the insert call.
cardTypestringYesYes

A Valid card type. This depends on what the merchant has configured, but the possible values are: VISA, MasterCard, Discover, Diners Club, JCB, AMEX

Case and spaces matter on the card type. Take care.

cardExpMonthintYesYes1-12 corresponding to the 12 months of Jan-Feb
cardExpYearintYesYesFour digit year.
cardNumberstringYesYes

A valid credit card number. Validity depends on the card type.

When credit card records are returned from the server, they are always masked. The only time this record has the full CC number is upon insert/update. Don't worry about wiping the CC field. Leave the mask in place.

The server is smart enough to check for an updated number and apply it. If the mask is returned, the server will ignore the field.

lastUsedDatestringNoNo

ISO-8601 format. very handy when used with something like moment.js

Updated whenever the card is used or changed. Do not provide or update this value. Any updates are ignored.

This value is assigned on the server.

lastUsedDateFormattedstringNoNo

A formatted version of lastUsedDate.

Format is: dd MMM yyyy HH:mm:ss


CustomerCredentials

This is the wrapper object for the values needed during login. 

FieldTypeRequiredEdit/UpdateComment
merchantIdstring(50)YesN/A
emailstring(100)YesN/A


passwordstring(30)YesN/A


MyAccount

 This contains the high level record for the customer.   While there is overlap between this record and the shipping/billing addresses, this is the address of record.  

It cannot be deleted, except to delete the entire customer.  

This record cannot be created, except during the ordering process by the customer.  It can only be selected / updated / deleted from the MyAccount API

FieldTypeRequiredComment
merchantIdstring(5)Yes
customerProfileIdintYes*

Object Identifier. This will always be returned from the server.

Do not create one on your own (won't be accepted).

A common problem that causes our json deserializer to vomit is submitting a new Address with an empty string.

Null is okay. A string that is a parsable integer is okay. But a zero length string has no integer equivalent. Be careful not to do this!

titlestring(50)No
companystring(50)No
firstNamestring(30)Yes
lastNamestring(30)Yes
address1string(32)Yes
address2string(32)No
citystring(32)Yes
statestring(32)Yes
postalCodestring(20)YesIn the US, this is known as 'zip code'
countrystring(32)Yes
titlestring(50)No
dayPhonestring(25)No
eveningPhonestring(25)No
faxstring(32)NoDoes anyone even use fax machines any more? If so, this field is for them.
taxIdstring(15)NoVery popular field for wholesale customers.
passwordstring(30)No

This is not returned when the records are selected, and it cannot be updated via this record. It must be updated via a specific call (changePassword).

As I write this, I'm not really sure why it's even a part of this record...


NotReviewedItem

This object represents a purchased item that does not yet have a review written by the customer.  It's used on the reviews page and contains enough information to display a line enticing the customer to write a review and then direct them to the review screen.

Reviews cannot be created via this API.  This was done on purpose to drive all reviews through the review cgi.    That cgi has a multitude of functionality chosen not to duplicate.

FieldTypeComment
merchantIdstring(5)
itemIdstring(30)

The merchant item id.

merchantItemOidstringAn string containing a number that is used to internally identify the item record. Both the item id and oid are provided because both are needed at different times during the display and link creation.
lastOrderDatestring

ISO-8601 format. very handy when used with something like moment.js

Contains the last date the item was ordered. Since the "not reviewed yet" item list is a distinct list, this value helps show the most recent purchases first.

lastOrderDateFormattedstring

A formatted version of lastOrderDate.

Format is: dd MMM yyyy HH:mm:ss

Sometimes it's not practical to format the ISO-8601 string, for example, within a Handlebars template.

itemItemA complex item containing all the details about the item. See its page for specifics.


Order

Every money field below is a number value. The number field has a corresponding string field with the suffix of 'Formatted'. These formatted fields contain the currency sign and decimal places. You should use the formatted fields wherever possible. Doing currency conversions of past orders is extremely complicated.

FieldTypeComment
labelshashthis 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.
merchantIdstringyour merchant id
customerProfileIdintcustomer's internal identifier
orderIdstringorder id
rejectedbooleantrue if the order was rejected
themeCodestringthe 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.
creationDatestringISO-8601 format. When the order was created
creationDateFormattedstringDD-MMM-YYYY format. When the order was created
shipOnDatestringISO-8601 format. When the order was requested to ship on.
shipOnDateFormattedstringDD-MMM-YYYY format. When the order was requested to ship on.
saturdayDeliverybooleantrue if the order is set for Saturday delivery
rejectedDatestringISO-8601 format. When the order was rejected (null if it hasn't been)
rejectedDateFormattedstringDD-MMM-YYYY format of when the order was rejected, if it was.
quoteExpirationDatestringISO-8601 format. If this order is a quote, when the quote expires.
quoteExpirationDateFormattedstringDD-MMM-YYYY format. If this order is a quote, when the quote expires.
statusstringCompleted, Rejected, Quote Sent, Quote Requested, Pre-Order Item, Pending
testOrderbooleantrue if this order was a test
shippingMethodstring a bare bones description of the shipping method
shippingMethodNamestring a friendly version of the shipping method. This should be preferred for display over shippingMethod
shippingMethodDetailedstringan elaborate string contain shippingMethodName and any features such as lift gates and ship to residential,  
shippingMethodCompanystringUPS, FedEx, etc. 
shipping3rdPartyAccountNumberstring
emailstring
ccEmailsstring[ ]an array of email addresses who were cc'd on the order.  
giftEmailstringthe gift recipient's email address 
billToCompanystring
billToTitlestring
billToFirstNamestring
billToLastNamestring
billToAddress1string
billToAddress2string
billToCitystring
billToStatestring
billToPostalCodestring
billToCountrystring
billToDayPhonestring
billToEveningPhonestring
shipToCompanystring
shipToTitlestring
shipToFirstNamestring
shipToLastNamestring
shipToAddress1string
shipToAddress2string
shipToCitystring
shipToStatestring
shipToPostalCodestring
shipToCountrystring
shipToDayPhonestring
shipToEveningPhonestring
giftbooleantrue if the order is a gift
liftGatebooleantrue if the order requires a lift gate to deliver.
shipToResidentialbooleantrue if the delivery is a residence
hidePaymentInformationbooleanwhether or not to show payment information. Imagine the scenario where the cost is zero and/or gift certificates were used.
refundPresentbooleanduplicate of hasRefund. Use hasRefund, as this field is deprecated and will be removed without warning.
taxShippingbooleanis shipping taxed? this affects the display of subtotal information (tax before subtotal or subtotal before tax).
taxCountystring
referralCodestring
advertisingSourcestring
paymentMethodstring

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

paymentNotestringA friendly working of the paymentMethod. For display purposes, use this value instead of paymentMethod. It will always read the same or better.
cardTypestringThe type of credit card used. VISA, MasterCard, etc.
cardNumberstringmasked. last four digits.
couponsCouponThe coupon class contains two simple fields: code and description
itemsItem[ ]The items for this order
giftWrapTitlestringthe name of the gift wrap
giftWrapCost / giftWrapCostFormattednumber / string
hasDiscountbooleantrue if a discount was made somewhere (often useful for adding an extra table column, etc.)
hasRefundbooleantrue if a refund was made somewhere (often useful for adding an extra table column, etc.)
subtotalBeforeDiscount / subtotalBeforeDiscountFormattednumber / string
discount / discountFormattednumber / string
subtotal / subtotalFormattednumber / stringsubtotal with any discounts and refunds already applied
subtotalRefunded / subtotalRefundedFormattednumber / string
taxRate / taxRateFormattednumber / string
shippingHandlingDiscount / shippingHandlingDiscountFormattednumber / string
shippingHandlingTotal / shippingHandlingTotalFormattednumber / stringtotal with any discounts and refunds already applied.
shippingHandlingRefunded / shippingHandlingRefundedFormattednumber / string
tax / taxFormattednumber / stringtax with any refund already applied
taxRefunded / taxRefundedFormattednumber / string
giftCharge / giftChargeFormattednumber / string
surcharge / surchargeFormattednumber / string
showBuysafebooleantrue if this order used buySAFE and the amounts should be shown.
buysafeCost / buysafeCostFormattednumber / string
buysafeRefunded / buysafeRefundedFormattednumber / string
showInsureShipboolean

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

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

insureShipCost / insureShipCostFormattednumber / stringinsure ship cost
insureShipRefunded / insureShipRefundedFormattednumber / stringvalue of any insure ship refunded
total / totalFormattednumber / stringgrand total
totalRefunded / totalRefundedFormattednumber / stringof the total, this amount was refunded
showCurrencyWarningbooleantrue if the currency warning (next line) should be shown.
currencyWarningstringthis 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.
giftCertificateCodestringthe gift certificate code. If the gift certificate was a credit card type, the code will be masked.
giftCertificateAmount / giftCertificateAmountFormattednumber / stringthe amount used of the gift certificate
giftMessagestring[ ]

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.

specialInstructionsstring[ ]

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.

commentsstring[ ]

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.

trackingNumbersstring[ ]array of tracking numbers
orderCaseCaseSee the case object above. If there is a case (customer feedback) associated with this order, it will be populated in this value.

Order Labels

The order labels are formatted labels for use when displaying an order.  They should be used whenever possible.

The default value is what is used if you have not configured anything custom in your Checkout Text section of the Configuration area.

Hash KeyDefault

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.


OrderTracking

Read-Only tracking information for an order

FieldTypeComment
merchantIdstringYour merchant id
orderIdstringThe order id
hasTrackingUrlbooleantrue if the url is present. This flag, although seemingly useless, makes templating very easy. when a boolean is quicker and simpler to use than a "is this field present and not empty" check
trackingNumberstringThe tracking number
trackingUrlstringThe full url to the shipper's web site.


ReviewedItem

This read-only object contains an item review.

FieldTypeComment
itemIdstringthe item id of the item reviewed
itemItem A complex item containing all the details about the item. See its page for specifics.
reviewOidintegerreview record's internal identifier
merchantIdstringthe merchant id (your merchant id)
customerProfileIdintegercustomer's internal identifier
merchantItemOidintegeritem's internal identifier
overallnumber1-5 The overall rating of the item. This should be featured prominently.
ratingName1stringThe name (category) of this rating. Configured by the merchant. Examples: Ease of Use, Price, Durability, etc.
ratingName2stringThe name (category) of this rating.
ratingName3stringThe name (category) of this rating.
ratingName4stringThe name (category) of this rating.
ratingName5stringThe name (category) of this rating.
ratingName6stringThe name (category) of this rating.
ratingName7stringThe name (category) of this rating.
ratingName8stringThe name (category) of this rating.
ratingName9stringThe name (category) of this rating.
ratingName10stringThe name (category) of this rating.
ratingScore1number1-5, the rating for the associated rating name.
ratingScore2number1-5, the rating for the associated rating name.
ratingScore3number1-5, the rating for the associated rating name.
ratingScore4number1-5, the rating for the associated rating name.
ratingScore5number1-5, the rating for the associated rating name.
ratingScore6number1-5, the rating for the associated rating name.
ratingScore7number1-5, the rating for the associated rating name.
ratingScore8number1-5, the rating for the associated rating name.
ratingScore9number1-5, the rating for the associated rating name.
ratingScore10number1-5, the rating for the associated rating name.
recommendToFriendbooleantrue if the customer would recomment the item to a friend.
titlestringThe title of the review
reviewstringThe review itself. These are the customer's comments.
statusCodestringApproved, Rejected, or Unapproved
featuredbooleantrue if the merchant has chosen to feature this review
recommendStoreToFriendbooleantrue if the customer would recommend your store to friends.
storeFeedbackstringany comments the customer had for your store
submittedDatestring

ISO-8601 format. very handy when used with something like moment.js

Contains the date when the review was submitted

submittedDateFormattedstring

A formatted version of submittedDate.

Format is: dd MMM yyyy HH:mm:ss

Sometimes it's not practical to format the ISO-8601 string, for example, within a Handlebars template.

helpfulYesVotesintegerthe number of times other customers have marked a review as helpful.
helpfulNoVotesintegerthe number of times other customers have marked a review as unhelpful.




MyAccount REST API

/rest/myaccount/loggedIn

Method
GET
Comments
Descriptionreturns MyAccount object if logged in, else empty object

Useful for determining if the customer is logged in without triggering a 401 Unauthorized response from the server.

In the demo, this call is only used on the main page to determine whether to show the login screen or not.

Most of the MyAccount pages will use security like this:

var redirectToLogin = function () {
 var location_href = "index.html";
 if (location.hash && location.hash.length > 0) {
 location_href += "?hash=" + location.hash.substring(1);
 }
 location.href = location_href;
};
var theDocument = jQuery(document);
theDocument.ajaxError(function (event, xhr) {

 if (xhr.status == 401)
 redirectToLogin();
});

 
However, that's not desired for the main page, so loggedIn provides a way of checking without triggering a 401.

Cookies

UltraCartMerchantId - Merchant ID

UltraCartShoppingCartId - Cart ID


Path Parametersnone
Query Parameters

none


Headers

none


Receives Jsonnone
Returns JsonMyAccount object if logged in, else empty object

Note: To avoid json parser errors from the likes of FireFox, if the customer is not logged in, the method does NOT return null. It returns an empty object.

Notice the example below checks for both result and result.email, so it's checking for a valid object that has some properties as well.

By checking both 'result' and 'result.email' for values, you'll get correct results as to whether the customer is logged in or not.

Example


  this.loggedIn = function (options) {
    options = options || {};
    var settings = null;
    jQuery.ajax({
      url: restUrl + '/loggedIn',
      type: 'get',
      async: (options.success || options.failure) ? true : false,
      headers: { "cache-control": "no-cache" },
      cache: false,
      dataType: 'json'
    }).done(function (result) {
              if(result && result.email){
                settings = result;
              } else {
                settings = null; // if the result is an empty object, then customer is not logged in.
              }
              if (options.success) {
                options.success(settings);
              }
            })
            .fail(function (jqXHR, textStatus, errorThrown) {
              if (options.failure) {
                options.failure(jqXHR, textStatus, errorThrown);
              }
            });

    return settings;
  };



/rest/myaccount/login

Method
GET or POST
Comments
Description

logs in a customer and returns their base information

(MyAccount object)

There are two ways to login: GET or POST.

For the GET, the three parameters are submitted. For POST, a CustomerCredentials object is submitted (it's a simple object with three fields).

Cookies

UltraCartShoppingCartId - Cart ID

not required, but if passed along and valid, the same shopping cart will continue to be used. Otherwise, a new cart is created and Set-Cookie headers will accompany a successful login. 
Path Parametersnone
Query Parameters

For GET:

merchantId

email

password

For POST:

none


Headers

none


Receives JsonCustomerCredentials
Returns JsonMyAccount object if successful

A failed login will result in a 401 Unauthorized http status.

Any missing parameers will result in a 400 Bad Request http status.

Example


  this.login = function (email, password, options) {
    options = options || {};
    var credentials = {merchantId: merchantId, email: email, password: password};
    var account = null;
    jQuery.ajax({
      url: restUrl + '/login',
      data: JSON.stringify(credentials),
      type: 'post',
      async: (options.success || options.failure) ? true : false,
      headers: { "cache-control": "no-cache" },
      contentType: 'application/json; charset=UTF-8',
      cache: false,
      dataType: 'json'
    }).done(function (result) {
              account = result;
              if (options.success) {
                options.success(account);
              }
            })
            .fail(function (jqXHR, textStatus, errorThrown) {
              if (options.failure) {
                options.failure(jqXHR, textStatus, errorThrown);
              }
            });
    return account;
  };




/rest/myaccount/logout

Method
GET or POST
Comments
Description

logs out a customer


Cookies

UltraCartShoppingCartId - Cart ID

used to determine which customer to logout
Path Parametersnone
Query Parameters

none


Headers

none


Receives Jsonnone
Returns Jsonnone


Example


    this.logout = function (options) {
    options = options || {};
    // even if logged out, there may be a shopping cart, so return that cart if it's returned from the server.
    var cart = null;
    jQuery.ajax({
      url: '/rest/myaccount/logout',
      type: 'get',
      headers: { "cache-control": "no-cache" },
      async: (options.success || options.failure) ? true : false,
      cache: false,
      dataType: 'json'
    }).done(function (result) {
              cart = result;
              if (options.success) {
                options.success(cart);
              }
            })
            .fail(function (jqXHR, textStatus, errorThrown) {
              if (options.failure) {
                options.failure(jqXHR, textStatus, errorThrown);
              }
            });
    return cart;
  };



/rest/myaccount/changePassword

Method
POST
Comments
Description

Updates password

This is the only way for a user to change their password

Cookies

UltraCartShoppingCartId - Cart ID

UltraCartMerchantID = Merchant ID

The customer must be successfully logged in to change their password.
Path Parametersnone
Query Parameters

none


Headers

none


Receives JsonChangePasswordRequest
Returns Jsonnothing (204 on success)

A failed login will result in a 401 Unauthorized http status.

Any missing parameers will result in a 400 Bad Request http status.

Any parameters too long will result in a 400 Bad Request http status

Example


  this.changePassword = function (oldPassword, newPassword, options) {
    options = options || {};
    jQuery.ajax({
      url: '/rest/myaccount/changePassword',
      data: JSON.stringify({oldPassword: oldPassword, newPassword: newPassword}),
      type: 'post',
      async: (options.success || options.failure) ? true : false,
      headers: { "cache-control": "no-cache" },
      cache: false,
      contentType: 'application/json; charset=UTF-8',
      dataType: 'json'
    }).done(function () {
              if (options.success) {
                options.success();
              }
            })
            .fail(function (jqXHR, textStatus, errorThrown) {
              if (options.failure) {
                options.failure(jqXHR, textStatus, errorThrown);
              }
            });
  };




/rest/myaccount/forgotPassword

Method
POST
Comments
Description

Emails customer new password


Cookies

UltraCartMerchantID = Merchant ID

The customer doesn't need to be logged in (obviously), but the Merchant ID is required.
Path Parametersnone
Query Parameters

merchantId

Optional in place of cookie
Headers

none


Receives JsonString (email)Just a single email address as a string
Returns JsonPlain text

The string "Your password was emailed to " + email is returned on success.

Example


  this.forgotPassword = function (email, options) {
    var msg = null;
    options = options || {};
    jQuery.ajax({
      url: '/rest/myaccount/forgotPassword',
      data: JSON.stringify(email),
      type: 'post',
      async: (options.success || options.failure) ? true : false,
      headers: { "cache-control": "no-cache" },
      cache: false,
      contentType: 'application/json; charset=UTF-8',
      dataType: 'text'
    }).done(function (result) {
              msg = result;
              if (options.success) {
                options.success(result);
              }
            })
            .fail(function (jqXHR, textStatus, errorThrown) {
              msg = errorThrown;
              if (options.failure) {
                options.failure(jqXHR, textStatus, errorThrown);
              }
            });
    return msg;
  };


/rest/myaccount/settings

Method
GET
Comments
Description

returns customer settings


Cookies

UltraCartMerchantID = Merchant ID

UltraCartShoppingCartId - Cart ID

The customer must be logged in.
Path Parametersnone
Query Parameters

none


Headers

none


Receives Jsonnone
Returns JsonMyAccount object

password is not returned. a string of asterisks is returned instead.

Example


   this.getSettings = function (options) {
    options = options || {};
    var account = null;
    jQuery.ajax({
      url: '/rest/myaccount/settings',
      type: 'get',
      async: (options.success || options.failure) ? true : false,
      headers: { "cache-control": "no-cache" },
      cache: false,
      dataType: 'json'
    }).done(function (result) {
              account = result;
              if (options.success) {
                options.success(account);
              }
            })
            .fail(function (jqXHR, textStatus, errorThrown) {
              if (options.failure) {
                options.failure(jqXHR, textStatus, errorThrown);
              }
            });
    return account;
  };




/rest/myaccount/settings

Method
POST
Comments
Description

creates a new customer profile

This method will begin an email validated registration process. The merchant id, email, and password are the only required fields. You may also provide the first and last name to pre-populate the account.

Upon successful email verification, any prior orders associated with the email address will be updated and assigned to the newly created account.

Cookies

UltraCartMerchantID = Merchant ID

UltraCartShoppingCartId - Cart ID

A new account cannot be created if the customer is logged in. They must log out first to create an account.
Path Parametersnone
Query Parameters

redirectUrl

themeCode

The redirectUrl is the url where you wish the customer to be redirected to after they click on their email confirmation. This should be the full url, including protocol. For security reasons, this exact url must be supplied in the Customer Profiles Settings page.

themeCode is the screen branding theme code. it ensures that if a redirect happens to a legacy page, the proper themeCode is displayed. You probably won't need this parameter if you have a StoreFront.

Headers

none


Receives JsonMyAccount object
Returns JsonMyAccount object

the return object will contain the customer profile id (unique identifier) 

If the merchant account does not allow customer profiles, a 400 Bad Request is returned.

If the email is already registered for this merchant, a 400 Bad Request is returned.

password is not returned. a string of asterisks is returned instead.

Example


    this.createAccount = function (customerInformation, options) {
    options = options || {};
    var account = null;
    jQuery.ajax({
      url: '/rest/myaccount/settings',
      data: JSON.stringify(customerInformation),
      type: 'post',
      async: (options.success || options.failure) ? true : false,
      headers: { "cache-control": "no-cache" },
      cache: false,
      contentType: 'application/json; charset=UTF-8',
      dataType: 'json'
    }).done(function (result) {
              account = result;
              if (options.success) {
                options.success(account);
              }
            })
            .fail(function (jqXHR, textStatus, errorThrown) {
              if (options.failure) {
                options.failure(jqXHR, textStatus, errorThrown);
              }
            });
    return account;
  };



/rest/myaccount/settings

Method
PUT
Comments
Description

updates customer settings

password cannot be updated here. It can only be done through changePassword. 

Cookies

UltraCartMerchantID = Merchant ID

UltraCartShoppingCartId - Cart ID


Path Parametersnone
Query Parameters

none


Headers

none


Receives JsonMyAccount object

whatever you pass in as values is set for the object. If you pass in an empty object, all account properties are blanked out.

If you pass in a single value, all others are blanked out. You should start with a fully populated account object from the get method and update that if you wish to change a single field.

Returns JsonMyAccount object

password is not returned. a string of asterisks is returned instead.

Example


  this.updateSettings = function (changes, options) {
    options = options || {};
    var account = null;
    jQuery.ajax({
      url: '/rest/myaccount/settings',
      data: JSON.stringify(changes),
      type: 'put',
      async: (options.success || options.failure) ? true : false,
      headers: { "cache-control": "no-cache" },
      cache: false,
      contentType: 'application/json; charset=UTF-8',
      dataType: 'json'
    }).done(function (result) {
              account = result;
              if (options.success) {
                options.success(account);
              }
            })
            .fail(function (jqXHR, textStatus, errorThrown) {
              if (options.failure) {
                options.failure(jqXHR, textStatus, errorThrown);
              }
            });
    return account;
  };




/rest/myaccount/settings

Method
DELETE
Comments
Description

deletes a customer profile

once a profile is deleted, it's gone. be careful allowing this.

Cookies

UltraCartMerchantID = Merchant ID

UltraCartShoppingCartId - Cart ID

Customer must be logged in to delete their profile.
Path Parametersnone
Query Parameters

none


Headers

none


Receives JsonnoneThe settings object is not required to delete a profile. The cart id is sufficient. 
Returns Jsonnone

204 No Content returned on success

Example


  this.deleteAccount = function (options) {
    options = options || {};
    jQuery.ajax({
      url: '/rest/myaccount/settings',
      type: 'delete',
      async: (options.success || options.failure) ? true : false,
      headers: { "cache-control": "no-cache" },
      cache: false,
      dataType: 'json'
    }).done(function () {
              if (options.success) {
                options.success();
              }
            })
            .fail(function (jqXHR, textStatus, errorThrown) {
              if (options.failure) {
                options.failure(jqXHR, textStatus, errorThrown);
              }
            });
  };




/rest/myaccount/shippingAddresses

Method
GET
Comments
Description

returns all shipping addresses


Cookies

UltraCartMerchantID = Merchant ID

UltraCartShoppingCartId - Cart ID

The customer must be logged in.
Path Parametersnone
Query Parameters

none


Headers

none


Receives Jsonnone
Returns JsonArray of Address objects


Example


  this.getShippingAddresses = function (options) {
    options = options || {};
    var addresses = [];
    jQuery.ajax({
      url: '/rest/myaccount/shippingAddresses',
      type: 'get',
      async: (options.success || options.failure) ? true : false,
      headers: { "cache-control": "no-cache" },
      cache: false,
      dataType: 'json'
    }).done(function (result) {
              addresses = result;
              if (options.success) {
                options.success(addresses);
              }
            })
            .fail(function (jqXHR, textStatus, errorThrown) {
              if (options.failure) {
                options.failure(jqXHR, textStatus, errorThrown);
              }
            });
    return addresses;
  };




/rest/myaccount/shippingAddresses/{id}

Method
GET
Comments
Description

returns a shipping address record


Cookies

UltraCartMerchantID = Merchant ID

UltraCartShoppingCartId - Cart ID

The customer must be logged in.
Path Parametersidaddress record identifier 
Query Parameters

none


Headers

none


Receives Jsonnone
Returns JsonAddress object


Example


   this.getShippingAddress = function (id, options) {
    options = options || {};
    var address = null;
    jQuery.ajax({
      url: '/rest/myaccount/shippingAddresses/' + id,
      type: 'get',
      async: (options.success || options.failure) ? true : false,
      headers: { "cache-control": "no-cache" },
      cache: false,
      dataType: 'json'
    }).done(function (result) {
              address = result;
              if (options.success) {
                options.success(address);
              }
            })
            .fail(function (jqXHR, textStatus, errorThrown) {
              if (options.failure) {
                options.failure(jqXHR, textStatus, errorThrown);
              }
            });
    return address;
  };





/rest/myaccount/shippingAddresses

Method
POST
Comments
Description

adds a shipping address


Cookies

UltraCartMerchantID = Merchant ID

UltraCartShoppingCartId - Cart ID

Customer must be logged in to perform this operation
Path Parametersnone
Query Parameters

none


Headers

none


Receives JsonAddress object
Returns JsonAddress object

the return object will contain the record id (unique identifier) 

Any field violations (exceeded length, missing fields) will return a 400 Bad Request.

 If the address already exists, a 400 Bad Request is returned.

Example


  this.insertShippingAddress = function (address, options) {
    options = options || {};
    var insertedAddress = null; // will contain oid
    jQuery.ajax({
      url: '/rest/myaccount/shippingAddresses',
      type: 'post',
      data: JSON.stringify(address),
      async: (options.success || options.failure) ? true : false,
      headers: { "cache-control": "no-cache" },
      cache: false,
      contentType: 'application/json; charset=UTF-8',
      dataType: 'json'
    }).done(function (result) {
              insertedAddress = result;
              if (options.success) {
                options.success(insertedAddress);
              }
            })
            .fail(function (jqXHR, textStatus, errorThrown) {
              if (options.failure) {
                options.failure(jqXHR, textStatus, errorThrown);
              }
            });
    return insertedAddress;
  };



/rest/myaccount/shippingAddresses/{id}

Method
PUT
Comments
Description

updates a shipping address record


Cookies

UltraCartMerchantID = Merchant ID

UltraCartShoppingCartId - Cart ID


Path Parametersidshipping address record identifier 
Query Parameters

none


Headers

none


Receives JsonMyAccount object
Returns JsonMyAccount object

If the address is updated to an address that already exists, a 400 Bad Request is returned.

Example


   this.updateShippingAddress = function (address, options) {
    options = options || {};
    var updatedAddress = null;
    jQuery.ajax({
      url: '/rest/myaccount/shippingAddresses/' + address.id,
      type: 'put',
      data: JSON.stringify(address),
      async: (options.success || options.failure) ? true : false,
      headers: { "cache-control": "no-cache" },
      cache: false,
      contentType: 'application/json; charset=UTF-8',
      dataType: 'json'
    }).done(function (result) {
              updatedAddress = result;
              if (options.success) {
                options.success(updatedAddress);
              }
            })
            .fail(function (jqXHR, textStatus, errorThrown) {
              if (options.failure) {
                options.failure(jqXHR, textStatus, errorThrown);
              }
            });
    return updatedAddress;
  };




/rest/myaccount/shippingAddresses/{id}

Method
DELETE
Comments
Description

deletes a shipping address


Cookies

UltraCartMerchantID = Merchant ID

UltraCartShoppingCartId - Cart ID

Customer must be logged in to delete an address
Path Parametersidaddress record identifier 
Query Parameters

none


Headers

none


Receives Jsonnone
Returns Jsonnone

204 No Content returned on success

Example


  this.deleteShippingAddress = function (address, options) {
    options = options || {};
    jQuery.ajax({
      url: '/rest/myaccount/shippingAddresses/' + address.id,
      type: 'delete',
      data: JSON.stringify(address),
      async: (options.success || options.failure) ? true : false,
      headers: { "cache-control": "no-cache" },
      cache: false,
      contentType: 'application/json; charset=UTF-8',
      dataType: 'json'
    }).done(function () {
              if (options.success) {
                options.success();
              }
            })
            .fail(function (jqXHR, textStatus, errorThrown) {
              if (options.failure) {
                options.failure(jqXHR, textStatus, errorThrown);
              }
            });
  };




/rest/myaccount/billingAddresses

Method
GET
Comments
Description

returns all billing addresses


Cookies

UltraCartMerchantID = Merchant ID

UltraCartShoppingCartId - Cart ID

The customer must be logged in.
Path Parametersnone
Query Parameters

none


Headers

none


Receives Jsonnone
Returns JsonArray of Address objects


Example


  this.getBillingAddresses = function (options) {
    options = options || {};
    var addresses = [];
    jQuery.ajax({
      url: '/rest/myaccount/billingAddresses',
      type: 'get',
      async: (options.success || options.failure) ? true : false,
      headers: { "cache-control": "no-cache" },
      cache: false,
      dataType: 'json'
    }).done(function (result) {
              addresses = result;
              if (options.success) {
                options.success(addresses);
              }
            })
            .fail(function (jqXHR, textStatus, errorThrown) {
              if (options.failure) {
                options.failure(jqXHR, textStatus, errorThrown);
              }
            });
    return addresses;
  };




/rest/myaccount/billingAddresses/{id}

Method
GET
Comments
Description

returns a billing address record


Cookies

UltraCartMerchantID = Merchant ID

UltraCartShoppingCartId - Cart ID

The customer must be logged in.
Path Parametersidaddress record identifier 
Query Parameters

none


Headers

none


Receives Jsonnone
Returns JsonAddress object


Example


  this.getBillingAddress = function (id, options) {
    options = options || {};
    var address = null;
    jQuery.ajax({
      url: '/rest/myaccount/billingAddresses/' + id,
      type: 'get',
      async: (options.success || options.failure) ? true : false,
      headers: { "cache-control": "no-cache" },
      cache: false,
      dataType: 'json'
    }).done(function (result) {
              address = result;
              if (options.success) {
                options.success(address);
              }
            })
            .fail(function (jqXHR, textStatus, errorThrown) {
              if (options.failure) {
                options.failure(jqXHR, textStatus, errorThrown);
              }
            });
    return address;
  };





/rest/myaccount/billingAddresses

Method
POST
Comments
Description

adds a billing address


Cookies

UltraCartMerchantID = Merchant ID

UltraCartShoppingCartId - Cart ID

Customer must be logged in to perform this operation
Path Parametersnone
Query Parameters

none


Headers

none


Receives JsonAddress object
Returns JsonAddress object

the return object will contain the record id (unique identifier) 

Any field violations (exceeded length, missing fields) will return a 400 Bad Request.

 If the address already exists, a 400 Bad Request is returned.

Example


  this.insertBillingAddress = function (address, options) {
    options = options || {};
    var insertedAddress = null; // will contain oid
    jQuery.ajax({
      url: '/rest/myaccount/billingAddresses',
      type: 'post',
      data: JSON.stringify(address),
      async: (options.success || options.failure) ? true : false,
      headers: { "cache-control": "no-cache" },
      cache: false,
      contentType: 'application/json; charset=UTF-8',
      dataType: 'json'
    }).done(function (result) {
              insertedAddress = result;
              if (options.success) {
                options.success(insertedAddress);
              }
            })
            .fail(function (jqXHR, textStatus, errorThrown) {
              if (options.failure) {
                options.failure(jqXHR, textStatus, errorThrown);
              }
            });
    return insertedAddress;
  };



/rest/myaccount/billingAddresses/{id}

Method
PUT
Comments
Description

updates a billing address


Cookies

UltraCartMerchantID = Merchant ID

UltraCartShoppingCartId - Cart ID


Path Parametersidbilling address record identifier 
Query Parameters

none


Headers

none


Receives JsonMyAccount object
Returns JsonMyAccount object

If the address is updated to an address that already exists, a 400 Bad Request is returned.

Example


  this.updateBillingAddress = function (address, options) {
    options = options || {};
    var updatedAddress = null;
    jQuery.ajax({
      url: '/rest/myaccount/billingAddresses/' + address.id,
      type: 'put',
      data: JSON.stringify(address),
      async: (options.success || options.failure) ? true : false,
      headers: { "cache-control": "no-cache" },
      cache: false,
      contentType: 'application/json; charset=UTF-8',
      dataType: 'json'
    }).done(function (result) {
              updatedAddress = result;
              if (options.success) {
                options.success(updatedAddress);
              }
            })
            .fail(function (jqXHR, textStatus, errorThrown) {
              if (options.failure) {
                options.failure(jqXHR, textStatus, errorThrown);
              }
            });
    return updatedAddress;
  };




/rest/myaccount/billingAddresses/{id}

Method
DELETE
Comments
Description

deletes a billing address


Cookies

UltraCartMerchantID = Merchant ID

UltraCartShoppingCartId - Cart ID

Customer must be logged in to delete an address
Path Parametersidaddress record identifier 
Query Parameters

none


Headers

none


Receives Jsonnone
Returns Jsonnone

204 No Content returned on success

Example


  this.deleteBillingAddress = function (address, options) {
    options = options || {};
    jQuery.ajax({
      url: '/rest/myaccount/billingAddresses/' + address.id,
      type: 'delete',
      data: JSON.stringify(address),
      async: (options.success || options.failure) ? true : false,
      headers: { "cache-control": "no-cache" },
      cache: false,
      contentType: 'application/json; charset=UTF-8',
      dataType: 'json'
    }).done(function () {
              if (options.success) {
                options.success();
              }
            })
            .fail(function (jqXHR, textStatus, errorThrown) {
              if (options.failure) {
                options.failure(jqXHR, textStatus, errorThrown);
              }
            });
  };



/rest/myaccount/creditCards

Method
GET
Comments
Description

returns all credit cards


Cookies

UltraCartMerchantID = Merchant ID

UltraCartShoppingCartId - Cart ID

The customer must be logged in.
Path Parametersnone
Query Parameters

none


Headers

none


Receives Jsonnone
Returns JsonArray of CreditCard objects

The card number is not returned (only a mask)

Example


  this.getCreditCards = function (options) {
    options = options || {};
    var creditCards = [];
    jQuery.ajax({
      url: '/rest/myaccount/creditCards',
      type: 'get',
      async: (options.success || options.failure) ? true : false,
      headers: { "cache-control": "no-cache" },
      cache: false,
      dataType: 'json'
    }).done(function (result) {
              creditCards = result;
              if (options.success) {
                options.success(creditCards);
              }
            })
            .fail(function (jqXHR, textStatus, errorThrown) {
              if (options.failure) {
                options.failure(jqXHR, textStatus, errorThrown);
              }
            });
    return creditCards;
  };




/rest/myaccount/creditCards/{id}

Method
GET
Comments
Description

returns a credit card record


Cookies

UltraCartMerchantID = Merchant ID

UltraCartShoppingCartId - Cart ID

The customer must be logged in.
Path Parametersidcredit card identifier  (not card number)
Query Parameters

none


Headers

none


Receives Jsonnone
Returns JsonCreditCard object

The card number is not returned (only a mask)

Example


  this.getCreditCard = function (id, options) {
    options = options || {};
    var creditCard = null;
    jQuery.ajax({
      url: '/rest/myaccount/creditCards/' + id,
      type: 'get',
      async: (options.success || options.failure) ? true : false,
      headers: { "cache-control": "no-cache" },
      cache: false,
      dataType: 'json'
    }).done(function (result) {
              creditCard = result;
              if (options.success) {
                options.success(creditCard);
              }
            })
            .fail(function (jqXHR, textStatus, errorThrown) {
              if (options.failure) {
                options.failure(jqXHR, textStatus, errorThrown);
              }
            });
    return creditCard;
  };





/rest/myaccount/creditCards

Method
POST
Comments
Description

adds a credit card


Cookies

UltraCartMerchantID = Merchant ID

UltraCartShoppingCartId - Cart ID

Customer must be logged in to perform this operation
Path Parametersnone
Query Parameters

none


Headers

none


Receives JsonCreditCard object
Returns JsonCreditCard object

the return object will contain the record id (unique identifier) 

Any field violations (exceeded length, missing fields) will return a 400 Bad Request.

 If the card number already exists, a 400 Bad Request is returned.

The card number is not returned (only a mask)

Example


  this.insertCreditCard = function (creditCard, options) {
    options = options || {};
    var insertedCard = null; // will contain oid
    jQuery.ajax({
      url: '/rest/myaccount/creditCards',
      type: 'post',
      data: JSON.stringify(creditCard),
      async: (options.success || options.failure) ? true : false,
      headers: { "cache-control": "no-cache" },
      cache: false,
      contentType: 'application/json; charset=UTF-8',
      dataType: 'json'
    }).done(function (result) {
              insertedCard = result;
              if (options.success) {
                options.success(insertedCard);
              }
            })
            .fail(function (jqXHR, textStatus, errorThrown) {
              if (options.failure) {
                options.failure(jqXHR, jqXHR, textStatus, errorThrown);
              }
            });
    return insertedCard;
  };



/rest/myaccount/creditCards/{id}

Method
PUT
Comments
Description

updates a credit card


Cookies

UltraCartMerchantID = Merchant ID

UltraCartShoppingCartId - Cart ID


Path Parametersidcredit card record identifier  (not card number)
Query Parameters

none


Headers

none


Receives JsonCreditCard objectThe card number is only updated if it contains a valid card. If the mask is returned or an empty field returned, the card number is not updated. 
Returns JsonCreditCard object

If the card number is updated to a card that already exists, a 400 Bad Request is returned.

Example


  this.updateCreditCard = function (creditCard, options) {
    options = options || {};
    var updatedCard = null;
    jQuery.ajax({
      url: '/rest/myaccount/creditCards/' + creditCard.id,
      type: 'put',
      data: JSON.stringify(creditCard),
      async: (options.success || options.failure) ? true : false,
      headers: { "cache-control": "no-cache" },
      cache: false,
      contentType: 'application/json; charset=UTF-8',
      dataType: 'json'
    }).done(function (result) {
              updatedCard = result;
              if (options.success) {
                options.success(updatedCard);
              }
            })
            .fail(function (jqXHR, textStatus, errorThrown) {
              if (options.failure) {
                options.failure(jqXHR, textStatus, errorThrown);
              }
            });
    return updatedCard;
  };




/rest/myaccount/creditCards/{id}

Method
DELETE
Comments
Description

deletes a credit card


Cookies

UltraCartMerchantID = Merchant ID

UltraCartShoppingCartId - Cart ID

Customer must be logged in to delete an address
Path Parametersidcredit card identifier  (not card number)
Query Parameters

none


Headers

none


Receives Jsonnone
Returns Jsonnone

204 No Content returned on success

Example


  this.deleteCreditCard = function (creditCard, options) {
    options = options || {};
    jQuery.ajax({
      url: '/rest/myaccount/creditCards/' + creditCard.id,
      type: 'delete',
      data: JSON.stringify(creditCard),
      async: (options.success || options.failure) ? true : false,
      headers: { "cache-control": "no-cache" },
      cache: false,
      contentType: 'application/json; charset=UTF-8',
      dataType: 'json'
    }).done(function () {
              if (options.success) {
                options.success();
              }
            })
            .fail(function (jqXHR, textStatus, errorThrown) {
              if (options.failure) {
                options.failure(textStatus, errorThrown);
              }
            });
  };





/rest/myaccount/orders

Method
GET
Comments
Description

returns orders belonging to customer


Cookies

UltraCartMerchantID = Merchant ID

UltraCartShoppingCartId - Cart ID

The customer must be logged in.
Path Parametersnone
Query Parameters

pageNumber

pageSize

search

_filterTime

pagination number

number of records per page (max is 10)

order id, item id, or item description search term

One of the following values:

last30days

last6months

year-XXXX

Headers

Returned headers:

uc-pagination-page-size

uc-pagination-page-number

uc-pagination-total-records

uc-pagination-total-pages


page size of result set

page number of result set

total number of records found

total number of pages found

Receives Jsonnone
Returns JsonArray of Order objects


Example


    /**
   * returns back pagination of orders, the success callback will
   * receive 1) orders, 2) pagination object (pageSize,pageNumber,totalRecords,totalPages)
   * @param [options] success and failure callbacks, 'pageNumber' and 'pageSize'
   * @return Object no callbacks specified, this returns back an object containing 'orders' and 'pagination' of orders (on success), else null
   */
  this.getOrders = function (options) {
    options = options || {};

    var data = {};
    data['pageNumber'] = options.pageNumber || '';
    data['pageSize'] = options.pageSize || '';
//    data['searchString'] = options.search || '';
    data['_filterTime'] = options.filter || '';
    var orders = [];
    var pagination = {};
    jQuery.ajax({
      url: '/rest/myaccount/orders',
      type: 'get',
      data: data,
      async: (options.success || options.failure) ? true : false,
      headers: { "cache-control": "no-cache" },
      cache: false,
      dataType: 'json'
    }).done(function (result, textStatus, jqXHR) {
              orders = result;
              pagination['pageSize'] = parseInt(jqXHR.getResponseHeader('uc-pagination-page-size'));
              pagination['pageNumber'] = parseInt(jqXHR.getResponseHeader('uc-pagination-page-number'));
              pagination['totalRecords'] = parseInt(jqXHR.getResponseHeader('uc-pagination-total-records'));
              pagination['totalPages'] = parseInt(jqXHR.getResponseHeader('uc-pagination-total-pages'));
              if (options.success) {
                options.success(orders, pagination);
              }
            })
            .fail(function (jqXHR, textStatus, errorThrown) {
              if (options.failure) {
                options.failure(textStatus, errorThrown);
              }
            });
    return {orders: orders, pagination: pagination};
  };




/rest/myaccount/orders/{orderId}

Method
GET
Comments
Description

returns an order


Cookies

UltraCartMerchantID = Merchant ID

UltraCartShoppingCartId - Cart ID

The customer must be logged in.
Path ParametersorderIdOrder ID
Query Parameters

none


Headers

none


Receives Jsonnone
Returns JsonOrder object

404 if order is not found.

Example


    this.getOrder = function (orderId, options) {
    options = options || {};

    var order = null;
    jQuery.ajax({
      url: '/rest/myaccount/orders/' + orderId,
      async: (options.success || options.failure) ? true : false,
      headers: { "cache-control": "no-cache" },
      cache: false,
      dataType: 'json'
    }).done(function (result) {
              order = result;
              if (options.success) {
                options.success(order);
              }
            })
            .fail(function (jqXHR, textStatus, errorThrown) {
              if (options.failure) {
                options.failure(textStatus, errorThrown);
              }
            });
    return order;
  };



/rest/myaccount/orders/{orderId}/tracking

Method
GET
Comments
Description

returns an order tracking information


Cookies

UltraCartMerchantID = Merchant ID

UltraCartShoppingCartId - Cart ID

The customer must be logged in.
Path ParametersorderIdOrder ID
Query Parameters

none


Headers

none


Receives Jsonnone
Returns JsonArray of OrderTracking objects

empty array if no tracking available.

Example


  this.getOrderTracking = function (orderId, options) {
    options = options || {};
    var tracking = null;
    jQuery.ajax({
      url: '/rest/myaccount/orders/' + orderId + "/tracking",
      async: (options.success || options.failure) ? true : false,
      headers: { "cache-control": "no-cache" },
      cache: false,
      dataType: 'json'
    }).done(function (result) {
              tracking = result;
              if (options.success) {
                options.success(tracking);
              }
            })
            .fail(function (jqXHR, textStatus, errorThrown) {
              if (options.failure) {
                options.failure(textStatus, errorThrown);
              }
            });
    return tracking;
  };


/rest/myaccount/orders/{orderId}/case

Method
GET
Comments
Description

returns a case object for an order

See Case Management to better understand what a case is 

Cookies

UltraCartMerchantID = Merchant ID

UltraCartShoppingCartId - Cart ID

The customer must be logged in.
Path ParametersorderIdOrder ID
Query Parameters

none


Headers

none


Receives Jsonnone
Returns JsonCase object

empty object (NOT a 404) if no case created yet for this object.

case actions are not returned (internal use only)

Example


   this.getOrderCase = function (orderId, options) {
    options = options || {};
    var orderCase = null;
    jQuery.ajax({
      url: '/rest/myaccount/orders/' + orderId + "/case",
      type: 'get',
      async: (options.success || options.failure) ? true : false,
      headers: { "cache-control": "no-cache" },
      cache: false,
      dataType: 'json'
    }).done(function (result) {
              if (result && result.caseOid) {
                orderCase = result;
              }
              if (options.success) {
                options.success(orderCase);
              }
            })
            .fail(function (jqXHR, textStatus, errorThrown) {
              if (options.failure) {
                options.failure(jqXHR, textStatus, errorThrown);
              }
            });
    return orderCase;
  };


/rest/myaccount/orders/{orderId}/case

Method
POST
Comments
Description

inserts a case object for an order

See Case Management to better understand what a case is 

Cookies

UltraCartMerchantID = Merchant ID

UltraCartShoppingCartId - Cart ID

The customer must be logged in.
Path ParametersorderIdOrder ID
Query Parameters

none


Headers

none


Receives JsonCase Object

 The case must have one and only one message. A case can't exist without customer initiated feedback.

If no message is supplied, a 400 Bad Request is returned.

Returns JsonCase object

contains record identifier as well as submitted fields.

Example


    this.insertOrderCase = function (orderId, orderCase, options) {
    options = options || {};
    jQuery.ajax({
      url: '/rest/myaccount/orders/' + orderId + "/case",
      data: JSON.stringify(orderCase),
      type: 'post',
      async: (options.success || options.failure) ? true : false,
      headers: { "cache-control": "no-cache" },
      cache: false,
      dataType: 'json',
      contentType: 'application/json; charset=UTF-8'
    }).done(function (result) {
              if (result) {
                orderCase = result;
              }
              if (options.success) {
                options.success(orderCase);
              }
            })
            .fail(function (jqXHR, textStatus, errorThrown) {
              if (options.failure) {
                options.failure(jqXHR, textStatus, errorThrown);
              }
            });
    return orderCase;
  };



/rest/myaccount/orders/{orderId}/case/messages

Method
GET
Comments
Description

returns all messages for the case associated with an order

See Case Management to better understand what a case is 

Cookies

UltraCartMerchantID = Merchant ID

UltraCartShoppingCartId - Cart ID

The customer must be logged in.
Path ParametersorderIdOrder ID
Query Parameters

none


Headers

none


Receives Jsonnone
Returns JsonArray of CaseMessage

if order doesn't exist, a 404 is returned.

If no case exists, a 404 is returned.


Example


   this.getOrderCaseMessages = function (orderId, options) {
    options = options || {};
    var messages = [];
    jQuery.ajax({
      url: '/rest/myaccount/orders/' + orderId + "/case/messages",
      type: 'get',
      async: (options.success || options.failure) ? true : false,
      headers: { "cache-control": "no-cache" },
      cache: false,
      dataType: 'json'
    }).done(function (result) {
              if (result) {
                messages = result;
              }
              if (options.success) {
                options.success(messages);
              }
            })
            .fail(function (jqXHR, textStatus, errorThrown) {
              if (options.failure) {
                options.failure(jqXHR, textStatus, errorThrown);
              }
            });
    return messages;
  };


/rest/myaccount/orders/{orderId}/case/messages

Method
POST
Comments
Description

inserts a case message object for a case

See Case Management to better understand what a case is 

This will trigger an email to customer service.

Cookies

UltraCartMerchantID = Merchant ID

UltraCartShoppingCartId - Cart ID

The customer must be logged in.
Path ParametersorderIdOrder ID
Query Parameters

none


Headers

none


Receives JsonCaseMessage Object

If this order id doesn't exist, a 404 is returned.

If no case exists for this order, a 400 Bad Request is returned.

If no message is supplied, a 400 Bad Request is returned.

Returns JsonCase object

contains record identifier as well as submitted fields.

Example


    this.insertOrderCaseMessage = function (orderId, messageText, options) {
    options = options || {};
    var orderCaseMessage = {message: messageText}; // this is all that's needed to insert message.
    jQuery.ajax({
      url: '/rest/myaccount/orders/' + orderId + "/case/messages",
      data: JSON.stringify(orderCaseMessage),
      type: 'post',
      async: (options.success || options.failure) ? true : false,
      headers: { "cache-control": "no-cache" },
      cache: false,
      dataType: 'json',
      contentType: 'application/json; charset=UTF-8'
    }).done(function (result) {
              if (result) {
                orderCaseMessage = result;
              }
              if (options.success) {
                options.success(orderCaseMessage);
              }
            })
            .fail(function (jqXHR, textStatus, errorThrown) {
              if (options.failure) {
                options.failure(jqXHR, textStatus, errorThrown);
              }
            });
    return orderCaseMessage;
  };




/rest/myaccount/notReviewedYet

Method
GET
Comments
Description

returns a distinct list of purchased items not yet reviewed.


Cookies

UltraCartMerchantID = Merchant ID

UltraCartShoppingCartId - Cart ID

The customer must be logged in.
Path Parametersnone
Query Parameters

pageNumber

pageSize


pagination number

number of records per page (max is 10)

Headers

Returned headers:

uc-pagination-page-size

uc-pagination-page-number

uc-pagination-total-records

uc-pagination-total-pages


page size of result set

page number of result set

total number of records found

total number of pages found

Receives Jsonnone
Returns JsonArray of NotReviewedItem objects


Example


  /**
   * returns back pagination of NotReviewedItem items, the success callback will
   * receive 1) review items, 2) pagination object (pageSize,pageNumber,totalRecords,totalPages)
   * @param [options] success and failure callbacks, 'pageNumber' and 'pageSize'
   * @return Object no callbacks specified, this returns back an object containing 'notYetReviewed' and 'pagination' of records (on success), else null
   */
  this.getNotReviewedYet = function (options) {
    options = options || {};
    var data = {};
    data['pageNumber'] = options.pageNumber || '';
    data['pageSize'] = options.pageSize || '';
    var notReviewedYet = [];
    var pagination = {};
    jQuery.ajax({
      url: '/rest/myaccount/notReviewedYet',
      type: 'get',
      data: data,
      async: (options.success || options.failure) ? true : false,
      headers: { "cache-control": "no-cache" },
      cache: false,
      dataType: 'json'
    }).done(function (result, textStatus, jqXHR) {
              notReviewedYet = result;
              pagination['pageSize'] = parseInt(jqXHR.getResponseHeader('uc-pagination-page-size'));
              pagination['pageNumber'] = parseInt(jqXHR.getResponseHeader('uc-pagination-page-number'));
              pagination['totalRecords'] = parseInt(jqXHR.getResponseHeader('uc-pagination-total-records'));
              pagination['totalPages'] = parseInt(jqXHR.getResponseHeader('uc-pagination-total-pages'));
              if (options.success) {
                options.success(notReviewedYet, pagination);
              }
            })
            .fail(function (jqXHR, textStatus, errorThrown) {
              if (options.failure) {
                options.failure(textStatus, errorThrown);
              }
            });
    return {notReviewedYet: notReviewedYet, pagination: pagination};
  };



/rest/myaccount/orders

Method
GET
Comments
Description

returns a list of reviews the customer has submitted


Cookies

UltraCartMerchantID = Merchant ID

UltraCartShoppingCartId - Cart ID

The customer must be logged in.
Path Parametersnone
Query Parameters

pageNumber

pageSize

pagination number

number of records per page (max is 10)

Headers

Returned headers:

uc-pagination-page-size

uc-pagination-page-number

uc-pagination-total-records

uc-pagination-total-pages


page size of result set

page number of result set

total number of records found

total number of pages found

Receives Jsonnone
Returns JsonArray of ReviewedItem objects


Example


  /**
   * returns back pagination of ReviewedItem items, the success callback will
   * receive 1) review items, 2) pagination object (pageSize,pageNumber,totalRecords,totalPages)
   * @param [options] success and failure callbacks, 'pageNumber' and 'pageSize'
   * @return Object no callbacks specified, this returns back an object containing 'reviews' and 'pagination' of records (on success), else null
   */
  this.getReviews = function (options) {
    options = options || {};
    var data = {};
    data['pageNumber'] = options.pageNumber || '';
    data['pageSize'] = options.pageSize || '';
    var reviews = [];
    var pagination = {};
    jQuery.ajax({
      url: '/rest/myaccount/reviews',
      type: 'get',
      data: data,
      async: (options.success || options.failure) ? true : false,
      headers: { "cache-control": "no-cache" },
      cache: false,
      dataType: 'json'
    }).done(function (result, textStatus, jqXHR) {
              reviews = result;
              pagination['pageSize'] = parseInt(jqXHR.getResponseHeader('uc-pagination-page-size'));
              pagination['pageNumber'] = parseInt(jqXHR.getResponseHeader('uc-pagination-page-number'));
              pagination['totalRecords'] = parseInt(jqXHR.getResponseHeader('uc-pagination-total-records'));
              pagination['totalPages'] = parseInt(jqXHR.getResponseHeader('uc-pagination-total-pages'));
              if (options.success) {
                options.success(reviews, pagination);
              }
            })
            .fail(function (jqXHR, textStatus, errorThrown) {
              if (options.failure) {
                options.failure(textStatus, errorThrown);
              }
            });
    return {reviews: reviews, pagination: pagination};
  };