Table of Contents

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.

...

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

Tip

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

Info

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:

Code Block

language	javascript
theme	DJango
language	javascript
linenumbers	true

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.

Info

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

Field

Type

Required

Comment

id

int

Yes*

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!

company

string(50)

No


firstName	string(30)	Yes


lastName	string(30)	Yes


address1	string(32)	Yes


address2	string(32)	No


city	string(32)	Yes


state	string(32)	Yes


postalCode	string(20)	Yes	In the US, this is known as 'zip code'
country	string(32)	Yes


title	string(50)	No


dayPhone	string(25)	No


eveningPhone	string(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.

Field	Type	Required	Edit/Update	Comment
caseOid	string	Yes*	No	Object Identifier. This will always be returned from the server. Do not create one on your own (won't be accepted).
merchantId	string(5)	Yes	No	not required during insert. it's collected from cookies
orderId	string(30)	Yes	No


email	string(100)	Yes	Yes	order email is used if missing
customerProfileId	string	Yes	No	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.
creationDate	string	No	No	ISO-8601 format. very handy when used with something like moment.js Assigned during case creation. Immutable afterwards.
creationDateFormatted	string	No	No	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.
subject	string(200)	Yes	Yes	This 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).
status	string(50)	Yes	Yes	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.
lastUpdateDate	string	No	No	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.
lastUpdateDateFormatted	string	No	No	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.
messages	CaseMessage[ ]	No	Insert	an 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.

Field	Type	Required	Edit/Update	Comment
caseMessageOid	String	Yes*	No	Object Identifier. This will always be returned from the server.
caseOid	string	Yes*	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.
message	string(2000)	Yes	No	the main body of the email
messageSender	string(20)	No	No	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`
messageDate	string	No	No	ISO-8601 format. very handy when used with something like moment.js Assigned during message creation. Immutable afterwards.
messageDateFormatted	string	No	No	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.

Field	Type	Required	Edit/Update	Comment
oldPassword	string(30)	Yes*	No	old password
newPassword	string(30)	Yes*	No	new password

CreditCard

A credit card object used on the payment pages.

Warning
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.

Field Type Required Edit/Update Comment

merchantId string(30) Yes* No old password

customerProfileId

string(30)

Yes*

No

new password

id id Yes* No an 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.

cardType

string

Yes

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.

cardExpMonth int Yes Yes 1-12 corresponding to the 12 months of Jan-Feb

cardExpYear int Yes Yes Four digit year.

cardNumber

string

Yes

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

Warning

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.

lastUsedDate

string

No

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.

lastUsedDateFormatted

string

No

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.

Field	Type	Required	Edit/Update	Comment
merchantId	string(50)	Yes	N/A


email	string(100)	Yes	N/A


password	string(30)	Yes	N/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.

...

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

Field	Type	Required	Comment
merchantId	string(5)	Yes

customerProfileId

int

Yes*

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!

title

string(50)

No


company	string(50)	No


firstName	string(30)	Yes


lastName	string(30)	Yes


address1	string(32)	Yes


address2	string(32)	No


city	string(32)	Yes


state	string(32)	Yes


postalCode	string(20)	Yes	In the US, this is known as 'zip code'
country	string(32)	Yes


title	string(50)	No


dayPhone	string(25)	No


eveningPhone	string(25)	No


fax	string(32)	No	Does anyone even use fax machines any more? If so, this field is for them.
taxId	string(15)	No	Very popular field for wholesale customers.
password	string(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.

Field	Type	Comment
merchantId	string(5)


itemId	string(30)	The merchant item id.
merchantItemOid	string	An 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.
lastOrderDate	string	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.
lastOrderDateFormatted	string	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.
item	Item	A complex item containing all the details about the item. See its page for specifics.

Order

Tip
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.

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

Google Checkout

Amazon SC
SkyMall
Smart Bargains

Dwolla

Sofort

`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.

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 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.

...

OrderTracking

Read-Only tracking information for an order

Field	Type	Comment
merchantId	string	Your merchant id
orderId	string	The order id
hasTrackingUrl	boolean	true 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
trackingNumber	string	The tracking number
trackingUrl	string	The full url to the shipper's web site.

ReviewedItem

This read-only object contains an item review.

Field	Type	Comment
itemId	string	the item id of the item reviewed
item	Item	A complex item containing all the details about the item. See its page for specifics.
reviewOid	integer	review record's internal identifier
merchantId	string	the merchant id (your merchant id)
customerProfileId	integer	customer's internal identifier
merchantItemOid	integer	item's internal identifier
overall	number	1-5 The overall rating of the item. This should be featured prominently.
ratingName1	string	The name (category) of this rating. Configured by the merchant. Examples: Ease of Use, Price, Durability, etc.
ratingName2	string	The name (category) of this rating.
ratingName3	string	The name (category) of this rating.
ratingName4	string	The name (category) of this rating.
ratingName5	string	The name (category) of this rating.
ratingName6	string	The name (category) of this rating.
ratingName7	string	The name (category) of this rating.
ratingName8	string	The name (category) of this rating.
ratingName9	string	The name (category) of this rating.
ratingName10	string	The name (category) of this rating.
ratingScore1	number	1-5, the rating for the associated rating name.
ratingScore2	number	1-5, the rating for the associated rating name.
ratingScore3	number	1-5, the rating for the associated rating name.
ratingScore4	number	1-5, the rating for the associated rating name.
ratingScore5	number	1-5, the rating for the associated rating name.
ratingScore6	number	1-5, the rating for the associated rating name.
ratingScore7	number	1-5, the rating for the associated rating name.
ratingScore8	number	1-5, the rating for the associated rating name.
ratingScore9	number	1-5, the rating for the associated rating name.
ratingScore10	number	1-5, the rating for the associated rating name.
recommendToFriend	boolean	true if the customer would recomment the item to a friend.
title	string	The title of the review
review	string	The review itself. These are the customer's comments.
statusCode	string	`Approved`, `Rejected`, or `Unapproved`
featured	boolean	true if the merchant has chosen to feature this review
recommendStoreToFriend	boolean	true if the customer would recommend your store to friends.
storeFeedback	string	any comments the customer had for your store
submittedDate	string	ISO-8601 format. very handy when used with something like moment.js Contains the date when the review was submitted
submittedDateFormatted	string	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.
helpfulYesVotes	integer	the number of times other customers have marked a review as helpful.
helpfulNoVotes	integer	the number of times other customers have marked a review as unhelpful.

...

MyAccount REST API

/rest/myaccount/loggedIn

Method

GET

Comments

Description

returns 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:

Code Block

language	javascript

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 Parameters	`none`


Query Parameters	none


Headers	none


Receives Json	none

Returns Json

MyAccount 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

Code Block

language

code

javascript
theme	DJango

language

javascript

linenumbers	true

  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;
  };

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 Parameters none

Query Parameters

For GET:

merchantId

email

password

For POST:

none


Headers	none


Receives Json	CustomerCredentials

Returns Json

MyAccount 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

Code Block

language

code

javascript
theme	DJango

languagejavascript


linenumbers	true

  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 Parameters	`none`


Query Parameters	none


Headers	none


Receives Json	none


Returns Json	none

Example

Code Block

language

code

javascript
theme	DJango

language

javascript

linenumbers	true

    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 Parameters none


Query Parameters	none


Headers	none


Receives Json	ChangePasswordRequest

Returns Json

nothing (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

Code Block

language

code

javascript
theme	DJango

languagejavascript

linenumbers	true

  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 Parameters	`none`


Query Parameters	merchantId	Optional in place of cookie
Headers	none


Receives Json	String (email)	Just a single email address as a string
Returns Json	Plain text	The string `"Your password was emailed to " + email` is returned on success.
Example

Code Block

language

code

javascript
theme	DJango

languagejavascript


linenumbers	true

  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 Parameters none


Query Parameters	`none`

Receives


Headers	`none`

Receives Json none


Returns Json	MyAccount object	password is not returned. a string of asterisks is returned instead.
Example

Code Block

language

code

javascript
theme	DJango

languagejavascript

linenumbers	true

   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 Parameters none

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 Json	MyAccount object

Returns Json

MyAccount 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

Code Block

language

code

javascript
theme	DJango

languagejavascript


linenumbers	true

    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 Parameters	`none`


Query Parameters	`none`


Headers	`none`

Receives Json

MyAccount object

Tip

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 Json

MyAccount object

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

Example

Code Block

language

code

javascript
theme	DJango

languagejavascript


linenumbers	true

  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 Parameters none


Query Parameters	`none`


Headers	`none`

Receives Json

none

The settings object is not required to delete a profile. The cart id is sufficient.

Returns Json

none

204 No Content returned on success

Example

Code Block

language

code

javascript
theme	DJango

language

javascript

linenumbers	true

  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 Parameters none


Query Parameters	`none`


Headers	`none`


Receives Json	`none`


Returns Json	Array of Address objects

Example

Code Block

language

code

javascript
theme	DJango

languagejavascript


linenumbers	true

  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 Parameters	`id`	address record identifier
Query Parameters	`none`


Headers	`none`


Receives Json	`none`


Returns Json	Address object

Example

Code Block

language

code

javascript
theme	DJango

languagejavascript

linenumbers	true

   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 Parameters none


Query Parameters	`none`


Headers	`none`


Receives Json	Address object

Returns Json

Address 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

Code Block

language

code

javascript
theme	DJango

language

javascript

linenumbers	true

  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 Parameters	`id`	shipping address record identifier
Query Parameters	`none`


Headers	`none`


Receives Json	MyAccount object

Returns Json

MyAccount object

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

Example

Code Block

language

code

javascript
theme	DJango

languagejavascript

linenumbers	true

   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 Parameters	`id`	address record identifier
Query Parameters	`none`


Headers	`none`


Receives Json	none


Returns Json	none	204 No Content returned on success
Example

Code Block

language

code

javascript
theme	DJango

languagejavascript


linenumbers	true

  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 Parameters none


Query Parameters	`none`


Headers	`none`


Receives Json	`none`


Returns Json	Array of Address objects

Example

Code Block

language

code

javascript
theme	DJango

languagejavascript

linenumbers	true

  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 Parameters	`id`	address record identifier
Query Parameters	`none`


Headers	`none`


Receives Json	`none`


Returns Json	Address object

Example

Code Block

language

code

javascript
theme	DJango

language

javascript

linenumbers	true

  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 Parameters none


Query Parameters	`none`


Headers	`none`


Receives Json	Address object

Returns Json

Address 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

Code Block

language

code

javascript
theme	DJango

language

javascript

linenumbers	true

  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 Parameters	`id`	billing address record identifier
Query Parameters	`none`


Headers	`none`


Receives Json	MyAccount object

Returns Json

MyAccount object

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

Example

Code Block

language

code

javascript
theme	DJango

languagejavascript

linenumbers	true

  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 Parameters	`id`	address record identifier
Query Parameters	`none`


Headers	`none`


Receives Json	none

Returns Json

none

204 No Content returned on success

Example

Code Block

language

code

javascript
theme	DJango

languagejavascript


linenumbers	true

  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 Parameters none


Query Parameters	`none`


Headers	`none`


Receives Json	`none`

Returns Json

Array of CreditCard objects

The card number is not returned (only a mask)

Example

Code Block

language

code

javascript
theme	DJango

languagejavascript

linenumbers	true

  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 Parameters	`id`	credit card identifier (not card number)
Query Parameters	`none`


Headers	`none`


Receives Json	`none`


Returns Json	CreditCard object	The card number is not returned (only a mask)
Example

Code Block

language

code

javascript
theme	DJango

language

javascript

linenumbers	true

  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 Parameters none


Query Parameters	`none`


Headers	`none`


Receives Json	CreditCard object

Returns Json

CreditCard 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

Code Block

language

code

javascript
theme	DJango

language

javascript

linenumbers	true

  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 Parameters	`id`	credit card record identifier (not card number)
Query Parameters	`none`


Headers	`none`


Receives Json	CreditCard object	The 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 Json	CreditCard object	If the card number is updated to a card that already exists, a 400 Bad Request is returned.
Example

Code Block

language

code

javascript
theme	DJango

languagejavascript


linenumbers	true

  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 Parameters	`id`	credit card identifier (not card number)
Query Parameters	`none`


Headers	`none`


Receives Json	none

Returns Json

none

204 No Content returned on success

Example

Code Block

language

code

javascript
theme	DJango

language

javascript

linenumbers	true

  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 Parameters none

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 Json none


Returns Json	Array of Order objects

Example

Code Block

language

code

javascript
theme	DJango

languagejavascript


linenumbers	true

    /**
   * 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 Parameters	`orderId`	Order ID
Query Parameters	`none`


Headers	`none`


Receives Json	`none`

Returns Json

Order object

404 if order is not found.

Example

Code Block

language

code

javascript
theme	DJango

languagejavascript

linenumbers	true

    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 Parameters	`orderId`	Order ID
Query Parameters	`none`


Headers	`none`


Receives Json	`none`


Returns Json	Array of OrderTracking objects	empty array if no tracking available.
Example

Code Block

language

code

javascript
theme	DJango

languagejavascript


linenumbers	true

  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 Parameters	`orderId`	Order ID
Query Parameters	`none`


Headers	`none`


Receives Json	`none`

Returns Json

Case object

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

case actions are not returned (internal use only)

Example

Code Block

language

code

javascript
theme	DJango

languagejavascript

linenumbers	true

   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 Parameters	`orderId`	Order ID
Query Parameters	`none`


Headers	`none`

Receives Json

Case 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 Json

Case object

contains record identifier as well as submitted fields.

Example

Code Block

language

code

javascript
theme	DJango

languagejavascript

linenumbers	true

    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 Parameters	`orderId`	Order ID
Query Parameters	`none`


Headers	`none`


Receives Json	`none`

Returns Json

Array of CaseMessage

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

If no case exists, a 404 is returned.

Example

Code Block

language

code

javascript
theme	DJango

language

javascript

linenumbers	true

   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 Parameters	`orderId`	Order ID
Query Parameters	`none`


Headers	`none`


Receives Json	`CaseMessage 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 Json	Case object	contains record identifier as well as submitted fields.
Example

Code Block

language

code

javascript
theme	DJango

languagejavascript

linenumbers	true

    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 Parameters none

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 Json none


Returns Json	Array of NotReviewedItem objects

Example

Code Block

language

code

javascript
theme	DJango

languagejavascript

linenumbers	true

  /**
   * 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 Parameters none

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 Json none


Returns Json	Array of ReviewedItem objects

Example

Code Block

language

code

javascript
theme	DJango

languagejavascript


linenumbers	true

  /**
   * 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};
  };

...

Page Comparison

Versions Compared

Old Version 25

New Version Current

Key

Introduction

Address

Case

Case Message

ChangePasswordRequest

CreditCard

MyAccount

NotReviewedItem

Order

Order Labels

OrderTracking

ReviewedItem

MyAccount REST API

/rest/myaccount/loggedIn

/rest/myaccount/login

/rest/myaccount/logout

/rest/myaccount/changePassword

/rest/myaccount/forgotPassword

/rest/myaccount/settings

/rest/myaccount/settings

/rest/myaccount/settings

/rest/myaccount/settings

/rest/myaccount/shippingAddresses

/rest/myaccount/shippingAddresses/{id}

/rest/myaccount/shippingAddresses

//rest/myaccount/shippingAddresses/{id}

/rest/myaccount/shippingAddresses/{id}

/rest/myaccount/billingAddresses

/rest/myaccount/billingAddresses/{id}

/rest/myaccount/billingAddresses

/rest/myaccount/billingAddresses/{id}

/rest/myaccount/billingAddresses/{id}

/rest/myaccount/creditCards

/rest/myaccount/creditCards/{id}

/rest/myaccount/creditCards

/rest/myaccount/creditCards/{id}

/rest/myaccount/creditCards/{id}

/rest/myaccount/orders

/rest/myaccount/orders/{orderId}

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

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

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

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

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

/rest/myaccount/notReviewedYet

/rest/myaccount/orders