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 | |
| 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:
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: |
| 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: 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
MyAccount
NotReviewedItem
Order
OrderTracking
OrderItem
ReviewedItem
TODO:
/myaccount/loggedIn (GET)
/myaccount/login (GET/POST)
/myaccount/logout (GET)
/myaccount/changePassword (POST)
/myaccount/forgotPassword (POST)
/myaccount/settings (GET)
/myaccount/settings (POST)
/myaccount/settings (PUT)
/myaccount/settings (DELETE)
/myaccount/shippingAddresses (GET)
/myaccount/shippingAddresses/id (GET)
/myaccount/shippingAddresses (POST)
/myaccount/shippingAddresses/id (PUT)
/myaccount/shippingAddresses/id (DELETE)
/myaccount/billingAddresses (GET)
/myaccount/billingAddresses/id (GET)
/myaccount/billingAddresses (POST)
/myaccount/billingAddresses/id (PUT)
/myaccount/billingAddresses/id (DELETE)
/myaccount/creditCards (GET)
/myaccount/creditCards/id (GET)
/myaccount/creditCards (POST)
/myaccount/creditCards/id (PUT)
/myaccount/creditCards/id (DELETE)
/myaccount/orders (GET)
/myaccount/orders/orderId (GET)
/myaccount/orders/orderId/tracking (GET)
/myaccount/orders/orderId/case (GET)
/myaccount/orders/orderId/case (POST)
/myaccount/notReviewedYet (GET)
/myaccount/reviews (GET)