/
UltraCart REST MyAccount API

UltraCart REST MyAccount API

Oct 07, 2025



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



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.

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

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

Yes

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.

lastUsedDate

string

No

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

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.  

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